---
# System prepended metadata

title: WES (工作流程執行服務)
tags: [WES, container, WDL, Nextflow, CWL, Common Workflow Language, 工作流程執行服務, pipeline, 生物資訊]

---

WES (工作流程執行服務)
===
###### tags: `生物資訊`
###### tags: `生物資訊`, `WES`, `工作流程執行服務`, `CWL`, `Common Workflow Language`, `WDL`, `Nextflow`, `pipeline`, `container`

<br>

[TOC]

<br>

## WES 摘要
- ### 全名
    - Workflow Execution Service, 工作流程執行服務
- ### 功用
    - 用來執行 CWL / WDL 工作流程語言的引擎(engine)
    - [點此了解 CWL (通用工作流程語言)](/R14doPGmQJmAQqCIoAZtCw#CWL-摘要)
- ### 開發 WES 的目的 <sup><sup>[[註]](https://developer.ibm.com/storage/2017/05/04/cwl-workflow-lsf-toil/)</sup></sup>
    - #### 為何開發？遭遇的痛點是？
        - 使用工作流程(workflow)的例子
            如 Taverna，Galaxy，Bpipe 和 Snakemake
        - 在一個系統中定義的工作流程，並無法在另一個系統中執行
        - 這已經成為生命科學界內，生物資訊學家合作的一個大障礙
    - #### 改善之道
        1. 簡化 pipeline 的開發
        2. 促進工作流程的**模組化**，以及模組的**再利用**
        3. 能整合不同的 HPC 環境 
            > HPC: High Performance Computing, 高效能運算
            藉此達到 ==write once, compute anywhere==
    - #### 小結
        - 使工作流程變成可攜、可擴充
        - 能橫跨不同的軟體與硬體環境 (工作站、叢集、雲端、HPC)
- ### WES API 發布聲明
    - v1.0
        - [GA4GH WES API enables portable genomic analysis
    ](https://www.ga4gh.org/news/ga4gh-wes-api-enables-portable-genomic-analysis/) (2018/10/26)
- ### WES API 的 Spec 制定
    - 由 GA4GH 制定存取 WES 接口 ([WES API](       https://github.com/ga4gh/workflow-execution-service-schemas))
        - [yaml 格式](https://github.com/ga4gh/workflow-execution-service-schemas/blob/master/openapi/workflow_execution_service.swagger.yaml)
    - [WES API 的制定目標](https://github.com/ga4gh/workflow-execution-service-schemas#what-is-wes)
        - 有能力請求執行 workflow，並要能支援 CWL/WDL 工作流程語言
        - 有能力使用 JSON 規範來表達 workflow 的請求
        - 有能力從執行中的 workflow 取得相關資訊
    - [WES API 的未來目標](https://github.com/ga4gh/workflow-execution-service-schemas#possible-future-enhancements)
        - 與 CWL 和 WDL 一起使用的通用 JSON 參數化格式
        - **驗證服務**：測試 WES 引擎是否符合規範
        - **診斷工具**：能對執行失敗的工作流程進行 debug
        - **掛勾機制**：能提供 callback 機制，來取得正在執行中的 workflow 之狀態變化
        - **數據整合**：能整合 GA4GH 資料庫
- ### WES engine 的實作
    - 決取於各家廠商的實作
        ![](https://i.imgur.com/VW1yU6L.png)
        ([資料來源1](https://docs.google.com/presentation/d/1sl9Rd141nJi9QCq-40RRo2F5yq84QN8iZj0SfE3fDQM/edit#slide=id.g3f851104e8_0_176), [資料來源2](https://www.ga4gh.org/news/ga4gh-wes-api-enables-portable-genomic-analysis/))
    - 目前知道的有：
        - **Cromwell** (使用 java 語言開發)
            - [GitHub](https://github.com/broadinstitute/cromwell) | [使用者指南](https://cromwell.readthedocs.io/en/stable/LanguageSupport/) | [快速上手](https://cromwell.readthedocs.io/en/stable/tutorials/FiveMinuteIntro/)
        - **Arvados**
            - [Github](https://github.com/arvados/arvados) | [使用者指南](https://doc.arvados.org/v2.0/user/cwl/cwl-run-options.html) | [官網](https://arvados.org/)
                - An open source platform for managing, processing, and sharing genomic and other large scientific and biomedical data
                    一個開放源碼平台，用於管理、處理和共享基因體以及其他大型科學和生物醫學資料
        - **Genomics Platform**
            - IAP: Illumina Analysis Platform
    <br>
- ### 常見 workflow 市集
    - [Dockstore](https://dockstore.org/)
        ![](https://i.imgur.com/brpQal8.png)
        - #### 介紹
            [![](https://i.imgur.com/9gGXdi6.png)](https://dockstore.org/)
            - Dockstore 是由 GA4GH 使用的開放平台
            - Dockstore 由[癌症基因體共同研究室(Cancer Genome Collaboratory)](https://cancercollaboratory.org/)開發
            - Dockstore 用於共享由「通用工作流程語言（CWL）」、「工作流程描述語言（WDL）」或「Nextflow」所描述的基於 Docker 工具
        - #### [統計資訊](https://dockstore.org/search?searchMode=files) (2020/04)
            - 專案類型
                ![](https://i.imgur.com/rAill8A.png)
            - 專案語言
                ![](https://i.imgur.com/V9qqxQX.png)
            - 專案來源
                ![](https://i.imgur.com/DKL3DOJ.png)

        - #### 工作流程範例
            - [pcawg-bwa-mem-workflow](https://dockstore.org/containers/quay.io/pancancer/pcawg-bwa-mem-workflow:2.7.0)
                - [CWL](https://dockstore.org/api/api/ga4gh/v2/tools/quay.io%2Fpancancer%2Fpcawg-bwa-mem-workflow/versions/2.7.0/plain-CWL/descriptor//Dockstore.cwl)
                - [Dockerfile](https://dockstore.org/containers/quay.io/pancancer/pcawg-bwa-mem-workflow:2.7.0?tab=files)
            - [gatk-haplotypecaller](https://dockstore.org/containers/registry.hub.docker.com/pfda2dockstore/gatk-haplotypecaller/gatk-haplotypecaller:11)
        - #### 工具範例
            - [fastqc](https://dockstore.org/containers/quay.io/wshands/fastqc:latest?tab=info)

<br>

## WES 架構流程圖
- user (or client) 

- <-> WES API 
    - GA4GH 制定的 RESTful API
    - 或是 server 本身提供的 API (如 Cromwell RESTful API)

- <-> WES Server  (Cromwell 同時支援 server & runner)
- <-> WES engine (或稱為 runner ?)
- <-> engine (或 runner) 執行指定的 workflow script 
    - script 語言可以是 CWL, WDL, Nextflow
- <-> script 可以執行單一個工具(tool), 或是多個工具(workflow)
    - 啟動 tool 的方式 有兩種：
        1. 直接在 OS 執行，像 shell script, python, perl, java, C/C++，等等
            - 啟動 python 的 cwl 範例
                test-python.cwl
                ```cwl
                cwlVersion: v1.0
                class: CommandLineTool
                baseCommand: [python, -c, 'print("Hello, world! ABCDEFGHIJKLMNOPQRSTUVWXYZ")']
                inputs: []
                outputs: []
                ```
        2. 透過 docker 來執行

<br>

---

<br>

## Cromwell 工具的測試
> 測試：CWL/WDL runner, WES API 
- ### AWS Cromwell Server
    - [Genomics Workflows on AWS](https://docs.opendata.aws/genomics-workflows/)
        - [Cromwell Examples](https://docs.opendata.aws/genomics-workflows/orchestration/cromwell/cromwell-examples/)
            - ==HaplotypeCaller example==
    - [Cromwell on AWS](https://aws.amazon.com/government-education/cromwell-on-aws/)
- ### Github (Cromwell 工具)
    - [GitHub](https://github.com/broadinstitute/cromwell) | [使用者指南](https://cromwell.readthedocs.io/en/stable/LanguageSupport/) | [快速上手](https://cromwell.readthedocs.io/en/stable/tutorials/FiveMinuteIntro/)
    - [用法](https://cromwell.readthedocs.io/en/stable/CommandLine/)
        - local mode
            ```java -jar cromwell-49.jar run  hello_world.cwl```
        - web mode
            ```java -jar cromwell-49.jar server```
            - [Cromwell Server REST API](https://cromwell.readthedocs.io/en/stable/api/RESTAPI/)
            <br>
        :::info
        :information_source: Cromwell 能解析 CWL 和 WDL 兩種資料流程語言
        :::
    - #### [新手上路](https://cromwell.readthedocs.io/en/stable/tutorials/FiveMinuteIntro/)
        1. 下載 Cromwell 的 java 套件
            https://github.com/broadinstitute/cromwell/releases/latest
            ![](https://i.imgur.com/Rlbxixu.png)
            <br>
        2. 建立一個目錄，並執行 jar 做測試
            ```$ java -jar cromwell-49.jar```
            [![](https://i.imgur.com/ad5qenu.png)](https://i.imgur.com/ad5qenu.png)
            <br>
        3. 執行 hello world (for WDL)
            - 檔案名稱：==myWorkflow.wdl==
                ```wdl
                workflow myWorkflow {
                    call myTask
                }

                task myTask {
                    command {
                        echo "hello world"
                    }
                    output {
                        String out = read_string(stdout())
                    }
                }
                ```
            - **直接執行 WDL**
                ```$ java -jar cromwell-49.jar run myWorkflow.wdl```
                打開 stdout 檔，會看到 ```hello world```
                <br>
            - **[透過 server 請求執行 WDL](https://cromwell.readthedocs.io/en/stable/CommandLine/)**
                - 先啟動 server
                    ```$ java -jar cromwell-49.jar server```
                - 再透過 WES API 來請求
                    ```bash
                    $ curl -X POST \
                    "http://localhost:8000/api/workflows/v1" \
                    -H "accept: application/json" \
                    -F "workflowSource=@/home/tj/Asus/workplace/cromwell/myWorkflow.wdl"
                    
                    ```
                :::info
                :information_source: **關於 execution 資料夾下，所產生的檔案**
                - **script.submit**
                    用來啟動 workflow 的 script，目前看到的有：
                    - 透過 bash 直接啟動
                    - 透過 docker 來執行
                - **script**
                    workflow 內容 (由 myWorkflow.wdl 轉譯成)
                :::
        4. 透過 Ubuntu dokcer 來執行 hello world (for WDL)
            - 檔案名稱：==simple-hello.wdl== (來源：[AWS](https://docs.opendata.aws/genomics-workflows/orchestration/cromwell/cromwell-examples/))
                ```wdl
                task echoHello{
                    command {
                        echo "Hello AWS!"
                    }
                    runtime {
                        docker: "ubuntu:latest"
                    }

                }

                workflow printHelloAndGoodbye {
                    call echoHello
                }
                ```
            - 方法同上，但會發現 Failed 訊息
                ```
                ...
                [2020-04-17 18:43:33,82] [info] WorkflowManagerActor Workflow d6c420b0-980e-4f5d-a3b7-570581222aab failed (during ExecutingWorkflowState): Job printHelloAndGoodbye.echoHello:NA:1 exited with return code -1 which has not been declared as a valid return code. See 'continueOnReturnCode' runtime attribute for more details.
                Check the content of stderr for potential additional information: /home/tj/Asus/workplace/cromwell/cromwell-executions/printHelloAndGoodbye/d6c420b0-980e-4f5d-a3b7-570581222aab/call-echoHello/execution/stderr.
                ...
                [2020-04-17 18:43:39,11] [info] SingleWorkflowRunnerActor workflow finished with status 'Failed'.
                ...
                Workflow d6c420b0-980e-4f5d-a3b7-570581222aab transitioned to state Failed
                ```
                ![](https://i.imgur.com/3Qk6QC4.png)
                - 亦無 stderr 檔
                <br>
            - 單獨執行 ```docker run ...```，會出現 permission denied
                > docker: Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Post http://%2Fvar%2Frun%2Fdocker.sock/v1.39/containers/create: dial unix /var/run/docker.sock: connect: permission denied.
            - 變成要有 sudo 才能執行成功
                ```sudo java -jar cromwell-49.jar run simple-hello.wdl```
                ```sudo java -jar cromwell-49.jar server``` (尚未測試)
                <br>
            - 正確解法，可參考底下兩篇文章
                - [How can I use docker without sudo?](https://askubuntu.com/questions/477551/how-can-i-use-docker-without-sudo/477554#477554)
                - [[解決方法] docker: permission denied](http://andy51002000.blogspot.com/2019/02/docker-permission-denied.html)
                - 實際測試，底下三種方法皆可
                    ```bash
                    $ sudo gpasswd -a $USER docker
                    $ sudo usrmod -a -G docker $USER
                    
                    # 添加 user 到 docker
                    # 變更前：docker:x:129:
                    # 變更後：docker:x:129:tj
                    $ sudo gedit /etc/group
                    ```
            - 若執行成功，會出現底下訊息
                ```
                ... is in a terminal state: WorkflowSucceededState
                ```
                - 不管是直接執行 WDL
                - 還是透過 server 請求執行 WDL
                - 皆有此訊息

<br>

## Cromwell API 的簡易測試
### Spec.
- 上面提到的 [Cromwell Server REST API](https://cromwell.readthedocs.io/en/stable/api/RESTAPI/)

### base URL
- WES API 是使用 /ga4gh/wes/v1
- Cromwell 則是 /api/workflows/v1

### Submit a workflow for execution
- 測試指令
    ```bash
    $ curl -X POST \
    "http://localhost:8000/api/workflows/v1" \
    -F "workflowSource=@/home/tj/Asus/workplace/cromwell/myWorkflow.wdl"
    ```
- 執行結果
    ```
    {"id":"b5c60c00-ecef-449a-9d9a-e5b079e23070","status":"Submitted"}
    ```
### Get workflows matching some criteria
- 測試指令
    ```bash
    $ curl -X GET \
    "http://localhost:8000/api/workflows/v1/query?id=b5c60c00-ecef-449a-9d9a-e5b079e23070"
    ```
- 執行結果
    ```
    {"results":[{"end":"2020-04-21T03:17:46.667Z","id":"b5c60c00-ecef-449a-9d9a-e5b079e23070","metadataArchiveStatus":"Unarchived","name":"myWorkflow","start":"2020-04-21T03:17:37.396Z","status":"Succeeded","submission":"2020-04-21T03:17:20.322Z"}],"totalResultsCount":1}
    ```
    ![](https://i.imgur.com/wZhMcVQ.png)

<br>
<br>

## WES API 的簡易測試
### Spec.
- 上面提到的 [yaml 格式](https://github.com/ga4gh/workflow-execution-service-schemas/blob/master/openapi/workflow_execution_service.swagger.yaml)

### base URL
- WES API 是使用 /ga4gh/wes/v1
- Cromwell 則是 /api/workflows/v1

### service-info: 取得關於工作流程執行服務的資訊
- 測試指令
    ```bash
    $ curl -X GET "http://localhost:8000/ga4gh/wes/v1/service-info"
    ```
- 執行結果
    ```
    {"auth_instructions_url":"https://cromwell.readthedocs.io/en/stable/","contact_info_url":"https://cromwell.readthedocs.io/en/stable/","default_workflow_engine_parameters":[],"supported_filesystem_protocols":["gcs","drs","http","s3","ftp","oss"],"supported_wes_versions":["1.0"],"system_state_counts":{},"tags":{},"workflow_engine_versions":{"Cromwell":"49"},"workflow_type_version":{"CWL":["v1.0"],"WDL":["draft-2","1.0","biscayne"]}}
    ```
    ![](https://i.imgur.com/7GvOoRr.png)




<br>

## 關於 GA4GH 的細節
- ### 官網
    - https://www.ga4gh.org/
- ### [成立初衷](https://kknews.cc/zh-tw/finance/5ave8el.html)
    > 發掘基因醫藥的潛能，提高人類健康水平。該機構由30個國家的逾285個領先機構組成，當中包括全球領先的醫療保健供應商、研究贊助人、研究機構、醫藥公司、醫病宣傳機構、生命科學及資訊科技公司。GA4GH成員共同努力建構統一的共同框架，推動負責任、自願(?)及安全的基因體與臨床數據分享。
- ### 五年戰略規劃
    - [共建基因組學數據共享標準](https://read01.com/zh-tw/RnKnENg.html#.XplansYzbCI)


<!--
    - 執行單位
        - [Veritas Genetics](https://www.veritasgenetics.com/)：公司，從事全基因體定序
        - [the Human Cell Atlas](https://www.humancellatlas.org/)：組織機構，建置所有人體細胞的全面參考圖
        - [the Broad Institute of MIT and Harvard](https://www.broadinstitute.org/)：麻省理工暨哈佛研究所，生物醫學和基因體研究中心，非營利組織
        - [Illumina](https://www.illumina.com/)：生物科技中心
        
-->