_episodes/03-running.md

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