doc/user/topics/arv-run.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Using arv-run"
   5 ...
   6
   7 The @arv-run@ command enables you create Arvados pipelines at the command line that fan out to multiple concurrent tasks across Arvado compute nodes.
   8
   9 {% include 'tutorial_expectations' %}
  10
  11 h1. Quick introduction
  12
  13 Run one @grep@ task per file, and redirect the output to output.txt
  14
  15 <notextile>
  16 <pre>
  17 $ <span class="userinput">cd ~/keep/by_id/3229739b505d2b878b62aed09895a55a+142</span>
  18 $ <span class="userinput">arv-run grep -H -n ATTGGAGGAAAGATGAGTGAC -- *.fastq \&gt; output.txt</span>
  19 Running pipeline qr1hi-d1hrv-mg3bju0u7r6w241
  20 </pre>
  21 </notextile>
  22
  23 h1. Usage
  24
  25 @arv-run@ takes a command or command pipeline, along with stdin and stdout redirection, and creates an Arvados pipeline to run the command.  The syntax is designed to mimic standard shell syntax, so it is usually necessary to quote the metacharacters < > and | as either \< \> and \| or '<' '>' and '|'.
  26
  27 @arv-run@ introspects the command line to determine which arguments are file inputs.  If you specify a file that is only available on the local filesystem, it will be first uploaded to Arvados, and then the command line will be rewritten to refer to the newly uploaded file.  @arv-run@ also works together with @arv-mount@ to identify if a file specified on the command line is part of an Arvados collection.  If so, the command line will be rewritten to refer to the file within the collection without any upload necessary.
  28
  29 @arv-run@ will parallelize on the files listed on the command line after @--@.  You may specify @--batch-size N@ after the @--@ but before listing any files to specify how many files to provide put on the command line for each task (see below for example).
  30
  31 You may use stdin @<@ redirection on multiple files.  This will create a separate task for each input file.
  32
  33 You are only permitted to supply a single file name for stdout @>@ redirection.  If there are multiple tasks, their output will be collated at the end of the pipeline.  Alternately, you may use "run-command":run-command.html parameter substitution in the file name to generate different filenames for each task.
  34
  35 Multiple commands connected by pipes all execute in the same container.  If you need to capture intermediate results of a pipe, use the @tee@ command.
  36
  37 @arv-run@ commands always run inside a Docker image.  By default, this is "arvados/jobs".  Use @arv --docker-image IMG@ to specify the image to use.  Note: the Docker image must be uploaded to Arvados using @arv keep docker@.
  38
  39 Use @arv-run --dry-run@ to print out the final Arvados pipeline generated by @arv-run@ without submitting it.
  40
  41 By default, the pipeline will be submitted to your configured Arvado instance.  Use @arv-run --local@ to run the command locally using "arv-crunch-job".
  42
  43 h1. Examples
  44
  45 Run one @grep@ task per file, with each input files piped from stdin.  Redirect the output to output.txt.
  46
  47 <notextile>
  48 <pre>
  49 $ <span class="userinput">arv-run grep -H -n ATTGGAGGAAAGATGAGTGAC \< *.fastq \> output.txt</span>
  50 </pre>
  51 </notextile>
  52
  53 Run @cat | grep@ once per file.  Redirect the output to output.txt.
  54
  55 <notextile>
  56 <pre>
  57 $ <span class="userinput">arv-run cat -- *.fastq \| grep -H -n ATTGGAGGAAAGATGAGTGAC \> output.txt</span>
  58 </pre>
  59 </notextile>
  60
  61 Run @bwa@ for pairs of fastq files in "inputs" using the reference human_g1k_v37.fasta.
  62
  63 <notextile>
  64 <pre>
  65 <span class="userinput">arv-run --docker-image arvados/jobs-java-bwa-samtools bwa mem reference/human_g1k_v37.fasta -- --batch-size 2 inputs/*.fastq \> '$(task.uuid).sam'</span>
  66 </pre>
  67 </notextile>