doc/user/tutorials/running-external-program.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Writing a pipeline template"
   5 ...
   6
   7 This tutorial demonstrates how to construct a two stage pipeline template that uses the "bwa mem":http://bio-bwa.sourceforge.net/ tool to produce a "Sequence Alignment/Map (SAM)":https://samtools.github.io/ file, then uses the "Picard SortSam tool":http://picard.sourceforge.net/command-line-overview.shtml#SortSam to produce a BAM (Binary Alignment/Map) file.
   8
   9 {% include 'tutorial_expectations' %}
  10
  11 Use the following command to create a new empty template using @arv pipeline_template create@:
  12
  13 <notextile>
  14 <pre><code>~$ <span class="userinput">arv edit $(arv --format=uuid pipeline_template create --pipeline-template '{}') name components </span></code></pre>
  15 </notextile>
  16
  17 * @--format=uuid@ option prints out just the unique identifier for the new template, instead of the entire template record (default)
  18
  19 This will open the template record in an interactive text editor (as specified by $EDITOR or $VISUAL, otherwise defaults to @nano@) using @arv edit@.  Now add the following content:
  20
  21 <notextile>{% code 'tutorial_bwa_sortsam_pipeline' as javascript %}</notextile>
  22
  23 * @"name"@ is a human-readable name for the pipeline.
  24 * @"components"@ is a set of scripts or commands that make up the pipeline.  Each component is given an identifier (@"bwa-mem"@ and @"SortSam"@) in this example).
  25 ** Each entry in components @"components"@ is an Arvados job submission.  For more information about individual jobs, see the "job object reference":{{site.baseurl}}/api/schema/Job.html and "job create method.":{{site.baseurl}}/api/methods/jobs.html#create
  26 * @"repository"@, @"script_version"@, and @"script"@ indicate that we intend to use the external @"run-command"@ tool wrapper that is part of the Arvados.  These parameters are described in more detail in "Writing a script":tutorial-firstscript.html
  27 * @"runtime_constraints"@ describes runtime resource requirements for the component.
  28 ** @"docker_image"@ specifies the "Docker":https://www.docker.com/ runtime environment in which to run the job.  The Docker image @"arvados/jobs-java-bwa-samtools"@ supplied here has the Arvados SDK, Java runtime environment, bwa, and samtools installed.
  29 * @"script_parameters"@ describes the component parameters.
  30 ** @"command"@ is the actual command line to invoke the @bwa@ and then @SortSam@.  The notation @$()@ denotes macro substitution commands evaluated by the run-command tool wrapper.
  31 ** @"stdout"@ indicates that the output of this command should be captured to a file.
  32 ** @$(node.cores)@ evaluates to the number of cores available on the compute node at time the command is run.
  33 ** @$(tmpdir)@ evaluates to the local path for temporary directory the command should use for scratch data.
  34 ** @$(reference_collection)@ evaluates to the script_parameter @"reference_collection"@
  35 ** @$(dir $(...))@ constructs a local path to a directory representing the supplied Arvados collection.
  36 ** @$(file $(...))@ constructs a local path to a given file within the supplied Arvados collection.
  37 ** @$(glob $(...))@ searches the specified path based on a file glob pattern and evalutes to the first result.
  38 ** @$(basename $(...))@ evaluates to the supplied path with leading path portion and trailing filename extensions stripped
  39 ** @"output_of"@ indicates that the @output@ of the @bwa-mem@ component should be used as the @"input"@ of @SortSam@.  Arvados uses these dependencies between components to automatically determine the correct order to run them.
  40
  41 When using @run-command@, the tool should write its output to the current working directory.  The output will be automatically uploaded to Keep when the job completes.
  42
  43 h2. Running your pipeline
  44
  45 Your new pipeline template should appear at the top of the Workbench "pipeline&nbsp;templates":https://{{ site.arvados_workbench_host }}/pipeline_templates page.  You can run your pipeline "using Workbench":tutorial-pipeline-workbench.html or the "command line.":{{site.baseurl}}/user/topics/running-pipeline-command-line.html
  46
  47 Test data is available in the "Arvados Tutorial":https://{{ site.arvados_workbench_host }}/projects/qr1hi-j7d0g-u7zg1qdaowykd8d project:
  48
  49 * Choose <i class="fa fa-fw fa-archive"></i> "Tutorial chromosome 19 reference (2463fa9efeb75e099685528b3b9071e0+438)":https://{{ site.arvados_workbench_host }}/collections/2463fa9efeb75e099685528b3b9071e0+438 for the "reference_collection" parameter
  50 * Choose <i class="fa fa-fw fa-archive"></i> "Tutorial sample exome (3229739b505d2b878b62aed09895a55a+142)":https://{{ site.arvados_workbench_host }}/collections/3229739b505d2b878b62aed09895a55a+142 for the "sample" parameter
  51
  52 For more information and examples for writing pipelines, see the "pipeline template reference":{{site.baseurl}}/api/schema/PipelineTemplate.html