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 an empty template using @arv create pipeline_template@:
  12
  13 <notextile>
  14 <pre><code>~$ <span class="userinput">arv create pipeline_template</span></code></pre>
  15 </notextile>
  16
  17 This will open the template record in an interactive text editor (as specified by $EDITOR or $VISUAL, otherwise defaults to @nano@).  Now, update the contents of the editor with the following content:
  18
  19 <notextile>{% code 'tutorial_bwa_sortsam_pipeline' as javascript %}</notextile>
  20
  21 * @"name"@ is a human-readable name for the pipeline.
  22 * @"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).
  23 ** 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
  24 * @"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.
  25 * @"runtime_constraints"@ describes runtime resource requirements for the component.
  26 ** @"docker_image"@ specifies the "Docker":https://www.docker.com/ runtime environment in which to run the job.  The Docker image @"bcosc/arv-base-java"@ supplied here has the Java runtime environment, bwa, and samtools installed.
  27 ** @"arvados_sdk_version"@ specifies a version of the Arvados SDK to load alongside the job's script.
  28 * @"script_parameters"@ describes the component parameters.
  29 ** @"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.
  30 ** @"task.stdout"@ indicates that the output of this command should be captured to a file.
  31 ** @$(node.cores)@ evaluates to the number of cores available on the compute node at time the command is run.
  32 ** @$(tmpdir)@ evaluates to the local path for temporary directory the command should use for scratch data.
  33 ** @$(reference_collection)@ evaluates to the script_parameter @"reference_collection"@
  34 ** @$(dir $(...))@ constructs a local path to a directory representing the supplied Arvados collection.
  35 ** @$(file $(...))@ constructs a local path to a given file within the supplied Arvados collection.
  36 ** @$(glob $(...))@ searches the specified path based on a file glob pattern and evalutes to the first result.
  37 ** @$(basename $(...))@ evaluates to the supplied path with leading path portion and trailing filename extensions stripped
  38 * @"output_of"@ indicates that the @output@ of the @bwa-mem@ component should be used as the @"input"@ script parameter of @SortSam@.  Arvados uses these dependencies between components to automatically determine the correct order to run them.
  39
  40 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.
  41
  42 See the "run-command reference":{{site.baseurl}}/user/topics/run-command.html for more information about using @run-command@.
  43
  44 *Note:* When trying to get job reproducibility without re-computation, you need to set these parameters to their specific hashes. Using a version such as master in @"arvados_sdk_version"@ will grab the latest version hash, which will allow Arvados to re-compute your job if the sdk gets updated.
  45 * @"arvados_sdk_version"@ : The latest version can be found on the "Arvados Python sdk repository":https://arvados.org/projects/arvados/repository/revisions/master/show/sdk/python under *Latest revisions*.
  46 * @"script_version"@ : The current version of your script in your git repository can be found by using the following command:
  47
  48 <notextile>
  49 <pre><code>~$ <span class="userinput">git rev-parse HEAD</span></code></pre>
  50 </notextile>
  51
  52 * @"docker_image"@ : The docker image hash used is found on the "Collection page":https://cloud.curoverse.com/collections/qr1hi-4zz18-dov6im679g3jr1n as the *Content address*.
  53
  54 h2. Running your pipeline
  55
  56 Your new pipeline template should appear at the top of the Workbench "pipeline&nbsp;templates":{{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
  57
  58 Test data is available in the "Arvados Tutorial":{{site.arvados_workbench_host}}/projects/qr1hi-j7d0g-u7zg1qdaowykd8d project:
  59
  60 * Choose <i class="fa fa-fw fa-archive"></i> "Tutorial chromosome 19 reference (2463fa9efeb75e099685528b3b9071e0+438)":{{site.arvados_workbench_host}}/collections/2463fa9efeb75e099685528b3b9071e0+438 for the "reference_collection" parameter
  61 * Choose <i class="fa fa-fw fa-archive"></i> "Tutorial sample exome (3229739b505d2b878b62aed09895a55a+142)":{{site.arvados_workbench_host}}/collections/3229739b505d2b878b62aed09895a55a+142 for the "sample" parameter
  62
  63 For more information and examples for writing pipelines, see the "pipeline template reference":{{site.baseurl}}/api/schema/PipelineTemplate.html