_episodes/02-workflow.md

   1 ---
   2 title: "Make a workflow by composing tools"
   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. File header
  14
  15 Create a new file "main.cwl"
  16
  17 Start with this header.
  18
  19
  20 ```
  21 cwlVersion: v1.2
  22 class: Workflow
  23 label: RNAseq CWL practice workflow
  24 ```
  25
  26 # 2. Workflow Inputs
  27
  28 The purpose of a workflow is to consume some input parameters, run a
  29 series of steps, and produce output values.
  30
  31 For this analysis, the input parameters are the fastq file and the reference data required by STAR.
  32
  33 In the original shell script, the following variables are declared:
  34
  35 ```
  36 # initialize a variable with an intuitive name to store the name of the input fastq file
  37 fq=$1
  38
  39 # directory with genome reference FASTA and index files + name of the gene annotation file
  40 genome=rnaseq/reference_data
  41 gtf=rnaseq/reference_data/chr1-hg19_genes.gtf
  42 ```
  43
  44 In CWL, we will declare these variables in the `inputs` section.
  45
  46 The inputs section lists each input parameter and its type.  Valid
  47 types include `File`, `Directory`, `string`, `boolean`, `int`, and
  48 `float`.
  49
  50 In this case, the fastq and gene annotation file are individual files.  The STAR index is a directory.  We can describe these inputs in CWL like this:
  51
  52 ```
  53 inputs:
  54   fq: File
  55   genome: Directory
  56   gtf: File
  57 ```
  58
  59 # 3. Workflow Steps
  60
  61 A workflow consists of one or more steps.  This is the `steps` section.
  62
  63 Now we need to describe the first step of the workflow.  This step is to run `fastqc`.
  64
  65 A workflow step consists of the name of the step, the tool to `run`,
  66 the input parameters to be passed to the tool in `in`, and the output
  67 parameters expected from the tool in `out`.
  68
  69 The value of `run` references the tool file.  Tip: while typing the
  70 file name, you can get suggestions and auto-completion on a partial
  71 name using control+space.
  72
  73 The `in` block lists input parameters to the tool and the workflow
  74 parameters that will be assigned to those inputs.
  75
  76 The `out` block lists output parameters to the tool that are used
  77 later in the workflow.
  78
  79 You need to know which input and output parameters are available for
  80 each tool.  In vscode, click on the value of `run` and select "Go to
  81 definition" to open the tool file.  Look for the `inputs` and
  82 `outputs` sections of the tool file to find out what parameters are
  83 defined.
  84
  85 ```
  86 steps:
  87   fastqc:
  88     run: bio-cwl-tools/fastqc/fastqc_2.cwl
  89     in:
  90       reads_file: fq
  91     out: [html_file]
  92 ```
  93
  94 # 4. Running alignment with STAR
  95
  96 STAR has more parameters.  Sometimes we want to provide input values
  97 to a step without making them as workflow-level inputs.  We can do
  98 this with `{default: N}`
  99
 100
 101 ```
 102   STAR:
 103     requirements:
 104       ResourceRequirement:
 105         ramMin: 6000
 106     run: bio-cwl-tools/STAR/STAR-Align.cwl
 107     in:
 108       RunThreadN: {default: 4}
 109       GenomeDir: genome
 110       ForwardReads: fq
 111       OutSAMtype: {default: BAM}
 112       OutSAMunmapped: {default: Within}
 113     out: [alignment]
 114 ```
 115
 116 # 5. Running samtools
 117
 118 The third step is to generate an index for the aligned BAM.
 119
 120 For this step, we need to use the output of a previous step as input
 121 to this step.  We refer the output of a step by with name of the step
 122 (STAR), a slash, and the name of the output parameter (alignment), e.g. `STAR/alignment`
 123
 124 This creates a dependency between steps.  This means the `samtools`
 125 step will not run until the `STAR` step has completed successfully.
 126
 127 ```
 128   samtools:
 129     run: bio-cwl-tools/samtools/samtools_index.cwl
 130     in:
 131       bam_sorted: STAR/alignment
 132     out: [bam_sorted_indexed]
 133 ```
 134
 135 # 6. featureCounts
 136
 137 As of this writing, the `subread` package that provides
 138 `featureCounts` is not available in bio-cwl-tools (and if it has been
 139 added since writing this, let's pretend that it isn't there.)  We will
 140 go over how to write a CWL wrapper for a command line tool in
 141 lesson 3.  For now, we will leave off the final step.
 142
 143 # 7. Workflow Outputs
 144
 145 The last thing to do is declare the workflow outputs in the `outputs` section.
 146
 147 For each output, we need to declare the type of output, and what
 148 parameter has the output value.
 149
 150 Output types are the same as input types, valid types include `File`,
 151 `Directory`, `string`, `boolean`, `int`, and `float`.
 152
 153 The `outputSource` field refers the a step output in the same way that
 154 the `in` block does, the name of the step, a slash, and the name of
 155 the output parameter.
 156
 157 For our final outputs, we want the results from fastqc and the
 158 aligned, sorted and indexed BAM file.
 159
 160 ```
 161 outputs:
 162   qc_html:
 163     type: File
 164     outputSource: fastqc/html_file
 165   bam_sorted_indexed:
 166     type: File
 167     outputSource: samtools/bam_sorted_indexed
 168 ```