Cromwell +WDL学习

WDL （一个workflow description language）+ Cromwell（an execution engine that can run WDL scripts）是目前可以更好使用GATK的一套工具。这里学习wdl的快速入门教程。
WDL是一种流程编写语言，没有太多复杂的逻辑和语法，入门简单。首先看一个hello world的例子

workflow myWorkflow {
    call myTask
}
task myTask {
    command {
        echo "hello world"
    }
    output {
        String out = read_string(stdout())
    }
}

对于一个WDL脚本而言，有以下5个核心结构

• workflow

• task

• call

• command

• output

每个脚本包含1个workflow， workflow由多个task构成。 在workflow中，通过call调用对应的task。每个task在workflow代码块之外单独定义。

task代表任务，读取输入文件，执行相应命令，然后输出。command中对应的就是执行的命令，比如一条具体的gatk的命令，output 指定task的输出值。可以将task理解为编程语言中的函数，每个函数读取输入的参数，执行代码，然后返回，command对应执行的具体代码，output对应返回值。

基础结构

• 顶层组件: workflow, task and call
  workflow在顶层，用calls去执行tasks。tasks在workflow模块外被定义。

workflow myWorkFlowName {
    call task_A
    call task_B
}
task task_A{...}
task task_B{...}

• 核心任务级别的组件: command and output
  task的核心成分：command被运行，output明确指出哪一部分命令组成了输出。

task task_A {
    command {...}
    output {...}
}

• 添加变量
  有2种不同层次的variables，一种存在于task，一种存在于整个workflow。variable也可以从一个task传递到下一个task。

• Adding task-level variables
  下面，task 有3个输入的参数，文件类型的ref，in 和字符串类型的id。 在command中，通过${ref}这种格式访问变量的值

task task_A {
    File ref
    File in
    String id
    command {
    do_stuff R=${ref} I=${in} O=${id}.ext
    }
    output {
    File out="${id}.ext"
    }
}

• Adding workflow-level variables
  下面， workflow 有3个参数，文件类型的my_ref，my_input 和字符串类型的name。传递这3个参数给task时，直接传变量名就可以了。

workflow myWorkflowName {
    File my_ref
    File my_input
    String name
    call task_A {
    input: ref=my_ref, in=my_input, id=name
    }
    call task_B {
    input: ref=my_ref, in=task_A.out
    }
}
task task_A{...}
task task_B{...}

添加管道

• 前一个task的输出，作为后一个task的输入

workflow LinearChain {
  File firstInput
  call stepA { input: in=firstInput }
  call stepB { input: in=stepA.out }
  call stepC { input: in=stepB.out }
}
task stepA {
  File in
  command { programA I=${in} O=outputA.ext }
  output { File out = "outputA.ext" }
}
task stepB {
  File in
  command { programB I=${in} O=outputB.ext }
  output { File out = "outputB.ext" }
}
task stepC {
  File in
  command { programC I=${in} O=outputC.ext }
  output { File out = "outputC.ext" }

• 一个task的多个输出作为下一个task的输入
  

workflow MultiOutMultiIn {
  File firstInput
  call stepA { input: in=firstInput }
  call stepB { input: in=stepA.out }
  call stepC { input: in1=stepB.out1, in2=stepB.out2 }
}
task stepA {
  File in
  command { programA I=${in} O=outputA.ext }
  output { File out = "outputA.ext" }
}
task stepB {
  File in
  command { programB I=${in} O1=outputB1.ext O2=outputB2.ext }
  output {
    File out1 = "outputB1.ext"
    File out2 = "outputB2.ext" }
}
task stepC {
  File in1
  File in2
  command { programB I1=${in1} I2=${in2} O=outputC.ext }
  output { File out = "outputC.ext" }
}

• 多对多的依赖关系
  一个task的输出作为多个task的输入，或者多个task的输出作为1个task的输入
  

workflow BranchAndMerge {
  File firstInput
  call stepA { input: in=firstInput }
  call stepB { input: in=stepA.out }
  call stepC { input: in=stepA.out }
  call stepD { input: in1=stepC.out, in2=stepB.out }
}
task stepA {
  File in
  command { programA I=${in} O=outputA.ext }
  output { File out = "outputA.ext" }
}
task stepB {
  File in
  command { programB I=${in} O=outputB.ext }
  output { File out = "outputB.ext" }
}
task stepC {
  File in
  command { programC I=${in} O=outputC.ext }
  output { File out = "outputC.ext" }
}
task stepD {
  File in1
  File in2
  command { programD I1=${in1} I2=${in2} O=outputD.ext }
  output { File out = "outputD.ext" }
}

• 平行关系
  多个task之间完全平行，可以并行执行
  
  Parallelism即平行可以使得任务更快，而非顺序进行。我们使用了基于WDL standard library的scatter，会产生可平行的任务（成为一列Input，array），并且会输出结果（也是array）。Scatter这个过程是外显的（explicit），而gather这个过程是不外显的（implicit）。

workflow ScatterGather {
  Array[File] inputFiles
  scatter (oneFile in inputFiles) {
    call stepA { input: in=oneFile }
  }
  call stepB { input: files=stepA.out }
}
task stepA {
  File in
  command { programA I=${in} O=outputA.ext }
  output { File out = "outputA.ext" }
}
task stepB {
  Array[File] files
  command { programB I=${files} O=outputB.ext }
  output { File out = "outputB.ext" }
}

• 任务混叠
  task和函数还是有一定的区别，函数可以在代码中多次调用，但是task多次调用会有风险。下面的示意图中，stepA 运行两次，一次作为stepB的输入，一次作为stepC的输入。如果stepA的两次调用并行执行，当执行完之后，在传递给下一个task时，由于存在两个同名的stepA, stepB和stepC 就会无法正确接受参数。
  
  WDL中提供了解决方案，叫做task alias, 为task起一个别名，示例如下

workflow taskAlias {
  File firstInput
  File secondInput
  call stepA as firstSample { input: in=firstInput }
  call stepA as secondSample { input: in=secondInput }
  call stepB { input: in=firstSample.out }
  call stepC { input: in=secondSample.out }
}
task stepA {
  File in
  command { programA I=${in} O=outputA.ext }
  output { File out = "outputA.ext" }
}
task stepB {
  File in
  command { programB I=${in} O=outputB.ext }
  output { File out = "outputB.ext" }
}
task stepC {
  File in
  command { programC I=${in} O=outputC.ext }
  output { File out = "outputC.ext" }
}

在WDL脚本中, 理论上每个task 只可以调用1次，如果希望多次调用，必须借助task alias。

运行脚本

掌握以上几点，就可以理解一个wdl脚本的整体框架了。在实际使用中，我们只要能理解整个workflow的流向，会使用wdl脚本就可以了。
运行wdl脚本，需要两个文件

1. cromwell.jar
2. womtools.jar

最新版的下载链接如下：

https://github.com/broadinstitute/cromwell/releases

第一步是得到输入参数的列表，用法如下

java -jar womtools.jar inputs myWorkflow.wdl > myWorkflow_inputs.json

用json格式存存储，这一步得到的只是一个模板，需要编辑这个文件，将对应的参数替换成实际的参数
第二步运行脚本，用法如下

java -jar Cromwell.jar run myWorkflow.wdl -i myWorkflow_inputs.json

总结

WDL是一种流程管理语言，语法简单，内置的支持并行等特征，适合编写pipeline。

运行wdl脚本只需两步，第一步编辑参数列表对应的json文件，第二步直接运行即可。