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