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

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Writing a CWL workflow"
   5 ...
   6
   7 {% include 'what_is_cwl' %}
   8
   9 {% include 'tutorial_expectations' %}
  10
  11 h2. Developing workflows
  12
  13 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 .
  14
  15 To run on Arvados, a workflow should provide a @DockerRequirement@ in the @hints@ section.
  16
  17 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.
  18
  19 <notextile>
  20 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arv-get 2463fa9efeb75e099685528b3b9071e0+438/ .</span>
  21 156 MiB / 156 MiB 100.0%
  22 ~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arv-get ae480c5099b81e17267b7445e35b4bc7+180/ .</span>
  23 23 MiB / 23 MiB 100.0%
  24 ~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">cwltool bwa-mem-input.yml bwa-mem-input-local.yml</span>
  25 cwltool 1.0.20160629140624
  26 [job bwa-mem.cwl] /home/example/arvados/doc/user/cwl/bwa-mem$ docker \
  27     run \
  28     -i \
  29     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.ann:/var/lib/cwl/job979368791_bwa-mem/19.fasta.ann:ro \
  30     --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 \
  31     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.sa:/var/lib/cwl/job979368791_bwa-mem/19.fasta.sa:ro \
  32     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.amb:/var/lib/cwl/job979368791_bwa-mem/19.fasta.amb:ro \
  33     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.pac:/var/lib/cwl/job979368791_bwa-mem/19.fasta.pac:ro \
  34     --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 \
  35     --volume=/home/example/arvados/doc/user/cwl/bwa-mem/19.fasta.bwt:/var/lib/cwl/job979368791_bwa-mem/19.fasta.bwt:ro \
  36     --volume=/home/example/arvados/doc/user/cwl/bwa-mem:/var/spool/cwl:rw \
  37     --volume=/tmp/tmpgzyou9:/tmp:rw \
  38     --workdir=/var/spool/cwl \
  39     --read-only=true \
  40     --log-driver=none \
  41     --user=1001 \
  42     --rm \
  43     --env=TMPDIR=/tmp \
  44     --env=HOME=/var/spool/cwl \
  45     biodckr/bwa \
  46     bwa \
  47     mem \
  48     -t \
  49     1 \
  50     -R \
  51     '@RG        ID:arvados_tutorial     PL:illumina     SM:HWI-ST1027_129' \
  52     /var/lib/cwl/job979368791_bwa-mem/19.fasta \
  53     /var/lib/cwl/job979368791_bwa-mem/HWI-ST1027_129_D0THKACXX.1_1.fastq \
  54     /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
  55 [M::bwa_idx_load_from_disk] read 0 ALT contigs
  56 [M::process] read 100000 sequences (10000000 bp)...
  57 [M::mem_pestat] # candidate unique pairs for (FF, FR, RF, RR): (0, 4745, 1, 0)
  58 [M::mem_pestat] skip orientation FF as there are not enough pairs
  59 [M::mem_pestat] analyzing insert size distribution for orientation FR...
  60 [M::mem_pestat] (25, 50, 75) percentile: (154, 181, 214)
  61 [M::mem_pestat] low and high boundaries for computing mean and std.dev: (34, 334)
  62 [M::mem_pestat] mean and std.dev: (185.63, 44.88)
  63 [M::mem_pestat] low and high boundaries for proper pairs: (1, 394)
  64 [M::mem_pestat] skip orientation RF as there are not enough pairs
  65 [M::mem_pestat] skip orientation RR as there are not enough pairs
  66 [M::mem_process_seqs] Processed 100000 reads in 9.848 CPU sec, 9.864 real sec
  67 [main] Version: 0.7.12-r1039
  68 [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
  69 [main] Real time: 10.061 sec; CPU: 10.032 sec
  70 Final process status is success
  71 {
  72     "aligned_sam": {
  73         "size": 30738959,
  74         "path": "/home/example/arvados/doc/user/cwl/bwa-mem/HWI-ST1027_129_D0THKACXX.1_1.sam",
  75         "checksum": "sha1$0c668cca45fef02397bb5302880526d300ee4dac",
  76         "class": "File"
  77     }
  78 }
  79 </code></pre>
  80 </notextile>
  81
  82 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.
  83
  84 h2. Registering a workflow to use in Workbench
  85
  86 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.
  87
  88 <notextile>
  89 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --create-workflow bwa-mem.cwl</span>
  90 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
  91 2016-07-01 12:21:01 arvados.arv-run[15796] INFO: Upload local files: "bwa-mem.cwl"
  92 2016-07-01 12:21:01 arvados.arv-run[15796] INFO: Uploaded to qr1hi-4zz18-7e0hedrmkuyoei3
  93 2016-07-01 12:21:01 arvados.cwl-runner[15796] INFO: Created template qr1hi-p5p6p-rjleou1dwr167v5
  94 qr1hi-p5p6p-rjleou1dwr167v5
  95 </code></pre>
  96 </notextile>
  97
  98 You can provide a partial input file to set default values for the workflow input parameters:
  99
 100 <notextile>
 101 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --create-workflow bwa-mem.cwl bwa-mem-template.yml</span>
 102 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 103 2016-07-01 14:09:50 arvados.arv-run[3730] INFO: Upload local files: "bwa-mem.cwl"
 104 2016-07-01 14:09:50 arvados.arv-run[3730] INFO: Uploaded to qr1hi-4zz18-0f91qkovk4ml18o
 105 2016-07-01 14:09:50 arvados.cwl-runner[3730] INFO: Created template qr1hi-p5p6p-0deqe6nuuyqns2i
 106 qr1hi-p5p6p-0deqe6nuuyqns2i
 107 </code></pre>
 108 </notextile>
 109
 110 h2. Running registered workflows at the command line
 111
 112 You can run a registered workflow at the command line by its UUID:
 113
 114 <notextile>
 115 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner 962eh-7fd4e-660fw86nz0w77mk bwa-mem-input.yml</span>
 116 </code></pre>
 117 </notextile>
 118
 119 h2. Making workflows directly executable
 120
 121 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:
 122
 123 <notextile>
 124 <pre><code>#!/usr/bin/env cwl-runner
 125 </code></pre>
 126 </notextile>
 127
 128 <notextile>
 129 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">./bwa-mem.cwl bwa-mem-input.yml</span>
 130 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 131 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
 132 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to qr1hi-4zz18-h7ljh5u76760ww2
 133 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job qr1hi-8i9sb-fm2n3b1w0l6bskg
 134 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Running
 135 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Complete
 136 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
 137 {
 138     "aligned_sam": {
 139         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
 140         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 141         "class": "File",
 142         "size": 30738986
 143     }
 144 }
 145 </code></pre>
 146 </notextile>
 147
 148 You can even make an input file directly executable the same way with the following two lines at the top:
 149
 150 <notextile>
 151 <pre><code>#!/usr/bin/env cwl-runner
 152 cwl:tool: <span class="userinput">bwa-mem.cwl</span>
 153 </code></pre>
 154 </notextile>
 155
 156 <notextile>
 157 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">./bwa-mem-input.yml</span>
 158 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 159 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
 160 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to qr1hi-4zz18-h7ljh5u76760ww2
 161 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job qr1hi-8i9sb-fm2n3b1w0l6bskg
 162 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Running
 163 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Complete
 164 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
 165 {
 166     "aligned_sam": {
 167         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
 168         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 169         "class": "File",
 170         "size": 30738986
 171     }
 172 }
 173 </code></pre>
 174 </notextile>
 175
 176 h3. Control a workflow locally
 177
 178 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, however, the jobs themselves will still run on the Arvados cluster.  With @--local@, if you interrupt @arvados-cwl-runner@ or log out, the workflow will be terminated.
 179
 180 <notextile>
 181 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --local bwa-mem.cwl bwa-mem-input.yml</span>
 182 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 183 2016-07-01 10:05:19 arvados.cwl-runner[16290] INFO: Pipeline instance qr1hi-d1hrv-92wcu6ldtio74r4
 184 2016-07-01 10:05:28 arvados.cwl-runner[16290] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-2nzzfbuf9zjrj4g) is Queued
 185 2016-07-01 10:05:29 arvados.cwl-runner[16290] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-2nzzfbuf9zjrj4g) is Running
 186 2016-07-01 10:05:45 arvados.cwl-runner[16290] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-2nzzfbuf9zjrj4g) is Complete
 187 2016-07-01 10:05:46 arvados.cwl-runner[16290] INFO: Overall process status is success
 188 {
 189     "aligned_sam": {
 190         "size": 30738986,
 191         "path": "keep:15f56bad0aaa7364819bf14ca2a27c63+88/HWI-ST1027_129_D0THKACXX.1_1.sam",
 192         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 193         "class": "File"
 194     }
 195 }
 196 </code></pre>
 197 </notextile>