我們為什麼需要标準的工作流描述語言

在構造生物資訊工作流時，如果不使用标準工作流描述語言，我們一般是使用腳本語言來構造：

直接采用shell、R、Python 等編寫腳本，封裝基因計算軟體的指令行
多個腳本組成一個工作流
執行時輸入參數執行指令行

這種方式構造的工作流，在使用過程中可能面臨下面的挑戰：

不同的基因流程可能使用不同的腳本語言、對使用者的計算機技能要求較高
腳本類的工作流的執行，無專業的解析引擎，運作狀态無法監控
腳本健壯性要求高，如果錯誤處理沒有做好，可能造成時間和資源的浪費

如果您也遇到了上面的痛點，那麼您急需要引入标準的工作流來規範流程。比如 WDL 就是個很好的選擇。

WDL

什麼是 WDL

是 Workflow Description Language的縮寫，有時也寫作 Workflow Definition Language，是美國

Broad Institute

推出的工作流描述語言。

經過幾年的發展，WDL 已經是生信行業廣泛接受的一種工作流标準，具有下面的優勢：

Human-readable

WDL 作為一種為工作流領域定制的語言，和 Shell、Python 等通用的腳本語言相比，沒有過多複雜的概念，對使用者的計算機技能要求不高，對于生信使用者容易上手。
Portable Workflow

WDL 可以在多個平台執行，比如本地伺服器、SGE 叢集，雲計算平台等，可以做到一次編寫多處執行。
Standard

作為GA4GH支援的工作流描述語言之一，已經得到了衆多大廠和行業協會的支援，形成了比較完善的生态。

從 Hello world 開始編寫WDL

像我們學習其他語言一樣，先從經典的 hello world 開始，學習 WDL 的編寫

task echo {
  String out

  command {
    echo Hello World! > ${out}
  }

  runtime {
    cluster: "OnDemand ecs.sn1.medium img-ubuntu-vpc"
    docker: "registry.cn-shanghai.aliyuncs.com/mynamespace/myubuntu:0.1"
  }

  output {
    File outFile = "${out}"
  }
}

workflow wf_echo {
  call echo
  output {
    echo.outFile
  }
}

上面的例子是一個簡單的 WDL，作用是輸出

Hello world

并儲存在一個檔案裡面，輸出檔案名可以指定。一個完整的 WDL 一般由下面幾個部分組成：

workflow：工作流定義
task：工作流包含的任務定義
call：調用或觸發工作流裡面的 task 執行
command：task在計算節點上要執行的指令行
runtime：task在計算節點上的運作時參數，包括 CPU、記憶體、docker 鏡像等
output：task 或 workflow 的輸出定義

使用變量

我們要把一個處理步驟構造成一個 task, 就要封裝計算軟體的指令行，那麼指令行的參數如何傳入呢？輸出檔案的名字如何指定呢？這些問題在 WDL 中可以通過變量來解決。比如

Hello world

例子中的

String out

就是一個字元串類型的輸入，用于指定輸出檔案的名字。WDL 中的變量可以定義在 workflow 中，也可以定義在 task中。在command 和 output 中可以通過$和{}的方式來引用變量。

變量的類型主要有以下幾種：

String
Int
Float
File
Boolean
Array[T]
Map[K, V]
Pair[X, Y]
Object

關于每一種變量的使用，以及 WDL 的更多使用技巧，請參考

官方規範文檔

。

task 如何組裝成 workflow

一個 workflow 裡面包含多個 task，task 之前的串行或并行關系如何表達呢？主要有下面三種情況：

Linear Chaining

第一種是最常見的場景，簡單的線性串聯，多個 task 依次執行，前面步驟的輸出作為後面步驟的輸入，最後一個 task 的輸出作為整個 workflow 的輸出。

Multi-input / Multi-output

第二種是多輸入多輸出的場景，一個 task 可以定義多個輸入和輸出，比如上面的例子，task B 有兩個輸出，作為 taskC 的輸入。

Scatter-Gather Parallelism

第三種場景是用于 task 的并發執行。如果一個 task 有多個樣本需要并發處理，可以使用數組的方式将樣本傳入，然後使用 scatter 并發的處理每個樣本，每個執行的單元稱為一個 shard。所有的 shard 執行完成，則目前 task 執行完成，所有 shard 的輸出，又作為一個數組，可以傳遞到下一個 task 處理。

輸入參數如何傳入

workflow 的輸入，比如基因樣本的存儲位置、計算軟體的指令行參數、計算節點的資源配置等，可以通過 json 檔案的形式來指定。使用 wdltools 工具可以根據 WDL 檔案來生成輸入模闆：

模闆格式如下：

當然，如果工作流不是很複雜，也可以按照上面的格式手寫 input 檔案。下面是一個 GATK 工作流的 input 檔案的片段：

實際的例子

使用 GATK 建構的Jointcalling

workflow定義

task 定義：HaplotypeCallerERC

task定義 GenotypeGVCFs

工作流解析

整個 workflow 由2個 task 組成
Task1 通過 Scatter 并發處理多份樣本，得到一組 vcf 檔案
Task2 處理 Task1 輸出的一組 vcf 檔案，得到最終的workflow 輸出

一個稍微複雜的例子--使用 GATK 做外顯子分析

工作流定義

task定義：UnmappedBamToAlignedBam

整個 Workflow 由5個 task 組成
Task 之間通過 Linear Chaining 的方式組合
每個 Task 是子 Workflow，由多個 Task 組合而成。也就是說 WDL 支援嵌套，workflow 裡面的任務，既可以是一個 task，也可以是一個完整的 workflow，這個 workflow 被稱為sub workflow。更多關于嵌套的用法請參考

WDL 怎麼運作

執行引擎 Cromwell

Cromwell

是 Broad Institute 開發的工作流管理引擎。具有如下的優勢：

支援 WDL 和 CWL 兩種工作流描述語言
多平台支援，包括本地伺服器、SGE叢集、雲計算平台等
阿裡雲批量計算是官方支援的雲平台之一
豐富的中繼資料，展示工作流執行過程
支援多種進階特性，優化 workflow 的執行

使用 Cromwell 運作 WDL

使用 Cromwell 運作 WDL 有兩種模式

Run 模式

用來執行單個 WDL，适用于調試初期，快速執行一個WDL。
```
$ java -jar cromwell.jar run echo.wdl --inputs input.json           
```

Server 模式

用下面的指令啟動一個 HTTP server

$ java -Dconfig.file=application.conf -jar cromwell.jar server

再使用 RESTful API 送出工作流到 server 執行：

$ java -jar cromwell.jar submit -t wdl -i input.json -o option.json -h http://localhost:8000

相比 Run 模式，Server 模式有以下優勢：

- 可以并行處理多個 workflow，适用于生産環境
- 有 Call caching 等進階特性（下文會講到），優化 workflow 的執行
- 提供豐富的 workflow metadata，來展示 workflow 的執行過程

注意：不管是使用Run 模式還是 Server模式，要使用批量計算作為後端運作 WDL，都需要對應的配置檔案支援，配置檔案詳解請參考批量計算官方文檔或 Cromwell 官方文檔

工具和支援

編輯工具及插件支援

上圖的三個主流編輯器或 IDE 都有 WDL 的官方插件，支援文法高亮。

文法檢查工具

WDL 編寫完成後，在真正執行之前，我們可以使用官方工具進行文法檢查：

$ java -jar wdltool.jar validate myWorkflow.wdl

Broad WDL 論壇

在使用 WDL 和 Cromwell 的過程中，如果遇到問題，可以到

Broad WDL 官方論壇

尋求幫助，常見的問題，在論壇都可以找到答案。

WDL 參考樣例

在學習編寫 WDL 的過程中，可以參考 Broad 官方的一些

GATK 工作流

，借鑒和學習 WDL 的用法。

WDL + Cromwell 在阿裡雲批量計算的最佳實踐

批量計算服務雲上基因計算

批量計算

是阿裡雲上的一種适用于大規模并行批處理作業的分布式雲服務。BatchCompute可支援海量作業并發規模，系統自動完成資源管理，作業排程和資料加載，并按實際使用量計費，是一種很适合基因計算的雲計算平台，目前是 Cromwell 官方支援的雲計算平台後端之一。

Cromwell + 批量計算實作 WDL 流程

上圖是使用批量計算實作 WDL 流程的總架構圖：

使用者使用 WDL 構造工作流
使用指令行工具送出 WDL 到 Cromwell server
Cromwell server 解析 WDL 并将 task 轉化為批量計算的作業送出
批量計算作業送出會後根據作業數量動态的申請計算資源
作業開始運作後，會從 OSS 對象存儲讀取測試資料，計算完成後會将結果上傳到 OSS
針對基因資料分發中資料拷貝的痛點，推出了對應的分發解決方案：CCP（内容協作平台），生信分析公司通過CCP實作對象存儲的目錄-Drive的映射，實作租戶級分目錄管理，管理不同的測序公司通路權限，生物樣本傳遞給第三方測序公司測序，測序公司直接上傳資料到網盤，實作雲上傳遞

Cromwell On 批量計算

批量計算作為官方支援的雲計算後端，在存儲、計算等方面做了大量的适配和優化。

支援的進階特性

從官方

版本45

開始，Cromwell 使用批量計算作為後端，支援 glob 和 Call caching 兩個進階特性。

glob

glob 是指對 workflow 或 task 的輸出，支援通配符比對。

output {
  Array[File] output_bams = glob("*.bam")
}

使用場景

輸出檔案有多個，且檔案名不确定
使用方法

采用 glob 表達式，用 array 方式存儲多個輸出檔案
價值

輸出結果支援通配符比對，簡化 WDL 編寫，采用數組方式，友善并發處理

Call caching

Call caching 是 Cromwell 的一個很有用的進階特性，通過 task 的複用，幫助客戶節省時間，節省成本。

适用場景

輸入和運作環境不變的情況下，複用之前 task 的運作結果
命中條件

輸入 + 運作時參數相同
複用之前的執行結果，節省時間，節省成本

例如上圖的 workflow，一共有4個 task，當執行到第三個 task 時，由于參數錯誤失敗了。當我們排除了錯誤之後，再次送出 workflow，Crowell 會檢測到前兩個 task 已經執行過，則直接複用其結果，從 task3 開始繼續執行，進而達到節省時間，節省成本的目的。

關于 Call caching 的配置和使用，請參考

批量計算 runtime

使用批量計算作為後端時，主要的 runtime 參數有：

cluster
- 計算叢集環境
- 支援serverless 模式和固定叢集模式
mounts
- 挂載設定
- 支援 OSS 和 NAS
docker
- 容器鏡像位址
- 支援容器鏡像服務
systemDisk
- 系統盤設定
- 包括磁盤類型和磁盤大小
dataDisk
- 資料盤設定
- 包括磁盤類型、磁盤大小和挂載點
timeout
- 作業逾時時間

具體的參數解釋及填寫方法，請參考

啟動 Cromwell server

為了友善使用者部署 Cromwell server，我們推出了免費的 Cromwell server ECS 鏡像，内置 Cromwell 運作需要的 java 環境、docker 工具、mysql 鏡像及配置檔案模闆等，使用一鍵啟動工具，就可以啟停 Cromwell server:

$ cd /home/cromwell/docker-compose-mysql/

#初次部署，使用init來初始化配置并啟動服務
$ ./server.sh init --id=xxxx --key=xxxx --root=oss://my-bucket/cromwell_dir --instance=ecs.sn1.medium --image=img-ubuntu-vpc

#停止服務
$ ./server.sh stop

#再次啟動服務
$ ./server.sh start

服務啟動後，可以使用鏡像内置的指令行工具 widdler 來送出和檢視 workflow。widdler指令行內建了Crowmell server 和批量計算服務，可以提供如下功能：

支援工作流的送出、查詢等操作
支援工作流對應的批量計算日志的查詢
支援失敗工作流快速定位原因
支援workflow 級别的 metric 統計
支援workflow 級别的 billing 統計

标準流程描述語言 WDL 阿裡雲最佳實踐我們為什麼需要标準的工作流描述語言WDLWDL + Cromwell 在阿裡雲批量計算的最佳實踐