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 "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 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: 7000
 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     "qc_summary": {
 147         "location": "file:///home/username/rnaseq-cwl-training-exercises/summary.txt",
 148         "basename": "summary.txt",
 149         "class": "File",
 150         "size": 590
 151     }
 152 }
 153 ```
 154
 155 This has the same structure as `input.yaml`.  The each output
 156 parameter is listed, with the `location` field of each `File` object
 157 indicating where the output file can be found.
 158
 159 # Appendix
 160
 161 ## Downloading sample and reference data
 162
 163 Start from your rnaseq-cwl-exercises directory.
 164
 165 ```
 166 mkdir rnaseq
 167 cd rnaseq
 168 wget --mirror --no-parent --no-host --cut-dirs=1 https://download.pirca.arvadosapi.com/c=9178fe1b80a08a422dbe02adfd439764+925/
 169 ```
 170
 171 ## Downloading or generating STAR index
 172
 173 Running STAR requires index files generated from the reference.
 174
 175 This is a rather large download (4 GB).  Depending on your bandwidth, it may be faster to generate it yourself.
 176
 177 ### Downloading
 178
 179 Go to the "Terminal" tab in the lower vscode panel.  If necessary, select `bash` from the dropdown list in the upper right corner.
 180
 181 ```
 182 mkdir hg19-chr1-STAR-index
 183 cd hg19-chr1-STAR-index
 184 wget --mirror --no-parent --no-host --cut-dirs=1 https://download.pirca.arvadosapi.com/c=02a12ce9e2707610991bd29d38796b57+2912/
 185 ```
 186
 187 ### Generating
 188
 189 Create `chr1-star-index.yaml`:
 190
 191 ```
 192 InputFiles:
 193   - class: File
 194     location: rnaseq/reference_data/chr1.fa
 195     format: http://edamontology.org/format_1930
 196 IndexName: 'hg19-chr1-STAR-index'
 197 Gtf:
 198   class: File
 199   location: rnaseq/reference_data/chr1-hg19_genes.gtf
 200 Overhang: 99
 201 ```
 202
 203 Next, go to the "Terminal" tab in the lower vscode panel.  If
 204 necessary, select `bash` from the dropdown list in the upper right
 205 corner.  Generate the index with your local cwl-runner.
 206
 207 ```
 208 cwl-runner bio-cwl-tools/STAR/STAR-Index.cwl chr1-star-index.yaml
 209 ```