Arvados-DCO-1.1-Signed-off-by: Radhika Chippada <radhika@curoverse.com>
[arvados.git] / doc / user / topics / run-command.html.textile.liquid
1 ---
2 layout: default
3 navsection: userguide
4 title: "run-command reference"
5 ...
6 {% comment %}
7 Copyright (C) The Arvados Authors. All rights reserved.
8
9 SPDX-License-Identifier: CC-BY-SA-3.0
10 {% endcomment %}
11
12 {% include 'pipeline_deprecation_notice' %}
13
14 The @run-command@ crunch script enables you run command line programs.
15
16 {% include 'tutorial_expectations_workstation' %}
17
18 h1. Using run-command
19
20 The basic @run-command@ process evaluates its inputs and builds a command line, executes the command, and saves the contents of the output directory back to Keep.  For large datasets, @run-command@ can schedule concurrent tasks to execute the wrapped program over a range of inputs (see @task.foreach@ below.)
21
22 @run-command@ is controlled through the @script_parameters@ section of a pipeline component.  @script_parameters@ is a JSON object consisting of key-value pairs.  There are three categories of keys that are meaningful to run-command:
23 * The @command@ section defining the template to build the command line of task
24 * Special processing directives such as @task.foreach@ @task.cwd@ @task.vwd@ @task.stdin@ @task.stdout@
25 * User-defined parameters (everything else)
26
27 In the following examples, you can use "dry run mode" to determine the command line that @run-command@ will use without actually running the command.  For example:
28
29 <notextile>
30 <pre><code>~$ <span class="userinput">cd $HOME/arvados/crunch_scripts</span>
31 ~$ <span class="userinput">./run-command --dry-run --script-parameters '{
32   "command": ["echo", "hello world"]
33 }'</span>
34 run-command: echo hello world
35 </code></pre>
36 </notextile>
37
38 h2. Command template
39
40 The value of the "command" key is a list.  The first parameter of the list is the actual program to invoke, followed by the command arguments.  The simplest @run-command@ invocation simply runs a program with static parameters.  In this example, run "echo" with the first argument "hello world":
41
42 <pre>
43 {
44   "command": ["echo", "hello world"]
45 }
46 </pre>
47
48 Running this job will print "hello world" to the job log.
49
50 By default, the command will start with the current working directory set to the output directory.  Anything written to the output directory will be saved to Keep when the command is finished.  You can change the default working directory using @task.cwd@ and get the path to the output directory using @$(task.outdir)@ as explained below.
51
52 Items in the "command" list may include lists and objects in addition to strings.  Lists are flattened to produce the final command line.  JSON objects are evaluated as list item functions (see below).  For example, the following evaluates to @["echo", "hello", "world"]@:
53
54 <pre>
55 {
56   "command": ["echo", ["hello", "world"]]
57 }
58 </pre>
59
60 Finally, if "command" is a list of lists, it specifies a Unix pipeline where the standard output of the previous command is piped into the standard input of the next command.  The following example describes the Unix pipeline @cat foo | grep bar@:
61
62 <pre>
63 {
64   "command": [["cat", "foo"], ["grep", "bar"]]
65 }
66 </pre>
67
68 h2. Parameter substitution
69
70 The "command" list can include parameter substitutions.  Substitutions are enclosed in "$(...)" and may contain the name of a user-defined parameter.  In the following example, the value of "a" is "hello world"; so when "command" is evaluated, it will substitute "hello world" for "$(a)":
71
72 <pre>
73 {
74   "a": "c1bad4b39ca5a924e481008009d94e32+210/var-GS000016015-ASM.tsv.bz2",
75   "command": ["echo", "$(file $(a))"]
76 }
77 </pre>
78
79 table(table table-bordered table-condensed).
80 |_. Function|_. Action|
81 |$(file ...)       | Takes a reference to a file within an Arvados collection and evaluates to a file path on the local file system where that file can be accessed by your command.  Will raise an error if the file is not accessible.|
82 |$(dir ...)        | Takes a reference to an Arvados collection or directory within an Arvados collection and evaluates to a directory path on the local file system where that directory can be accessed by your command.  The path may include a file name, in which case it will evaluate to the parent directory of the file.  Uses Python's os.path.dirname(), so "/foo/bar" will evaluate to "/foo" but "/foo/bar/" will evaluate to "/foo/bar".  Will raise an error if the directory is not accessible. |
83 |$(basename&nbsp;...)   | Strip leading directory and trailing file extension from the path provided.  For example, $(basename /foo/bar.baz.txt) will evaluate to "bar.baz".|
84 |$(glob ...)       | Take a Unix shell path pattern (supports @*@ @?@ and @[]@) and search the local filesystem, returning the first match found.  Use together with $(dir ...) to get a local filesystem path for Arvados collections.  For example: $(glob $(dir $(mycollection)/*.bam)) will find the first .bam file in the collection specified by the user parameter "mycollection".  If there is more than one match, which one is returned is undefined.  Will raise an error if no matches are found.|
85 |$(task.tmpdir)|Designated temporary directory.  This directory will be discarded when the job completes.|
86 |$(task.outdir)|Designated output directory.  The contents of this directory will be saved to Keep when the job completes.  A symlink to a file in the keep mount will reference existing Keep blocks in your job output collection, with no data copying or duplication.|
87 |$(job.srcdir)|Path to the git working directory ($CRUNCH_SRC).|
88 |$(node.cores)|Number of CPU cores on the node.|
89 |$(job.uuid)|Current job uuid ($JOB_UUID)|
90 |$(task.uuid)|Current task uuid ($TASK_UUID)|
91
92 h3. Escape sequences
93
94 If your command includes a @$()@ sequence that shouldn't be interpreted by run-command&mdash;for example, because you're writing shell code that calls a subcommand&mdash;you can prevent run-command from interpreting it by placing a backslash in front of the @$@ character.  Note that JSON also uses backslash to escape characters, so you'll need to write two backslashes for run-command to see one after parsing the parameter.  This example uppercases all alphabetic characters in the "pattern" parameter before using it as a regular expression in grep:
95
96 <pre>{"command": ["bash", "-c", "grep \\$(echo '$(pattern)' | tr a-z A-Z) '$(input)'"]}</pre>
97
98 You can put a literal backslash in your command by escaping it with another backslash.  Ultimately this means that where the primary Unix command includes a single backslash, you'll need to write four backslashes: double the backslashes for run-command escaping, then double them again for JSON escaping.
99
100 <pre>{"command": ["grep", "\\\\bword\\\\b", "$(input)"]}</pre>
101
102 h2. List context
103
104 Where specified by the documentation, parameters may be evaluated in a "list context".  That means the value will evaluate to a list instead of a string.  Parameter values can be a static list, a path to a file, a path to a directory, or a JSON object describing a list context function.
105
106 If the value is a string, it is interpreted as a path.  If the path specifies a regular file, that file will be opened as a text file and produce a list with one item for each line in the file (end-of-line characters will be stripped).  If the path specifies a directory, produce a list containing all of the entries in the directory.  Note that parameter expansion is not performed on list items produced this way.
107
108 If the value is a static list, it will evaluate each item and return the expanded list.  Each item may be a string (evaluated for parameter substitution), a list (recursively evaluated), or a JSON object (indicating a list function, described below).
109
110 If the value is a JSON object, it is evaluated as a list function described below.
111
112 h2. List functions
113
114 When @run-command@ is evaluating a list (such as "command"), in addition to string parameter substitution, you can use list item functions.  In the following functions, you specify the name of a user parameter to act on (@"$(a)"@ in the first example); the value of that user parameter will be evaluated in a list context (as described above) to get the list value. Alternately, you can provide list value directly in line.  As an example, the following two fragments yield the same result:
115
116 <pre>
117 {
118   "a": ["alice", "bob"],
119   "command": ["echo", {"foreach": "$(a)",
120                        "var": "a_var",
121                        "command": ["--something", "$(a_var)"]}]
122 }
123 </pre>
124
125 <pre>
126 {
127   "command": ["echo", {"foreach": ["alice", "bob"],
128                        "var": "a_var",
129                        "command": ["--something", "$(a_var)"]}]
130 }
131 </pre>
132
133 Note: when you provide the list inline with "foreach" or "index", you must include the "var" parameter to specify the substitution variable name to use when evaluating the command fragment.
134
135 You can also nest functions.  This filters @["alice", "bob", "betty"]@ on the regular expression @"b.*"@ to get the list @["bob", "betty"]@, assigns @a_var@ to each value of the list, then expands @"command"@ to get @["--something", "bob", "--something", "betty"]@.
136
137 <pre>
138 {
139   "command": ["echo", {"foreach": {"filter": ["alice", "bob", "betty"],
140                                    "regex": "b.*"},
141                        "var": "a_var",
142                        "command": ["--something", "$(a_var)"]}]
143 }
144 </pre>
145
146 h3. foreach
147
148 The @foreach@ list item function (not to be confused with the @task.foreach@ directive) expands a command template for each item in the specified user parameter (the value of the user parameter is evaluated in a list context, as described above).  The following example will evaluate "command" to @["echo", "--something", "alice", "--something", "bob"]@:
149
150 <pre>
151 {
152   "a": ["alice", "bob"],
153   "command": ["echo", {"foreach": "$(a)",
154                        "var": "a_var",
155                        "command": ["--something", "$(a_var)"]}]
156 }
157 </pre>
158
159 h3. index
160
161 This function extracts a single item from a list.  The value of @index@ is zero-based (i.e. the first item is at index 0, the second item index 1, etc).  The following example will evaluate "command" to @["echo", "--something", "bob"]@:
162
163 <pre>
164 {
165   "a": ["alice", "bob"],
166   "command": ["echo", {"list": "$(a)",
167                        "var": "a_var",
168                        "index": 1,
169                        "command": ["--something", "$(a_var)"]}]
170 }
171 </pre>
172
173 h3. filter
174
175 Filter the list so that it only includes items that match a regular expression.  The following example will evaluate to @["echo", "bob"]@
176
177 <pre>
178 {
179   "a": ["alice", "bob"],
180   "command": ["echo", {"filter": "$(a)",
181                        "regex": "b.*"}]
182 }
183 </pre>
184
185 h3. group
186
187 Generate a list of lists, where items are grouped on common subexpression match.  Items which don't match the regular expression are excluded.  In the following example, the subexpression is @(a?)@, resulting in two groups, strings that contain the letter 'a' and strings that do not.  The following example evaluates to @["echo", "--group", "alice", "carol", "dave", "--group", "bob", "betty"]@:
188
189 <pre>
190 {
191   "a": ["alice", "bob", "betty", "carol", "dave"],
192   "b": {"group": "$(a)",
193         "regex": "[^a]*(a?).*"},
194   "command": ["echo", {"foreach": "$(b)",
195                        "var": "b_var",
196                        "command": ["--group", "$(b_var)"]}]
197 }
198 </pre>
199
200 h3. extract
201
202 Generate a list of lists, where items are split by subexpression match.  Items which don't match the regular expression are excluded.  The following example evaluates to @["echo", "--something", "c", "a", "rol", "--something", "d", "a", "ve"]@:
203
204 <pre>
205 {
206   "a": ["alice", "bob", "carol", "dave"],
207   "b": {"extract": "$(a)",
208         "regex": "(.+)(a)(.*)"},
209   "command": ["echo", {"foreach": "$(b)",
210                        "var": "b_var",
211                        "command": ["--something", "$(b_var)"]}]
212 }
213 </pre>
214
215 h3. batch
216
217 Generate a list of lists, where items are split into a batch size.  If the list does not divide evenly into batch sizes, the last batch will be short.  The following example evaluates to @["echo", "--something", "alice", "bob", "--something", "carol", "dave"]@
218
219 <pre>
220 {
221   "a": ["alice", "bob", "carol", "dave"],
222   "command": ["echo", {"foreach":{"batch": "$(a)",
223                                   "size": 2},
224                        "var": "a_var",
225                        "command": ["--something", "$(a_var)"]}]
226 }
227 </pre>
228
229 h2. Directives
230
231 Directives alter the behavior of run-command.  All directives are optional.
232
233 h3. task.cwd
234
235 This directive sets the initial current working directory in which your command will run.  If @task.cwd@ is not specified, the default current working directory is @task.outdir@.
236
237 h3. task.ignore_rcode
238
239 By Unix convention a task which exits with a non-zero return code is considered failed.  However, some programs (such as @grep@) return non-zero codes for conditions that should not be considered fatal errors.  Set @"task.ignore_rcode": true@ to indicate the task should always be considered a success regardless of the return code.
240
241 h3. task.stdin and task.stdout
242
243 Provide standard input and standard output redirection.
244
245 @task.stdin@ must evaluate to a path to a file to be bound to the standard input stream of the command.  When command describes a Unix pipeline, this goes into the first command.
246
247 @task.stdout@ specifies the desired file name in the output directory to save the content of standard output.  When command describes a Unix pipeline, this captures the output of the last command.
248
249 h3. task.env
250
251 Set environment variables for the command.  Accepts an object mapping environment variables to the desired values.  Parameter substitution is performed on values, but not on the environment variable names themselves.  Example usage:
252
253 <pre>
254 {
255   "command": ["/bin/sh", "-c", "echo $MY_ENV_VAR"],
256   "task.env": {
257     "MY_ENV_VAR": "Hello world!"
258   }
259 }
260 </pre>
261
262 h3. task.vwd
263
264 Background: because Keep collections are read-only, this does not play well with certain tools that expect to be able to write their outputs alongside their inputs (such as tools that generate indexes that are closely associated with the original file.)  The run-command's solution to this is the "virtual working directory".
265
266 @task.vwd@ specifies a Keep collection with the starting contents of the output directory.  @run-command@ will populate @task.outdir@ with directories and symlinks to mirror the contents of the @task.vwd@ collection.  Your command will then be able to both access its input files and write its output files from within @task.outdir@.  When the command completes, run-command will write the contents of the output directory, which will include the output of your command as well as symlinks to files in starting collection.  Note that files from the starting collection remain read-only and cannot be altered, but may be deleted or renamed.
267
268 h3. task.foreach
269
270 Using @task.foreach@, you can run your command concurrently over large datasets.
271
272 @task.foreach@ takes the names of one or more user-defined parameters.  The value of these parameters are evaluated in a list context.  @run-command@ then generates tasks based on the Cartesian product (i.e. all combinations) of the input lists.  The outputs of all tasks are merged to create the final output collection.  Note that if two tasks output a file in the same directory with the same name, that file will be concatenated in the final output.  In the following example, three tasks will be created for the "grep" command, based on the contents of user parameter "a":
273
274 <pre>
275 {
276   "command": ["echo", "$(a)"],
277   "task.foreach": "a",
278   "a": ["alice", "bob", "carol"]
279 }
280 </pre>
281
282 This evaluates to the commands:
283 <notextile>
284 <pre>
285 ["echo", "alice"]
286 ["echo", "bob"]
287 ["echo", "carol"]
288 </pre>
289 </notextile>
290
291 You can also specify multiple parameters:
292
293 <pre>
294 {
295   "a": ["alice", "bob"],
296   "b": ["carol", "dave"],
297   "task.foreach": ["a", "b"],
298   "command": ["echo", "$(a)", "$(b)"]
299 }
300 </pre>
301
302 This evaluates to the commands:
303
304 <pre>
305 ["echo", "alice", "carol"]
306 ["echo", "alice", "dave"]
307 ["echo", "bob", "carol"]
308 ["echo", "bob", "dave"]
309 </pre>
310
311 h1. Examples
312
313 The following is a single task pipeline using @run-command@ to run the bwa alignment tool to align a single paired-end read fastq sample.  The input to this pipeline is the reference genome and a collection consisting of two fastq files for the read pair.
314
315 <notextile>{% code 'run_command_simple_example' as javascript %}</notextile>
316
317 The following is a concurrent task pipeline using @run-command@ to run the bwa alignment tool to align a set of fastq reads over multiple samples.  The input to this pipeline is the reference genome and a collection consisting subdirectories for each sample, with each subdirectory containing pairs of fastq files for each set of reads.
318
319 <notextile>{% code 'run_command_foreach_example' as javascript %}</notextile>