lesson2/lesson2.md

   1 # Running and debugging a workflow
   2
   3 ### 1. The input parameter file
   4
   5 CWL input values are provided in the form of a YAML or JSON file.
   6 Create one by right clicking on the explorer, select "New File" and
   7 create a called file "main-input.yaml".
   8
   9 This file gives the values for parameters declared in the `inputs`
  10 section of our workflow.  Our workflow takes `fq`, `genome` and `gtf`
  11 as input parameters.
  12
  13 When setting inputs, Files and Directories are given as an object with
  14 `class: File` or `class: Directory`.  This distinguishes them from
  15 plain strings that may or may not be file paths.
  16
  17 Note: if you don't have example sequence data or the STAR index files, see the Appendix below.
  18
  19 ```
  20 fq:
  21   class: File
  22   location: rnaseq/raw_fastq/Mov10_oe_1.subset.fq
  23   format: http://edamontology.org/format_1930
  24 genome:
  25   class: Directory
  26   location: hg19-chr1-STAR-index
  27 gtf:
  28   class: File
  29   location: rnaseq/reference_data/chr1-hg19_genes.gtf
  30 ```
  31
  32 On Arvados, do this:
  33
  34 ```
  35 fq:
  36   class: File
  37   location: keep:9178fe1b80a08a422dbe02adfd439764+925/raw_fastq/Mov10_oe_1.subset.fq
  38   format: http://edamontology.org/format_1930
  39 genome:
  40   class: Directory
  41   location: keep:02a12ce9e2707610991bd29d38796b57+2912
  42 gtf:
  43   class: File
  44   location: keep:9178fe1b80a08a422dbe02adfd439764+925/reference_data/chr1-hg19_genes.gtf
  45 ```
  46
  47 ### 2. Running the workflow
  48
  49 Type this into the terminal:
  50
  51 ```
  52 cwl-runner main.cwl main-input.yaml
  53 ```
  54
  55 ### 3. Debugging the workflow
  56
  57 A workflow can fail for many reasons: some possible reasons include
  58 bad input, bugs in the code, or running out memory.  In this case, the
  59 STAR workflow might fail with an out of memory error.
  60
  61 To help diagnose these errors, the workflow runner produces logs that
  62 record what happened, either in the terminal or the web interface.
  63
  64 Some errors you might see in the logs that would indicate an out of
  65 memory condition:
  66
  67 ```
  68 EXITING: fatal error trying to allocate genome arrays, exception thrown: std::bad_alloc
  69 Possible cause 1: not enough RAM. Check if you have enough RAM 5711762337 bytes
  70 Possible cause 2: not enough virtual memory allowed with ulimit. SOLUTION: run ulimit -v 5711762337
  71 ```
  72
  73 or
  74
  75 ```
  76 Container exited with code: 137
  77 ```
  78
  79 (Exit code 137 most commonly occurs when a container goes "out of memory" and is terminated by the operating system).
  80
  81 If this happens, you will need to request more RAM.
  82
  83 ### 4. Setting runtime RAM requirements
  84
  85 By default, a step is allocated 256 MB of RAM.  From the STAR error message:
  86
  87 > Check if you have enough RAM 5711762337 bytes
  88
  89 We can see that STAR requires quite a bit more RAM than that.  To
  90 request more RAM, add a "requirements" section with
  91 "ResourceRequirement" to the "STAR" step:
  92
  93 ```
  94   STAR:
  95     requirements:
  96       ResourceRequirement:
  97         ramMin: 8000
  98     run: bio-cwl-tools/STAR/STAR-Align.cwl
  99 ```
 100
 101 Resource requirements you can set include:
 102
 103 * coresMin: CPU cores
 104 * ramMin: RAM (in megabytes)
 105 * tmpdirMin: temporary directory available space
 106 * outdirMin: output directory available space
 107
 108 After setting the RAM requirements, re-run the workflow.
 109
 110 ### 5. Workflow results
 111
 112 The CWL runner will print a results JSON object to standard output.  It will look something like this (it may include additional fields).
 113
 114
 115 ```
 116 {
 117     "bam_sorted_indexed": {
 118         "location": "file:///home/username/rnaseq-cwl-training-exercises/Aligned.sortedByCoord.out.bam",
 119         "basename": "Aligned.sortedByCoord.out.bam",
 120         "class": "File",
 121         "size": 25370707,
 122         "secondaryFiles": [
 123             {
 124                 "basename": "Aligned.sortedByCoord.out.bam.bai",
 125                 "location": "file:///home/username/rnaseq-cwl-training-exercises/Aligned.sortedByCoord.out.bam.bai",
 126                 "class": "File",
 127                 "size": 176552,
 128             }
 129         ]
 130     },
 131     "qc_html": {
 132         "location": "file:///home/username/rnaseq-cwl-training-exercises/Mov10_oe_1.subset_fastqc.html",
 133         "basename": "Mov10_oe_1.subset_fastqc.html",
 134         "class": "File",
 135         "size": 383589
 136     }
 137 }
 138 ```
 139
 140 This has the same structure as `main-input.yaml`.  The each output
 141 parameter is listed, with the `location` field of each `File` object
 142 indicating where the output file can be found.
 143
 144 # Appendix
 145
 146 ## Downloading sample and reference data
 147
 148 Start from your rnaseq-cwl-exercises directory.
 149
 150 ```
 151 mkdir rnaseq
 152 cd rnaseq
 153 wget --mirror --no-parent --no-host --cut-dirs=1 https://download.pirca.arvadosapi.com/c=9178fe1b80a08a422dbe02adfd439764+925/
 154 ```
 155
 156 ## Downloading or generating STAR index
 157
 158 Running STAR requires index files generated from the reference.
 159
 160 This is a rather large download (4 GB).  Depending on your bandwidth, it may be faster to generate it yourself.
 161
 162 ### Downloading
 163
 164 ```
 165 mkdir hg19-chr1-STAR-index
 166 cd hg19-chr1-STAR-index
 167 wget --mirror --no-parent --no-host --cut-dirs=1 https://download.pirca.arvadosapi.com/c=02a12ce9e2707610991bd29d38796b57+2912/
 168 ```
 169
 170 ### Generating
 171
 172 Create `chr1-star-index.yaml`:
 173
 174 ```
 175 InputFiles:
 176   - class: File
 177     location: rnaseq/reference_data/chr1.fa
 178     format: http://edamontology.org/format_1930
 179 IndexName: 'hg19-chr1-STAR-index'
 180 Gtf:
 181   class: File
 182   location: rnaseq/reference_data/chr1-hg19_genes.gtf
 183 Overhang: 99
 184 ```
 185
 186 Generate the index with your local cwl-runner.
 187
 188 ```
 189 cwl-runner bio-cwl-tools/STAR/STAR-Index.cwl chr1-star-index.yaml
 190 ```