WES (工作流程執行服務)

WES (工作流程執行服務) === ###### tags: `生物資訊` ###### tags: `生物資訊`, `WES`, `工作流程執行服務`, `CWL`, `Common Workflow Language`, `WDL`, `Nextflow`, `pipeline`, `container` [TOC] ## WES 摘要 - ### 全名 - Workflow Execution Service, 工作流程執行服務 - ### 功用 - 用來執行 CWL / WDL 工作流程語言的引擎(engine) - [點此了解 CWL (通用工作流程語言)](/R14doPGmQJmAQqCIoAZtCw#CWL-摘要) - ### 開發 WES 的目的 [[註]](https://developer.ibm.com/storage/2017/05/04/cwl-workflow-lsf-toil/) - #### 為何開發？遭遇的痛點是？ - 使用工作流程(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 - ### 常見 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) ## 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 來執行 --- ## 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/) :::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) 2. 建立一個目錄，並執行 jar 做測試 ```$ java -jar cromwell-49.jar``` [![](https://i.imgur.com/ad5qenu.png)](https://i.imgur.com/ad5qenu.png) 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``` - **[透過 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 檔 - 單獨執行 ```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``` (尚未測試) - 正確解法，可參考底下兩篇文章 - [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 - 皆有此訊息 ## 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) ## 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) ## 關於 GA4GH 的細節 - ### 官網 - https://www.ga4gh.org/ - ### [成立初衷](https://kknews.cc/zh-tw/finance/5ave8el.html) > 發掘基因醫藥的潛能，提高人類健康水平。該機構由30個國家的逾285個領先機構組成，當中包括全球領先的醫療保健供應商、研究贊助人、研究機構、醫藥公司、醫病宣傳機構、生命科學及資訊科技公司。GA4GH成員共同努力建構統一的共同框架，推動負責任、自願(?)及安全的基因體與臨床數據分享。 - ### 五年戰略規劃 - [共建基因組學數據共享標準](https://read01.com/zh-tw/RnKnENg.html#.XplansYzbCI)