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 fully supports the "CWL draft-3":http://commonwl.org/draft-3 specification.
   8
   9 {% include 'tutorial_expectations' %}
  10
  11 h2. Getting the example files
  12
  13 The tutorial files are located in the documentation section Arvados source repository:
  14
  15 <notextile>
  16 <pre><code>~$ <span class="userinput">git clone https://github.com/curoverse/arvados</span>
  17 ~$ <span class="userinput">cd arvados/doc/user/cwl/bwa-mem</span>
  18 </code></pre>
  19 </notextile>
  20
  21 The tutorial data is hosted on "http://cloud.curoverse.com":http://cloud.curoverse.com (also known as *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).
  22
  23 <notextile>
  24 <pre><code>~$ <span class="userinput">arv-copy --src cloud --dst settings 2463fa9efeb75e099685528b3b9071e0+438</span>
  25 ~$ <span class="userinput">arv-copy --src cloud --dst settings ae480c5099b81e17267b7445e35b4bc7+180</span>
  26 </code></pre>
  27 </notextile>
  28
  29 If you do not wish to create an account on "http://cloud.curoverse.com":http://cloud.curoverse.com, you may download the files anonymously and upload them to your local Arvados instance:
  30
  31 "https://cloud.curoverse.com/collections/2463fa9efeb75e099685528b3b9071e0+438":https://cloud.curoverse.com/collections/2463fa9efeb75e099685528b3b9071e0+438
  32
  33 "https://cloud.curoverse.com/collections/ae480c5099b81e17267b7445e35b4bc7+180":https://cloud.curoverse.com/collections/ae480c5099b81e17267b7445e35b4bc7+180
  34
  35 h2. Submitting a workflow to an Arvados cluster
  36
  37 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.
  38
  39 <notextile>
  40 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner bwa-mem.cwl bwa-mem-input.yml</span>
  41 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
  42 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
  43 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to 3d0ga-4zz18-h7ljh5u76760ww2
  44 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job 3d0ga-8i9sb-fm2n3b1w0l6bskg
  45 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (3d0ga-8i9sb-fm2n3b1w0l6bskg) is Running
  46 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (3d0ga-8i9sb-fm2n3b1w0l6bskg) is Complete
  47 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
  48 {
  49     "aligned_sam": {
  50         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
  51         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
  52         "class": "File",
  53         "size": 30738986
  54     }
  55 }
  56 </code></pre>
  57 </notextile>
  58
  59 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.
  60
  61 <notextile>
  62 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --no-wait bwa-mem.cwl bwa-mem-input.yml</span>
  63 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
  64 2016-06-30 15:07:52 arvados.arv-run[12480] INFO: Upload local files: "bwa-mem.cwl"
  65 2016-06-30 15:07:52 arvados.arv-run[12480] INFO: Uploaded to 3d0ga-4zz18-eqnfwrow8aysa9q
  66 2016-06-30 15:07:52 arvados.cwl-runner[12480] INFO: Submitted job 3d0ga-8i9sb-fm2n3b1w0l6bskg
  67 3d0ga-8i9sb-fm2n3b1w0l6bskg
  68 </code></pre>
  69 </notextile>
  70
  71 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.
  72
  73 <notextile>
  74 <pre><code>
  75 ~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --local bwa-mem.cwl bwa-mem-input.yml</span>
  76 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
  77 2016-07-01 10:05:19 arvados.cwl-runner[16290] INFO: Pipeline instance 3d0ga-d1hrv-92wcu6ldtio74r4
  78 2016-07-01 10:05:28 arvados.cwl-runner[16290] INFO: Job bwa-mem.cwl (3d0ga-8i9sb-2nzzfbuf9zjrj4g) is Queued
  79 2016-07-01 10:05:29 arvados.cwl-runner[16290] INFO: Job bwa-mem.cwl (3d0ga-8i9sb-2nzzfbuf9zjrj4g) is Running
  80 2016-07-01 10:05:45 arvados.cwl-runner[16290] INFO: Job bwa-mem.cwl (3d0ga-8i9sb-2nzzfbuf9zjrj4g) is Complete
  81 2016-07-01 10:05:46 arvados.cwl-runner[16290] INFO: Overall process status is success
  82 {
  83     "aligned_sam": {
  84         "size": 30738986,
  85         "path": "keep:15f56bad0aaa7364819bf14ca2a27c63+88/HWI-ST1027_129_D0THKACXX.1_1.sam",
  86         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
  87         "class": "File"
  88     }
  89 }
  90 </code></pre>
  91 </notextile>
  92
  93 h2. Work reuse
  94
  95 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@.
  96
  97 h2. Referencing files
  98
  99 When running a workflow on an Arvados cluster, the input files must be stored in Keep.  There are several ways this can happen.
 100
 101 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@.
 102
 103 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.
 104
 105 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.
 106
 107 h2. Registering a workflow with Workbench
 108
 109 Use @--create-template@ to register a CWL workflow with Arvados Workbench.  This enables you to run Workflows by clicking on the <span class="btn btn-sm btn-primary"><i class="fa fa-fw fa-gear"></i> Run a pipeline...</span> on the Workbench Dashboard.
 110
 111 <notextile>
 112 <pre><code>
 113 ~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --create-template bwa-mem.cwl</span>
 114 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 115 2016-07-01 12:21:01 arvados.arv-run[15796] INFO: Upload local files: "bwa-mem.cwl"
 116 2016-07-01 12:21:01 arvados.arv-run[15796] INFO: Uploaded to 3d0ga-4zz18-7e0hedrmkuyoei3
 117 2016-07-01 12:21:01 arvados.cwl-runner[15796] INFO: Created template 3d0ga-p5p6p-rjleou1dwr167v5
 118 3d0ga-p5p6p-rjleou1dwr167v5
 119 </code></pre>
 120 </notextile>
 121
 122 You can provide a partial input file to set default values for the Workflow input parameters:
 123
 124 <notextile>
 125 <pre><code>
 126 ~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --create-template bwa-mem.cwl bwa-mem-template.yml</span>
 127 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 128 2016-07-01 14:09:50 arvados.arv-run[3730] INFO: Upload local files: "bwa-mem.cwl"
 129 2016-07-01 14:09:50 arvados.arv-run[3730] INFO: Uploaded to 3d0ga-4zz18-0f91qkovk4ml18o
 130 2016-07-01 14:09:50 arvados.cwl-runner[3730] INFO: Created template 3d0ga-p5p6p-0deqe6nuuyqns2i
 131 3d0ga-p5p6p-0deqe6nuuyqns2i
 132 </code></pre>
 133 </notextile>
 134
 135 h2. Making workflows directly executable
 136
 137 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:
 138
 139 *bwa-mem.cwl*
 140
 141 <notextile>
 142 <pre><code>#!/usr/bin/env cwl-runner
 143 </code></pre>
 144 </notextile>
 145
 146 <notextile>
 147 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">./bwa-mem.cwl bwa-mem-input.yml</span>
 148 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 149 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
 150 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to 3d0ga-4zz18-h7ljh5u76760ww2
 151 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job 3d0ga-8i9sb-fm2n3b1w0l6bskg
 152 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (3d0ga-8i9sb-fm2n3b1w0l6bskg) is Running
 153 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (3d0ga-8i9sb-fm2n3b1w0l6bskg) is Complete
 154 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
 155 {
 156     "aligned_sam": {
 157         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
 158         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 159         "class": "File",
 160         "size": 30738986
 161     }
 162 }
 163 </code></pre>
 164 </notextile>
 165
 166 You can even make an input file directly executable the same way with the following two lines at the top:
 167
 168 *bwa-mem-input.yml*
 169
 170 <notextile>
 171 <pre><code>#!/usr/bin/env cwl-runner
 172 cwl:tool: bwa-mem.cwl
 173 </code></pre>
 174 </notextile>
 175
 176 <notextile>
 177 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">./bwa-mem-input.yml</span>
 178 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 179 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
 180 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to 3d0ga-4zz18-h7ljh5u76760ww2
 181 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job 3d0ga-8i9sb-fm2n3b1w0l6bskg
 182 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (3d0ga-8i9sb-fm2n3b1w0l6bskg) is Running
 183 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (3d0ga-8i9sb-fm2n3b1w0l6bskg) is Complete
 184 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
 185 {
 186     "aligned_sam": {
 187         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
 188         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 189         "class": "File",
 190         "size": 30738986
 191     }
 192 }
 193 </code></pre>
 194 </notextile>
 195
 196 h2. Developing workflows
 197
 198 For an introduction and and detailed documentation about writing CWL, see the "User Guide":http://commonwl.org/draft-3/UserGuide.html and the "Specification":http://commonwl.org/draft-3 .
 199
 200 To run on Arvados, a workflow should provide a @DockerRequirement@ in the @hints@ section.
 201
 202 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.
 203
 204 <notextile>
 205 <pre><code>
 206 ~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arv-get 2463fa9efeb75e099685528b3b9071e0+438/ .</span>
 207 156 MiB / 156 MiB 100.0%
 208 ~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arv-get ae480c5099b81e17267b7445e35b4bc7+180/ .</span>
 209 23 MiB / 23 MiB 100.0%
 210 ~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">cwltool bwa-mem-input.yml bwa-mem-input-local.yml</span>
 211 cwltool 1.0.20160629140624
 212 [job bwa-mem.cwl] /home/peter/.arvbox/arvbox/arvados/doc/user/cwl/bwa-mem$ docker \
 213     run \
 214     -i \
 215     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.ann:/var/lib/cwl/job979368791_bwa-mem/19.fasta.ann:ro \
 216     --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 \
 217     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.sa:/var/lib/cwl/job979368791_bwa-mem/19.fasta.sa:ro \
 218     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.amb:/var/lib/cwl/job979368791_bwa-mem/19.fasta.amb:ro \
 219     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.pac:/var/lib/cwl/job979368791_bwa-mem/19.fasta.pac:ro \
 220     --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 \
 221     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.bwt:/var/lib/cwl/job979368791_bwa-mem/19.fasta.bwt:ro \
 222     --volume=/home/example/arvados/doc/user/cwl/bwa-mem:/var/spool/cwl:rw \
 223     --volume=/tmp/tmpgzyou9:/tmp:rw \
 224     --workdir=/var/spool/cwl \
 225     --read-only=true \
 226     --log-driver=none \
 227     --user=1001 \
 228     --rm \
 229     --env=TMPDIR=/tmp \
 230     --env=HOME=/var/spool/cwl \
 231     biodckr/bwa \
 232     bwa \
 233     mem \
 234     -t \
 235     1 \
 236     -R \
 237     '@RG        ID:arvados_tutorial     PL:illumina     SM:HWI-ST1027_129' \
 238     /var/lib/cwl/job979368791_bwa-mem/19.fasta \
 239     /var/lib/cwl/job979368791_bwa-mem/HWI-ST1027_129_D0THKACXX.1_1.fastq \
 240     /var/lib/cwl/job979368791_bwa-mem/HWI-ST1027_129_D0THKACXX.1_2.fastq > /home/peter/.arvbox/arvbox/arvados/doc/user/cwl/bwa-mem/HWI-ST1027_129_D0THKACXX.1_1.sam
 241 [M::bwa_idx_load_from_disk] read 0 ALT contigs
 242 [M::process] read 100000 sequences (10000000 bp)...
 243 [M::mem_pestat] # candidate unique pairs for (FF, FR, RF, RR): (0, 4745, 1, 0)
 244 [M::mem_pestat] skip orientation FF as there are not enough pairs
 245 [M::mem_pestat] analyzing insert size distribution for orientation FR...
 246 [M::mem_pestat] (25, 50, 75) percentile: (154, 181, 214)
 247 [M::mem_pestat] low and high boundaries for computing mean and std.dev: (34, 334)
 248 [M::mem_pestat] mean and std.dev: (185.63, 44.88)
 249 [M::mem_pestat] low and high boundaries for proper pairs: (1, 394)
 250 [M::mem_pestat] skip orientation RF as there are not enough pairs
 251 [M::mem_pestat] skip orientation RR as there are not enough pairs
 252 [M::mem_process_seqs] Processed 100000 reads in 9.848 CPU sec, 9.864 real sec
 253 [main] Version: 0.7.12-r1039
 254 [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
 255 [main] Real time: 10.061 sec; CPU: 10.032 sec
 256 Final process status is success
 257 {
 258     "aligned_sam": {
 259         "size": 30738959,
 260         "path": "/home/example/arvados/doc/user/cwl/bwa-mem/HWI-ST1027_129_D0THKACXX.1_1.sam",
 261         "checksum": "sha1$0c668cca45fef02397bb5302880526d300ee4dac",
 262         "class": "File"
 263     }
 264 }
 265 </code></pre>
 266 </notextile>