如何用wdl编写生信流程

作者：童蒙
审稿：同尘
编辑：amethyst

引言

生信分析离不开各种各样的流程。一个好的流程可以帮我们快速的完成各种各样的分析。然而，如何让我们的流程有更高的复用性，可移植性，稳定性，对于流程的使用而言，也非常的重要。

现状

对于如何进行生信分析，相信是八仙过海，各显神通。如果实现一个简单文件的文件，可能执行某条语句或运行某个软件即可。如果满足一套复杂的要求，可能需要多条语句，用makefile，bash，或其他脚本语言串连成一个模块即可。如果减少一套分析方案的手动执行过程，则需要将多个模块串成pipeline或workflow…

workflow搭建就像将各个零件按设计图纸组装成机器一样，图纸不同，机器不同。但是如果各部分零件的规格和接口都不一样，图纸再简单，也是个复杂的工程，甚至只能一次次调整，耗时又耗力。目前生信分析的模块就是这样，没有统一的构建标准。

除了对流程进行定义缺乏标准外，如何调度和监控的任务，实现任务的并发、资源调度也是一件让人抓狂的事情。WDL是board推出的一套便于human readable and writable的流程编写规则，其主要的特点在于更适合于生信人员（而非纯IT人员）来书写流程。

例子

我们先看一个hello_world的案例

task hello {
  input {
    String pattern
    File in
  }

  command {
    egrep '${pattern}' '${in}'
  }

  runtime {
    docker: "broadinstitute/my_image"
  }

  output {
    Array[String] matches = read_lines(stdout())
  }
}

workflow wf {
  call hello
}

具体介绍前，从上面的例子我们可以总结WDL 的一些特点:

（1）分层清晰，即使不了解WDL也能明白每部分的作用；
（2）明确定义输入和输出，方便模块间引用。

WDL组件

WDL核心是两大部分，task 和 workflow，二者组成结构相似，具体如下：

1. task

task是对模块的定义，把通常用的一些命令组合到一起，形成一个复用程度高的集合。以下部分wdl中task包括的元素：

input
为该task的输入模块。如果该模块有外部输入，则是必须提供该部分。
在input内部，主要是进行变量的声明。变量的声明格式为 Type（？+） name=value ,value可以不存在，由外来传入。

其中Type的类型有String、Int、Float、Boolean、File、Array、Pair、Map，以及自定义的Struct类型。

?表示变量可不用传入信息，+只能跟在Aarry后面，表示数组至少有一个元素。

当定义为File类型时，会自动检查文件是否存在，不存在会报错。

有以下例子:

Int? i                     # An integer value, i is optional
Float f = 27.3             # A floating point number
Boolean b = true           # A boolean true/false
String s = "hello, world"  # A string value
File f = "path/to/file"    # A file
Array[Int] a1

声明内部也支持各种表达式的，例如“+-*/”等，这一块跟所有的编程语言很类似，不再赘述。

input之外的声明
input的声明是为了参数外传，对于task里的其他中间变量可以写在input外面。
这一部分是可选，写到input里面和外面好像效果都是一样的。

command
具体执行的命令，最基本的是shell，也支持其他语言的嵌套，软件的运行命令等。shell的所有语法，基本在这个代码块中都适用。例如hello_world中的

egrep '${pattern}' '${in}'

其中{pattern} 是变量的引用，也可以用～｛pattern｝来引用。官方建议用~｛pattern｝来引用。

runtime
配置该task的运行环境，一般有docker，memory，cpu等。这一块用来设置运行的环境、资源等，需要根据不同的运行平台进行设置。也可以是变量，由外部来导入。

output
输出模块，如果有输出，则一定要申明，其他模块在调用该模块的结果时可以直接引用，比如调用例子的结果方式是：hello.matches
声明的方式同input中一样，也支持表达式，例如“+-*/”等，如 ${name}+"txt"也支持变量的内插，例如${name}.txt”，当输出类型是File时，建议value值用双引号引起来，这样在下一个模块调用时才是绝对路径。
output中有个glob，可以glob某个pattern的文件，返回一个array。在某些情况下会很有用。
在output中还支持很多函数，例如read_int()，详情见3中函数部分。

meta
可选，例如存放作者和版本信息等。

parameter_meta
可选，相当于-h 里面的信息。可以使用wdl-aid来生成wdl的文档，方便分享。

2. workflow

将定义的task有机组合到一起，就形成了我们常说的流程。流程通常是DAG（有向无环图）的瀑布模式。
一个wdl里面只能有一个workflow定义，否则会报错。workflow的组成和task很相似，input，output，meta等定义方式一致，不再赘述。需要说明的是，workflow的output可以直接引用task的结果，比如：

output {
    File outfile1=task1.result
    File outfile2=task2.result
}

workflow与task最大的不同是没有command，而是有call，即调用task任务，同时为实现多样的DAG关系也存在特殊定义，比如scatter，if等，具体说明如下。

call
call是对task的直接调用，可以直接使用input的参数，也可以调用其他task的结果。正是因为call的顺序和输入输出的先后依赖关系，才构成了workflow的主要DAG关系。示例如下:

call my_task as my_task_alias2 {
    input: 
        threshold=threshold,
        file1=task1.output1,
        file2=task2.output1
  }

my_task是定义好的task名称，as后面是调用的时候的名称，如果同一个模块进行多次调用，需要给不同的别名，以便来区分每次调用后的输出。大括号里面的input，是将workflow的变量传参到task里, 在workflow里面变量直接调用即可，不需要$和双引号。

scatter
一个流程除了串联，还有并发，这个可以用scatter结合Array来实现。这个特性适用于我们有多个样品或多个文件，并发运行相同的分析，从而有效的节省时间，让DAG更简洁。示例如下：

scatter (i in integers) {
call task1{input: num=i}
call task2{input: num=task1.output}
}

scatter 和for循环不同，它是一种并发关系。在此例中，integers是一个array，调度器会对array里面的元素进行并发处理，而不是一个个循环处理。

if
对变量进行判断，选择性运行某个task。注意这个语法没有else。

if(number!=1) { call task1 {input: num=i} }

其他

import
使用import 可以导入task.wdl 或者sub-workflow.wdl，被workflow直接调用。

import "~/wdl/hello_word.wdl" as hello

sub-workflow
workflow本身可以被另一个workflow import进去，以sub-workflow的形式被调用，可以很方便地作为一个整体去复用。

函数
wdl提供了许多标准的函数来帮助实现简单的读写功能。常用有：

• stdout（）：标准输出流
• stderr（）：标准错误流
• read_lines（）：按行读取，返回array
  其他的见说明

定义struct

struct Person {
    String name
    Int age
    File input1
}

声明：Person a
调用：a.name

使用

WDL可以用cromwell（java） 或者widdler（python）运行，在下载cromwell（https://github.com/broadinstitute/cromwell/releases）时，可以同时下载womtool。womtool可以根据WDL内需要的的input变量生成一个json版的输入文件模板。

输入文件
使用womtools 生成

java -jar womtool-48.jar inputs test.wdl 

即可生成json文件，根据提示的File，Int，Array输入不同的类型的数据：

{
  "task1.inputfile": "new.txt",
  "task1.age": "18",
  "task1.word": "Say hello"
  "task1.samples": ["jia","yi"],
  "task1.info": [{"name":"jia","math":"89"},{"name":"yi","math":"93"}]
}

cromwell简单运行

java -Dconfig.file=test.config -jar cromwell-48.jar run hello_world.wdl -i input.json -o workflow.json

各种配置具体可以查看cromwell官网（https://cromwell.readthedocs.io/en/develop/）

-Dconfig.file 流程配置文件（可选）
可以设置一系列配置信息，比如打开断点续跑功能Call Cache。

call-caching {
  enabled = true
  invalidate-bad-cache-results = true
}

run *.wdl 一种运行模式
run模式用于本地测试一个独立的WDL, 不用配置任何信息，简单粗暴，直接运行WDL。另一种模式是server，服务器引擎模式，依赖于环境配置。

-i 输入文件
上面提到的WDL需要的各种参数形成的json文件。

-o workflow 配置文件
可以配置workflow的一下信息，比如最后的目录整理。

{
  "final_workflow_outputs_dir": ""~/Result",
  "use_relative_output_paths": true,
  "final_workflow_log_dir": "~/Log",
  "write_to_cache": true,
  "read_from_cache": true
}

输出结果
输出分为层级，里面包含输入输出，运行脚本，日志，等各种信息记录。

ref

https://github.com/openwdl/wdl/blob/master/versions/1.0/SPEC.md#arrayint-rangeint