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

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: Using Common Workflow Language
   5 ...
   6
   7 {% include 'what_is_cwl' %}
   8
   9 {% include 'tutorial_expectations' %}
  10
  11 h2. Preparing to work with Arvados CWL runner
  12
  13 h3. arvados-cwl-runner
  14
  15 The @arvados-cwl-runner@ client is installed by default on Arvados shell nodes.
  16
  17 However, if you do not have @arvados-cwl-runner@, you may install it using @pip@:
  18
  19 <notextile>
  20 <pre><code>~$ <span class="userinput">virtualenv ~/venv</span>
  21 ~$ <span class="userinput">. ~/venv/bin/activate</span>
  22 ~$ <span class="userinput">pip install -U setuptools</span>
  23 ~$ <span class="userinput">pip install arvados-cwl-runner</span>
  24 </code></pre>
  25 </notextile>
  26
  27 h3. Check Docker access
  28
  29 Certain features of @arvados-cwl-runner@ require access to Docker.
  30
  31 You can determine if you have access to Docker by running @docker version@:
  32
  33 <notextile>
  34 <pre><code>~$ <span class="userinput">docker version</span>
  35 Client:
  36  Version:      1.9.1
  37  API version:  1.21
  38  Go version:   go1.4.2
  39  Git commit:   a34a1d5
  40  Built:        Fri Nov 20 12:59:02 UTC 2015
  41  OS/Arch:      linux/amd64
  42
  43 Server:
  44  Version:      1.9.1
  45  API version:  1.21
  46  Go version:   go1.4.2
  47  Git commit:   a34a1d5
  48  Built:        Fri Nov 20 12:59:02 UTC 2015
  49  OS/Arch:      linux/amd64
  50 </code></pre>
  51 </notextile>
  52
  53 If this returns an error, contact the sysadmin of your cluster for assistance.
  54
  55 h3. Get the example files
  56
  57 The tutorial files are located in the documentation section of the Arvados source repository:
  58
  59 <notextile>
  60 <pre><code>~$ <span class="userinput">git clone https://github.com/curoverse/arvados</span>
  61 ~$ <span class="userinput">cd arvados/doc/user/cwl/bwa-mem</span>
  62 </code></pre>
  63 </notextile>
  64
  65 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).
  66
  67 <notextile>
  68 <pre><code>~$ <span class="userinput">arv-copy --src qr1hi --dst settings 2463fa9efeb75e099685528b3b9071e0+438</span>
  69 ~$ <span class="userinput">arv-copy --src qr1hi --dst settings ae480c5099b81e17267b7445e35b4bc7+180</span>
  70 </code></pre>
  71 </notextile>
  72
  73 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:
  74
  75 "https://cloud.curoverse.com/collections/2463fa9efeb75e099685528b3b9071e0+438":https://cloud.curoverse.com/collections/2463fa9efeb75e099685528b3b9071e0+438
  76
  77 "https://cloud.curoverse.com/collections/ae480c5099b81e17267b7445e35b4bc7+180":https://cloud.curoverse.com/collections/ae480c5099b81e17267b7445e35b4bc7+180
  78
  79 h2. Submitting a workflow to an Arvados cluster
  80
  81 {% include 'arvados_cwl_runner' %}
  82
  83 h2. Work reuse
  84
  85 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@.
  86
  87 h2. Referencing files
  88
  89 When running a workflow on an Arvados cluster, the input files must be stored in Keep.  There are several ways this can happen.
  90
  91 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@.
  92
  93 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.
  94
  95 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.
  96
  97 h2. Registering a workflow to use in Workbench
  98
  99 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.
 100
 101 {% include 'register_cwl_workflow' %}
 102
 103 h2. Making workflows directly executable
 104
 105 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:
 106
 107 <notextile>
 108 <pre><code>#!/usr/bin/env cwl-runner
 109 </code></pre>
 110 </notextile>
 111
 112 <notextile>
 113 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">./bwa-mem.cwl bwa-mem-input.yml</span>
 114 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 115 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
 116 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to qr1hi-4zz18-h7ljh5u76760ww2
 117 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job qr1hi-8i9sb-fm2n3b1w0l6bskg
 118 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Running
 119 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Complete
 120 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
 121 {
 122     "aligned_sam": {
 123         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
 124         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 125         "class": "File",
 126         "size": 30738986
 127     }
 128 }
 129 </code></pre>
 130 </notextile>
 131
 132 You can even make an input file directly executable the same way with the following two lines at the top:
 133
 134 <notextile>
 135 <pre><code>#!/usr/bin/env cwl-runner
 136 cwl:tool: <span class="userinput">bwa-mem.cwl</span>
 137 </code></pre>
 138 </notextile>
 139
 140 <notextile>
 141 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">./bwa-mem-input.yml</span>
 142 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 143 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
 144 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to qr1hi-4zz18-h7ljh5u76760ww2
 145 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job qr1hi-8i9sb-fm2n3b1w0l6bskg
 146 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Running
 147 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Complete
 148 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
 149 {
 150     "aligned_sam": {
 151         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
 152         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 153         "class": "File",
 154         "size": 30738986
 155     }
 156 }
 157 </code></pre>
 158 </notextile>
 159
 160 h2. Developing workflows
 161
 162 For an introduction and and detailed documentation about writing CWL, see the "CWL User Guide":http://commonwl.org/v1.0/UserGuide.html and the "CWL Specification":http://commonwl.org/v1.0 .
 163
 164 To run on Arvados, a workflow should provide a @DockerRequirement@ in the @hints@ section.
 165
 166 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.
 167
 168 <notextile>
 169 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arv-get 2463fa9efeb75e099685528b3b9071e0+438/ .</span>
 170 156 MiB / 156 MiB 100.0%
 171 ~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arv-get ae480c5099b81e17267b7445e35b4bc7+180/ .</span>
 172 23 MiB / 23 MiB 100.0%
 173 ~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">cwltool bwa-mem-input.yml bwa-mem-input-local.yml</span>
 174 cwltool 1.0.20160629140624
 175 [job bwa-mem.cwl] /home/example/arvados/doc/user/cwl/bwa-mem$ docker \
 176     run \
 177     -i \
 178     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.ann:/var/lib/cwl/job979368791_bwa-mem/19.fasta.ann:ro \
 179     --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 \
 180     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.sa:/var/lib/cwl/job979368791_bwa-mem/19.fasta.sa:ro \
 181     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.amb:/var/lib/cwl/job979368791_bwa-mem/19.fasta.amb:ro \
 182     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.pac:/var/lib/cwl/job979368791_bwa-mem/19.fasta.pac:ro \
 183     --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 \
 184     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.bwt:/var/lib/cwl/job979368791_bwa-mem/19.fasta.bwt:ro \
 185     --volume=/home/example/arvados/doc/user/cwl/bwa-mem:/var/spool/cwl:rw \
 186     --volume=/tmp/tmpgzyou9:/tmp:rw \
 187     --workdir=/var/spool/cwl \
 188     --read-only=true \
 189     --log-driver=none \
 190     --user=1001 \
 191     --rm \
 192     --env=TMPDIR=/tmp \
 193     --env=HOME=/var/spool/cwl \
 194     biodckr/bwa \
 195     bwa \
 196     mem \
 197     -t \
 198     1 \
 199     -R \
 200     '@RG        ID:arvados_tutorial     PL:illumina     SM:HWI-ST1027_129' \
 201     /var/lib/cwl/job979368791_bwa-mem/19.fasta \
 202     /var/lib/cwl/job979368791_bwa-mem/HWI-ST1027_129_D0THKACXX.1_1.fastq \
 203     /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
 204 [M::bwa_idx_load_from_disk] read 0 ALT contigs
 205 [M::process] read 100000 sequences (10000000 bp)...
 206 [M::mem_pestat] # candidate unique pairs for (FF, FR, RF, RR): (0, 4745, 1, 0)
 207 [M::mem_pestat] skip orientation FF as there are not enough pairs
 208 [M::mem_pestat] analyzing insert size distribution for orientation FR...
 209 [M::mem_pestat] (25, 50, 75) percentile: (154, 181, 214)
 210 [M::mem_pestat] low and high boundaries for computing mean and std.dev: (34, 334)
 211 [M::mem_pestat] mean and std.dev: (185.63, 44.88)
 212 [M::mem_pestat] low and high boundaries for proper pairs: (1, 394)
 213 [M::mem_pestat] skip orientation RF as there are not enough pairs
 214 [M::mem_pestat] skip orientation RR as there are not enough pairs
 215 [M::mem_process_seqs] Processed 100000 reads in 9.848 CPU sec, 9.864 real sec
 216 [main] Version: 0.7.12-r1039
 217 [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
 218 [main] Real time: 10.061 sec; CPU: 10.032 sec
 219 Final process status is success
 220 {
 221     "aligned_sam": {
 222         "size": 30738959,
 223         "path": "/home/example/arvados/doc/user/cwl/bwa-mem/HWI-ST1027_129_D0THKACXX.1_1.sam",
 224         "checksum": "sha1$0c668cca45fef02397bb5302880526d300ee4dac",
 225         "class": "File"
 226     }
 227 }
 228 </code></pre>
 229 </notextile>
 230
 231 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.