_episodes/03-running.md

   1 ---
   2 title: "Running and Debugging a Workflow"
   3 teaching: 15
   4 exercises: 20
   5 questions:
   6 - "How do I provide input to run a workflow?"
   7 - "What should I do if the workflow fails?"
   8 objectives:
   9 - "Write an input parameter file."
  10 - "Execute the workflow."
  11 - "Diagnose workflow errors."
  12 keypoints:
  13 - "The input parameter file is a YAML file with values for each input parameter."
  14 - "A common reason for a workflow step fails is insufficient RAM."
  15 - "Use ResourceRequirement to set the amount of RAM to be allocated to the job."
  16 - "Output parameter values are printed as JSON to standard output at the end of the run."
  17 ---
  18
  19 # The input parameter file
  20
  21 CWL input values are provided in the form of a YAML or JSON file.
  22 create a called file
  23
  24 This file gives the values for parameters declared in the `inputs`
  25 section of our workflow.  Our workflow takes `fq`, `genome` and `gtf`
  26 as input parameters.
  27
  28 When setting inputs, Files and Directories are given as an object with
  29 `class: File` or `class: Directory`.  This distinguishes them from
  30 plain strings that may or may not be file paths.
  31
  32 Note: if you don't have example sequence data or the STAR index files, see [setup](/setup.html).
  33
  34 {% assign tabs = "generic, arvados" | split: ", " %}
  35 {% capture generic_tab_content %}
  36 main-input.yaml
  37 ```
  38 fq:
  39   class: File
  40   location: rnaseq/raw_fastq/Mov10_oe_1.subset.fq
  41   format: http://edamontology.org/format_1930
  42 genome:
  43   class: Directory
  44   location: hg19-chr1-STAR-index
  45 gtf:
  46   class: File
  47   location: rnaseq/reference_data/chr1-hg19_genes.gtf
  48 ```
  49 {: .language-yaml }
  50
  51 > ## Running the workflow
  52 >
  53 > Type this into the terminal:
  54 >
  55 > ```
  56 > cwl-runner main.cwl main-input.yaml
  57 > ```
  58 > {: .language-bash }
  59 >
  60 > This may take a few minutes to run, and will print some amount of
  61 > logging.  The logging you see, how access other logs, and how to
  62 > track workflow progress will depend on your CWL runner platform.
  63 {: .challenge }
  64 {% endcapture %}
  65
  66 {% capture arvados_tab_content %}
  67 main-input.yaml
  68 ```
  69 fq:
  70   class: File
  71   location: keep:9178fe1b80a08a422dbe02adfd439764+925/raw_fastq/Mov10_oe_1.subset.fq
  72   format: http://edamontology.org/format_1930
  73 genome:
  74   class: Directory
  75   location: keep:02a12ce9e2707610991bd29d38796b57+2912
  76 gtf:
  77   class: File
  78   location: keep:9178fe1b80a08a422dbe02adfd439764+925/reference_data/chr1-hg19_genes.gtf
  79 ```
  80 {: .language-yaml }
  81
  82 > ## Running the workflow
  83 >
  84 > If you are using VSCode with Arvados tasks, select `main.cwl` and
  85 > then use the `Run CWL Workflow on Arvados` task.
  86 >
  87 {: .challenge }
  88 {% endcapture %}
  89
  90 <div class="tabbed">
  91   <ul class="tab">
  92     {% for tab in tabs %}
  93       <li><a href="#section-{{ tab }}">{{ tab }}</a></li>
  94     {% endfor %}
  95   </ul>
  96
  97   <section id="section-generic">{{ generic_tab_content | markdownify}}</section>
  98   <section id="section-arvados">{{ arvados_tab_content | markdownify}}</section>
  99 </div>
 100
 101 # Debugging the workflow
 102
 103 Depending on whether and how your workflow platform enforces memory
 104 limits, your workflow may fail.  Let's talk about what to do when a
 105 workflow fails.
 106
 107 A workflow can fail for many reasons: some possible reasons include
 108 bad input, bugs in the code, or running out memory.  In our example,
 109 the STAR workflow may fail with an out of memory error.
 110
 111 To help diagnose these errors, the workflow runner produces logs that
 112 record what happened, either in the terminal or the web interface.
 113
 114 Some errors you might see in the logs that would indicate an out of
 115 memory condition:
 116
 117 ```
 118 EXITING: fatal error trying to allocate genome arrays, exception thrown: std::bad_alloc
 119 Possible cause 1: not enough RAM. Check if you have enough RAM 5711762337 bytes
 120 Possible cause 2: not enough virtual memory allowed with ulimit. SOLUTION: run ulimit -v 5711762337
 121 ```
 122
 123 or
 124
 125 ```
 126 Container exited with code: 137
 127 ```
 128
 129 (Exit code 137 most commonly occurs when a container goes "out of memory" and is terminated by the operating system).
 130
 131 If this happens, you will need to request more RAM.
 132
 133 # Setting runtime RAM requirements
 134
 135 By default, a step is allocated 256 MB of RAM.  From the STAR error message:
 136
 137 > Check if you have enough RAM 5711762337 bytes
 138
 139 We can see that STAR requires quite a bit more RAM than 256 MB.  To
 140 request more RAM, add a "requirements" section with
 141 "ResourceRequirement" to the "STAR" step:
 142
 143 ```
 144   STAR:
 145     requirements:
 146       ResourceRequirement:
 147         ramMin: 9000
 148     run: bio-cwl-tools/STAR/STAR-Align.cwl
 149         ...
 150 ```
 151 {: .language-yaml }
 152
 153 Resource requirements you can set include:
 154
 155 * coresMin: CPU cores
 156 * ramMin: RAM (in megabytes)
 157 * tmpdirMin: temporary directory available space
 158 * outdirMin: output directory available space
 159
 160 > ## Running the workflow
 161 >
 162 > Now that you've fixed the workflow, run it again.
 163 >
 164 {: .challenge }
 165
 166 > ## Episode solution
 167 > * <a href="../assets/answers/ep3/main.cwl">main.cwl</a>
 168 {: .solution}
 169
 170 # Workflow results
 171
 172 The CWL runner will print a results JSON object to standard output.  It will look something like this (it may include additional fields).
 173
 174 <div>
 175 {% tabs output %}
 176
 177 {% tab output generic %}
 178 ```
 179 {
 180     "bam_sorted_indexed": {
 181         "location": "file:///home/username/rnaseq-cwl-training-exercises/Aligned.sortedByCoord.out.bam",
 182         "basename": "Aligned.sortedByCoord.out.bam",
 183         "class": "File",
 184         "size": 25370707,
 185         "secondaryFiles": [
 186             {
 187                 "basename": "Aligned.sortedByCoord.out.bam.bai",
 188                 "location": "file:///home/username/rnaseq-cwl-training-exercises/Aligned.sortedByCoord.out.bam.bai",
 189                 "class": "File",
 190                 "size": 176552,
 191             }
 192         ]
 193     },
 194     "qc_html": {
 195         "location": "file:///home/username/rnaseq-cwl-training-exercises/Mov10_oe_1.subset_fastqc.html",
 196         "basename": "Mov10_oe_1.subset_fastqc.html",
 197         "class": "File",
 198         "size": 383589
 199     }
 200 }
 201 ```
 202 {: .language-yaml }
 203 {% endtab %}
 204
 205 {% tab output arvados %}
 206 ```
 207 {
 208     "bam_sorted_indexed": {
 209         "basename": "Aligned.sortedByCoord.out.bam",
 210         "class": "File",
 211         "location": "keep:2dbaaef5aefd558e37f14280e47091a9+327/Aligned.sortedByCoord.out.bam",
 212         "secondaryFiles": [
 213             {
 214                 "basename": "Aligned.sortedByCoord.out.bam.bai",
 215                 "class": "File",
 216                 "location": "keep:2dbaaef5aefd558e37f14280e47091a9+327/Aligned.sortedByCoord.out.bam.bai"
 217             }
 218         ],
 219         "size": 25370695
 220     },
 221     "qc_html": {
 222         "basename": "Mov10_oe_1.subset_fastqc.html",
 223         "class": "File",
 224         "location": "keep:2dbaaef5aefd558e37f14280e47091a9+327/Mov10_oe_1.subset_fastqc.html",
 225         "size": 383589
 226     }
 227 }
 228 ```
 229 {: .language-yaml }
 230 {% endtab %}
 231 {% endtabs %}
 232 </div>
 233
 234 This has a similar structure as `main-input.yaml`.  The each output
 235 parameter is listed, with the `location` field of each `File` object
 236 indicating where the output file can be found.
 237