doc/user/tutorials/writing-cwl-workflow.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Writing a CWL workflow"
   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 'what_is_cwl' %}
  13
  14 {% include 'tutorial_expectations' %}
  15
  16 h2. Developing workflows
  17
  18 For an introduction and and detailed documentation about writing CWL, see the "CWL User Guide":https://www.commonwl.org/user_guide and the "CWL Specification":http://commonwl.org/v1.1 .
  19
  20 See "Writing Portable High-Performance Workflows":{{site.baseurl}}/user/cwl/cwl-style.html and "Arvados CWL Extensions":{{site.baseurl}}/user/cwl/cwl-extensions.html for additional information about using CWL on Arvados.
  21
  22 See "Repositories of CWL Tools and Workflows":https://www.commonwl.org/#Repositories_of_CWL_Tools_and_Workflows for links to repositories of existing tools for reuse.
  23
  24 See "Software for working with CWL":https://www.commonwl.org/#Software_for_working_with_CWL for links to software tools to help create CWL documents.
  25
  26 h2. Using Composer
  27
  28 You can create new workflows in the browser using "Arvados Composer":{{site.baseurl}}/user/composer/composer.html
  29
  30 h2. Registering a workflow to use in Workbench
  31
  32 Use @--create-workflow@ to register a CWL workflow with Arvados.  This enables you to share workflows with other Arvados users, and run them by clicking the <span class="btn btn-sm btn-primary"><i class="fa fa-fw fa-gear"></i> Run a process...</span> button on the Workbench Dashboard and on the command line by UUID.
  33
  34 <notextile>
  35 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --create-workflow bwa-mem.cwl</span>
  36 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
  37 2016-07-01 12:21:01 arvados.arv-run[15796] INFO: Upload local files: "bwa-mem.cwl"
  38 2016-07-01 12:21:01 arvados.arv-run[15796] INFO: Uploaded to zzzzz-4zz18-7e0hedrmkuyoei3
  39 2016-07-01 12:21:01 arvados.cwl-runner[15796] INFO: Created template zzzzz-p5p6p-rjleou1dwr167v5
  40 zzzzz-p5p6p-rjleou1dwr167v5
  41 </code></pre>
  42 </notextile>
  43
  44 You can provide a partial input file to set default values for the workflow input parameters.  You can also use the @--name@ option to set the name of the workflow:
  45
  46 <notextile>
  47 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --name "My workflow with defaults" --create-workflow bwa-mem.cwl bwa-mem-template.yml</span>
  48 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
  49 2016-07-01 14:09:50 arvados.arv-run[3730] INFO: Upload local files: "bwa-mem.cwl"
  50 2016-07-01 14:09:50 arvados.arv-run[3730] INFO: Uploaded to zzzzz-4zz18-0f91qkovk4ml18o
  51 2016-07-01 14:09:50 arvados.cwl-runner[3730] INFO: Created template zzzzz-p5p6p-0deqe6nuuyqns2i
  52 zzzzz-p5p6p-zuniv58hn8d0qd8
  53 </code></pre>
  54 </notextile>
  55
  56 h3. Running registered workflows at the command line
  57
  58 You can run a registered workflow at the command line by its UUID:
  59
  60 <notextile>
  61 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner zzzzz-p5p6p-zuniv58hn8d0qd8 --help</span>
  62 /home/peter/work/scripts/venv/bin/arvados-cwl-runner 0d62edcb9d25bf4dcdb20d8872ea7b438e12fc59 1.0.20161209192028, arvados-python-client 0.1.20161212125425, cwltool 1.0.20161207161158
  63 Resolved 'zzzzz-p5p6p-zuniv58hn8d0qd8' to 'keep:655c6cd07550151b210961ed1d3852cf+57/bwa-mem.cwl'
  64 usage: zzzzz-p5p6p-zuniv58hn8d0qd8 [-h] [--PL PL] --group_id GROUP_ID
  65                                    --read_p1 READ_P1 [--read_p2 READ_P2]
  66                                    [--reference REFERENCE] --sample_id
  67                                    SAMPLE_ID
  68                                    [job_order]
  69
  70 positional arguments:
  71   job_order             Job input json file
  72
  73 optional arguments:
  74   -h, --help            show this help message and exit
  75   --PL PL
  76   --group_id GROUP_ID
  77   --read_p1 READ_P1     The reads, in fastq format.
  78   --read_p2 READ_P2     For mate paired reads, the second file (optional).
  79   --reference REFERENCE
  80                         The index files produced by `bwa index`
  81   --sample_id SAMPLE_ID
  82 </code></pre>
  83 </notextile>
  84
  85 h2. Using cwltool
  86
  87 When developing a workflow, it is often helpful to run it on the local host to avoid the overhead of submitting to the cluster.  To execute a workflow only on the local host (without submitting jobs to an Arvados cluster) you can use the @cwltool@ command.  Note that when using @cwltool@ you must have the input data accessible on the local file system using either @arv-mount@ or @arv-get@ to fetch the data from Keep.
  88
  89 <notextile>
  90 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arv-get 2463fa9efeb75e099685528b3b9071e0+438/ .</span>
  91 156 MiB / 156 MiB 100.0%
  92 ~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arv-get ae480c5099b81e17267b7445e35b4bc7+180/ .</span>
  93 23 MiB / 23 MiB 100.0%
  94 ~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">cwltool bwa-mem-input.yml bwa-mem-input-local.yml</span>
  95 cwltool 1.0.20160629140624
  96 [job bwa-mem.cwl] /home/example/arvados/doc/user/cwl/bwa-mem$ docker \
  97     run \
  98     -i \
  99     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.ann:/var/lib/cwl/job979368791_bwa-mem/19.fasta.ann:ro \
 100     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/HWI-ST1027_129_D0THKACXX.1_1.fastq:/var/lib/cwl/job979368791_bwa-mem/HWI-ST1027_129_D0THKACXX.1_1.fastq:ro \
 101     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.sa:/var/lib/cwl/job979368791_bwa-mem/19.fasta.sa:ro \
 102     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.amb:/var/lib/cwl/job979368791_bwa-mem/19.fasta.amb:ro \
 103     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.pac:/var/lib/cwl/job979368791_bwa-mem/19.fasta.pac:ro \
 104     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/HWI-ST1027_129_D0THKACXX.1_2.fastq:/var/lib/cwl/job979368791_bwa-mem/HWI-ST1027_129_D0THKACXX.1_2.fastq:ro \
 105     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.bwt:/var/lib/cwl/job979368791_bwa-mem/19.fasta.bwt:ro \
 106     --volume=/home/example/arvados/doc/user/cwl/bwa-mem:/var/spool/cwl:rw \
 107     --volume=/tmp/tmpgzyou9:/tmp:rw \
 108     --workdir=/var/spool/cwl \
 109     --read-only=true \
 110     --log-driver=none \
 111     --user=1001 \
 112     --rm \
 113     --env=TMPDIR=/tmp \
 114     --env=HOME=/var/spool/cwl \
 115     biodckr/bwa \
 116     bwa \
 117     mem \
 118     -t \
 119     1 \
 120     -R \
 121     '@RG        ID:arvados_tutorial     PL:illumina     SM:HWI-ST1027_129' \
 122     /var/lib/cwl/job979368791_bwa-mem/19.fasta \
 123     /var/lib/cwl/job979368791_bwa-mem/HWI-ST1027_129_D0THKACXX.1_1.fastq \
 124     /var/lib/cwl/job979368791_bwa-mem/HWI-ST1027_129_D0THKACXX.1_2.fastq > /home/example/arvados/doc/user/cwl/bwa-mem/HWI-ST1027_129_D0THKACXX.1_1.sam
 125 [M::bwa_idx_load_from_disk] read 0 ALT contigs
 126 [M::process] read 100000 sequences (10000000 bp)...
 127 [M::mem_pestat] # candidate unique pairs for (FF, FR, RF, RR): (0, 4745, 1, 0)
 128 [M::mem_pestat] skip orientation FF as there are not enough pairs
 129 [M::mem_pestat] analyzing insert size distribution for orientation FR...
 130 [M::mem_pestat] (25, 50, 75) percentile: (154, 181, 214)
 131 [M::mem_pestat] low and high boundaries for computing mean and std.dev: (34, 334)
 132 [M::mem_pestat] mean and std.dev: (185.63, 44.88)
 133 [M::mem_pestat] low and high boundaries for proper pairs: (1, 394)
 134 [M::mem_pestat] skip orientation RF as there are not enough pairs
 135 [M::mem_pestat] skip orientation RR as there are not enough pairs
 136 [M::mem_process_seqs] Processed 100000 reads in 9.848 CPU sec, 9.864 real sec
 137 [main] Version: 0.7.12-r1039
 138 [main] CMD: bwa mem -t 1 -R @RG ID:arvados_tutorial     PL:illumina     SM:HWI-ST1027_129 /var/lib/cwl/job979368791_bwa-mem/19.fasta /var/lib/cwl/job979368791_bwa-mem/HWI-ST1027_129_D0THKACXX.1_1.fastq /var/lib/cwl/job979368791_bwa-mem/HWI-ST1027_129_D0THKACXX.1_2.fastq
 139 [main] Real time: 10.061 sec; CPU: 10.032 sec
 140 Final process status is success
 141 {
 142     "aligned_sam": {
 143         "size": 30738959,
 144         "path": "/home/example/arvados/doc/user/cwl/bwa-mem/HWI-ST1027_129_D0THKACXX.1_1.sam",
 145         "checksum": "sha1$0c668cca45fef02397bb5302880526d300ee4dac",
 146         "class": "File"
 147     }
 148 }
 149 </code></pre>
 150 </notextile>
 151
 152 If you get the error @JavascriptException: Long-running script killed after 20 seconds.@ this may be due to the Dockerized Node.js engine taking too long to start.  You may address this by installing Node.js locally (run @apt-get install nodejs@ on Debian or Ubuntu) or by specifying a longer timeout with the @--eval-timeout@ option.  For example, run the workflow with @cwltool --eval-timeout=40@ for a 40-second timeout.
 153
 154 h2. Making workflows directly executable
 155
 156 You can make a workflow file directly executable (@cwl-runner@ should be an alias to @arvados-cwl-runner@) by adding the following line to the top of the file:
 157
 158 <notextile>
 159 <pre><code>#!/usr/bin/env cwl-runner
 160 </code></pre>
 161 </notextile>
 162
 163 <notextile>
 164 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">./bwa-mem.cwl bwa-mem-input.yml</span>
 165 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 166 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
 167 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to zzzzz-4zz18-h7ljh5u76760ww2
 168 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job zzzzz-8i9sb-fm2n3b1w0l6bskg
 169 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-fm2n3b1w0l6bskg) is Running
 170 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-fm2n3b1w0l6bskg) is Complete
 171 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
 172 {
 173     "aligned_sam": {
 174         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
 175         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 176         "class": "File",
 177         "size": 30738986
 178     }
 179 }
 180 </code></pre>
 181 </notextile>
 182
 183 You can even make an input file directly executable the same way with the following two lines at the top:
 184
 185 <notextile>
 186 <pre><code>#!/usr/bin/env cwl-runner
 187 cwl:tool: <span class="userinput">bwa-mem.cwl</span>
 188 </code></pre>
 189 </notextile>
 190
 191 <notextile>
 192 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">./bwa-mem-input.yml</span>
 193 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 194 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
 195 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to zzzzz-4zz18-h7ljh5u76760ww2
 196 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job zzzzz-8i9sb-fm2n3b1w0l6bskg
 197 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-fm2n3b1w0l6bskg) is Running
 198 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-fm2n3b1w0l6bskg) is Complete
 199 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
 200 {
 201     "aligned_sam": {
 202         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
 203         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 204         "class": "File",
 205         "size": 30738986
 206     }
 207 }
 208 </code></pre>
 209 </notextile>