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