doc/user/cwl/cwl-runner.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: Using Common Workflow Language
   5 ...
   6
   7 The "Common Workflow Language (CWL)":http://commonwl.org is a multi-vendor open standard for describing analysis tools and workflows that are portable across a variety of platforms.  CWL is the recommended way to develop and run workflows for Arvados.  Arvados supports the "CWL v1.0":http://commonwl.org/v1.0 specification.
   8
   9 {% include 'tutorial_expectations' %}
  10
  11 h2. Setting up
  12
  13 The @arvados-cwl-runner@ client is installed by default on Arvados shell nodes.  However, if you do not have @arvados-cwl-runner@, you may install it using @pip@:
  14
  15 <notextile>
  16 <pre><code>~$ <span class="userinput">virtualenv ~/venv</span>
  17 ~$ <span class="userinput">. ~/venv/bin/activate</span>
  18 ~$ <span class="userinput">pip install -U setuptools</span>
  19 ~$ <span class="userinput">pip install arvados-cwl-runner</span>
  20 </code></pre>
  21 </notextile>
  22
  23 h3. Docker
  24
  25 Certain features of @arvados-cwl-runner@ require access to Docker.  You can determine if you have access to Docker by running @docker version@:
  26
  27 <notextile>
  28 <pre><code>~$ <span class="userinput">docker version</span>
  29 Client:
  30  Version:      1.9.1
  31  API version:  1.21
  32  Go version:   go1.4.2
  33  Git commit:   a34a1d5
  34  Built:        Fri Nov 20 12:59:02 UTC 2015
  35  OS/Arch:      linux/amd64
  36
  37 Server:
  38  Version:      1.9.1
  39  API version:  1.21
  40  Go version:   go1.4.2
  41  Git commit:   a34a1d5
  42  Built:        Fri Nov 20 12:59:02 UTC 2015
  43  OS/Arch:      linux/amd64
  44 </code></pre>
  45 </notextile>
  46
  47 If this returns an error, contact the sysadmin of your cluster for assistance.  Alternatively, if you have Docker installed on your local workstation, you may follow the instructions above to install @arvados-cwl-runner@.
  48
  49 h3. Getting the example files
  50
  51 The tutorial files are located in the documentation section of the Arvados source repository:
  52
  53 <notextile>
  54 <pre><code>~$ <span class="userinput">git clone https://github.com/curoverse/arvados</span>
  55 ~$ <span class="userinput">cd arvados/doc/user/cwl/bwa-mem</span>
  56 </code></pre>
  57 </notextile>
  58
  59 The tutorial data is hosted on "https://cloud.curoverse.com":https://cloud.curoverse.com (also referred to by the identifier *qr1hi*).  If you are using a different Arvados instance, you may need to copy the data to your own instance.  The easiest way to do this is with "arv-copy":{{site.baseurl}}/user/topics/arv-copy.html (this requires signing up for a free cloud.curoverse.com account).
  60
  61 <notextile>
  62 <pre><code>~$ <span class="userinput">arv-copy --src qr1hi --dst settings 2463fa9efeb75e099685528b3b9071e0+438</span>
  63 ~$ <span class="userinput">arv-copy --src qr1hi --dst settings ae480c5099b81e17267b7445e35b4bc7+180</span>
  64 </code></pre>
  65 </notextile>
  66
  67 If you do not wish to create an account on "https://cloud.curoverse.com":https://cloud.curoverse.com, you may download the files anonymously and upload them to your local Arvados instance:
  68
  69 "https://cloud.curoverse.com/collections/2463fa9efeb75e099685528b3b9071e0+438":https://cloud.curoverse.com/collections/2463fa9efeb75e099685528b3b9071e0+438
  70
  71 "https://cloud.curoverse.com/collections/ae480c5099b81e17267b7445e35b4bc7+180":https://cloud.curoverse.com/collections/ae480c5099b81e17267b7445e35b4bc7+180
  72
  73 h2. Submitting a workflow to an Arvados cluster
  74
  75 Use @arvados-cwl-runner@ to submit CWL workflows to Arvados.  After submitting the job, it will wait for the workflow to complete and print out the final result to standard output.  Note that once submitted, the workflow runs entirely on Arvados, so even if you interrupt @arvados-cwl-runner@ or log out, the workflow will continue to run.
  76
  77 <notextile>
  78 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner bwa-mem.cwl bwa-mem-input.yml</span>
  79 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
  80 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
  81 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to qr1hi-4zz18-h7ljh5u76760ww2
  82 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job qr1hi-8i9sb-fm2n3b1w0l6bskg
  83 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Running
  84 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Complete
  85 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
  86 {
  87     "aligned_sam": {
  88         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
  89         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
  90         "class": "File",
  91         "size": 30738986
  92     }
  93 }
  94 </code></pre>
  95 </notextile>
  96
  97 To submit a workflow and exit immediately, use the @--no-wait@ option.  This will print out the uuid of the job that was submitted to standard output.
  98
  99 <notextile>
 100 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --no-wait bwa-mem.cwl bwa-mem-input.yml</span>
 101 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 102 2016-06-30 15:07:52 arvados.arv-run[12480] INFO: Upload local files: "bwa-mem.cwl"
 103 2016-06-30 15:07:52 arvados.arv-run[12480] INFO: Uploaded to qr1hi-4zz18-eqnfwrow8aysa9q
 104 2016-06-30 15:07:52 arvados.cwl-runner[12480] INFO: Submitted job qr1hi-8i9sb-fm2n3b1w0l6bskg
 105 qr1hi-8i9sb-fm2n3b1w0l6bskg
 106 </code></pre>
 107 </notextile>
 108
 109 To run a workflow with local control, use @--local@.  This means that the host where you run @arvados-cwl-runner@ will be responsible for submitting jobs. With @--local@, if you interrupt @arvados-cwl-runner@ or log out, the workflow will be terminated.
 110
 111 <notextile>
 112 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --local bwa-mem.cwl bwa-mem-input.yml</span>
 113 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 114 2016-07-01 10:05:19 arvados.cwl-runner[16290] INFO: Pipeline instance qr1hi-d1hrv-92wcu6ldtio74r4
 115 2016-07-01 10:05:28 arvados.cwl-runner[16290] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-2nzzfbuf9zjrj4g) is Queued
 116 2016-07-01 10:05:29 arvados.cwl-runner[16290] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-2nzzfbuf9zjrj4g) is Running
 117 2016-07-01 10:05:45 arvados.cwl-runner[16290] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-2nzzfbuf9zjrj4g) is Complete
 118 2016-07-01 10:05:46 arvados.cwl-runner[16290] INFO: Overall process status is success
 119 {
 120     "aligned_sam": {
 121         "size": 30738986,
 122         "path": "keep:15f56bad0aaa7364819bf14ca2a27c63+88/HWI-ST1027_129_D0THKACXX.1_1.sam",
 123         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 124         "class": "File"
 125     }
 126 }
 127 </code></pre>
 128 </notextile>
 129
 130 h2. Work reuse
 131
 132 Workflows submitted with @arvados-cwl-runner@ will take advantage of Arvados job reuse.  If you submit a workflow which is identical to one that has run before, it will short cut the execution and return the result of the previous run.  This also applies to individual workflow steps.  For example, a two step workflow where the first step has run before will reuse results for first step and only execute the new second step.  You can disable this behavior with @--disable-reuse@.
 133
 134 h2. Referencing files
 135
 136 When running a workflow on an Arvados cluster, the input files must be stored in Keep.  There are several ways this can happen.
 137
 138 A URI reference to Keep uses the @keep:@ scheme followed by the portable data hash, collection size, and path to the file inside the collection.  For example, @keep:2463fa9efeb75e099685528b3b9071e0+438/19.fasta.bwt@.
 139
 140 If you reference a file in "arv-mount":{{site.baseurl}}/user/tutorials/tutorial-keep-mount.html, such as @/home/example/keep/by_id/2463fa9efeb75e099685528b3b9071e0+438/19.fasta.bwt@, then @arvados-cwl-runner@ will automatically determine the appropriate Keep URI reference.
 141
 142 If you reference a local file which is not in @arv-mount@, then @arvados-cwl-runner@ will upload the file to Keep and use the Keep URI reference from the upload.
 143
 144 h2. Registering a workflow to use in Workbench
 145
 146 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.
 147
 148 <notextile>
 149 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --create-workflow bwa-mem.cwl</span>
 150 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 151 2016-07-01 12:21:01 arvados.arv-run[15796] INFO: Upload local files: "bwa-mem.cwl"
 152 2016-07-01 12:21:01 arvados.arv-run[15796] INFO: Uploaded to qr1hi-4zz18-7e0hedrmkuyoei3
 153 2016-07-01 12:21:01 arvados.cwl-runner[15796] INFO: Created template qr1hi-p5p6p-rjleou1dwr167v5
 154 qr1hi-p5p6p-rjleou1dwr167v5
 155 </code></pre>
 156 </notextile>
 157
 158 You can provide a partial input file to set default values for the workflow input parameters:
 159
 160 <notextile>
 161 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --create-workflow bwa-mem.cwl bwa-mem-template.yml</span>
 162 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 163 2016-07-01 14:09:50 arvados.arv-run[3730] INFO: Upload local files: "bwa-mem.cwl"
 164 2016-07-01 14:09:50 arvados.arv-run[3730] INFO: Uploaded to qr1hi-4zz18-0f91qkovk4ml18o
 165 2016-07-01 14:09:50 arvados.cwl-runner[3730] INFO: Created template qr1hi-p5p6p-0deqe6nuuyqns2i
 166 qr1hi-p5p6p-0deqe6nuuyqns2i
 167 </code></pre>
 168 </notextile>
 169
 170 h2. Making workflows directly executable
 171
 172 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:
 173
 174 <notextile>
 175 <pre><code>#!/usr/bin/env cwl-runner
 176 </code></pre>
 177 </notextile>
 178
 179 <notextile>
 180 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">./bwa-mem.cwl bwa-mem-input.yml</span>
 181 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 182 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
 183 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to qr1hi-4zz18-h7ljh5u76760ww2
 184 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job qr1hi-8i9sb-fm2n3b1w0l6bskg
 185 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Running
 186 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Complete
 187 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
 188 {
 189     "aligned_sam": {
 190         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
 191         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 192         "class": "File",
 193         "size": 30738986
 194     }
 195 }
 196 </code></pre>
 197 </notextile>
 198
 199 You can even make an input file directly executable the same way with the following two lines at the top:
 200
 201 <notextile>
 202 <pre><code>#!/usr/bin/env cwl-runner
 203 cwl:tool: <span class="userinput">bwa-mem.cwl</span>
 204 </code></pre>
 205 </notextile>
 206
 207 <notextile>
 208 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">./bwa-mem-input.yml</span>
 209 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 210 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
 211 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to qr1hi-4zz18-h7ljh5u76760ww2
 212 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job qr1hi-8i9sb-fm2n3b1w0l6bskg
 213 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Running
 214 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Complete
 215 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
 216 {
 217     "aligned_sam": {
 218         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
 219         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 220         "class": "File",
 221         "size": 30738986
 222     }
 223 }
 224 </code></pre>
 225 </notextile>
 226
 227 h2. Developing workflows
 228
 229 For an introduction and and detailed documentation about writing CWL, see the "User Guide":http://commonwl.org/v1.0/UserGuide.html and the "Specification":http://commonwl.org/v1.0 .
 230
 231 To run on Arvados, a workflow should provide a @DockerRequirement@ in the @hints@ section.
 232
 233 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 you must also have the input data accessible on the local host.  You can use @arv-get@ to fetch the data from Keep.
 234
 235 <notextile>
 236 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arv-get 2463fa9efeb75e099685528b3b9071e0+438/ .</span>
 237 156 MiB / 156 MiB 100.0%
 238 ~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arv-get ae480c5099b81e17267b7445e35b4bc7+180/ .</span>
 239 23 MiB / 23 MiB 100.0%
 240 ~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">cwltool bwa-mem-input.yml bwa-mem-input-local.yml</span>
 241 cwltool 1.0.20160629140624
 242 [job bwa-mem.cwl] /home/example/arvados/doc/user/cwl/bwa-mem$ docker \
 243     run \
 244     -i \
 245     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.ann:/var/lib/cwl/job979368791_bwa-mem/19.fasta.ann:ro \
 246     --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 \
 247     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.sa:/var/lib/cwl/job979368791_bwa-mem/19.fasta.sa:ro \
 248     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.amb:/var/lib/cwl/job979368791_bwa-mem/19.fasta.amb:ro \
 249     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.pac:/var/lib/cwl/job979368791_bwa-mem/19.fasta.pac:ro \
 250     --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 \
 251     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.bwt:/var/lib/cwl/job979368791_bwa-mem/19.fasta.bwt:ro \
 252     --volume=/home/example/arvados/doc/user/cwl/bwa-mem:/var/spool/cwl:rw \
 253     --volume=/tmp/tmpgzyou9:/tmp:rw \
 254     --workdir=/var/spool/cwl \
 255     --read-only=true \
 256     --log-driver=none \
 257     --user=1001 \
 258     --rm \
 259     --env=TMPDIR=/tmp \
 260     --env=HOME=/var/spool/cwl \
 261     biodckr/bwa \
 262     bwa \
 263     mem \
 264     -t \
 265     1 \
 266     -R \
 267     '@RG        ID:arvados_tutorial     PL:illumina     SM:HWI-ST1027_129' \
 268     /var/lib/cwl/job979368791_bwa-mem/19.fasta \
 269     /var/lib/cwl/job979368791_bwa-mem/HWI-ST1027_129_D0THKACXX.1_1.fastq \
 270     /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
 271 [M::bwa_idx_load_from_disk] read 0 ALT contigs
 272 [M::process] read 100000 sequences (10000000 bp)...
 273 [M::mem_pestat] # candidate unique pairs for (FF, FR, RF, RR): (0, 4745, 1, 0)
 274 [M::mem_pestat] skip orientation FF as there are not enough pairs
 275 [M::mem_pestat] analyzing insert size distribution for orientation FR...
 276 [M::mem_pestat] (25, 50, 75) percentile: (154, 181, 214)
 277 [M::mem_pestat] low and high boundaries for computing mean and std.dev: (34, 334)
 278 [M::mem_pestat] mean and std.dev: (185.63, 44.88)
 279 [M::mem_pestat] low and high boundaries for proper pairs: (1, 394)
 280 [M::mem_pestat] skip orientation RF as there are not enough pairs
 281 [M::mem_pestat] skip orientation RR as there are not enough pairs
 282 [M::mem_process_seqs] Processed 100000 reads in 9.848 CPU sec, 9.864 real sec
 283 [main] Version: 0.7.12-r1039
 284 [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
 285 [main] Real time: 10.061 sec; CPU: 10.032 sec
 286 Final process status is success
 287 {
 288     "aligned_sam": {
 289         "size": 30738959,
 290         "path": "/home/example/arvados/doc/user/cwl/bwa-mem/HWI-ST1027_129_D0THKACXX.1_1.sam",
 291         "checksum": "sha1$0c668cca45fef02397bb5302880526d300ee4dac",
 292         "class": "File"
 293     }
 294 }
 295 </code></pre>
 296 </notextile>
 297
 298 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.