CWL (通用工作流程語言)

CWL (通用工作流程語言) === ###### tags: `生物資訊` ###### tags: `生物資訊`, `CWL`, `通用工作流程語言`, `WDL` [TOC] ## CWL 摘要 - ### 全名 - Common Workflow Language, 通用工作流程語言 - ### 功用 - 用來串接多個 task，組成一個工作流程(workflow)，如同 Linux script - ### 開發 CWL 的目的 [[註]](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) - ### 性質 - 它是一種語法規範，不是軟體或套件 - 如同 javascript 語言, 能執行 js 的引擎有 - [V8 (for Chrome)](https://zh.wikipedia.org/zh-tw/V8_(JavaScript%E5%BC%95%E6%93%8E)) - [SpiderMonkey (for Firefox)](https://zh.wikipedia.org/wiki/SpiderMonkey) - [Chakra (for Microsoft Edge)](https://zh.wikipedia.org/wiki/Chakra_(JavaScript%E5%BC%95%E6%93%8E)) - [等等](https://zh.wikipedia.org/wiki/JavaScript%E5%BC%95%E6%93%8E) - ### 執行 CWL 的引擎 - **cwl-runner** (使用 python 語言開發) - [GitHub](https://github.com/common-workflow-language/cwltool) - **Cromwell** (使用 java 語言開發) - [GitHub](https://github.com/broadinstitute/cromwell) | [使用者指南](https://cromwell.readthedocs.io/en/stable/LanguageSupport/) | [快速上手](https://cromwell.readthedocs.io/en/stable/tutorials/FiveMinuteIntro/) - **arvados-cwl-runner** - [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 一個開放源碼平台，用於管理、處理和共享基因體以及其他大型科學和生物醫學資料 - **toil** - [官網](https://toil.readthedocs.io/en/releases-3.6.x/running/running.html) - 由 UCSC 計算基因體學實驗室開發 - 是一個開源工作流程引擎，主要用於大規模生物醫學計算 - 等等 - ### 其他相關工具 - [cwlavro](https://github.com/common-workflow-language/cwlavro) > 將 CWL 定義的工作流程檔案，轉譯成 avro (可視為中間檔)，再生成 java 版本 > (感覺應該是 java-runner ?) - ### Q & A - **為何不使用 Linux script，而要選擇 CWL? 有以下考量：** 1. 能在不同的平台上執行，而 script 語法可能有平台相依性 2. 需要串接的不同程式，如 python, perl, java, C/C++ 等 3. 若能將不同程式用 CWL 包裝起來，如同一個黑箱子 - 使用者就不用考慮到 **「要如何執行該程式」** - 不用考慮 **「程式的輸入/輸出參數之用法、編排與傳遞」** - 只要提供 **「程式所需的輸入/輸出資料」** - **在基因體方面的應用** - 預期只要編寫一次 CWL，就能在不同的雲端平台 (如 AWS / Azure / GCP) 執行基因檢測的二級分析 - 因此，就可以達到 write once, compute anywhere - ### CWL 和 WES 的關係 - [生物資訊 / WES (工作流程執行服務)](/0o1sLP_KR4KVQdTT1npy1w) --- **CWL 操作細節：** [TOC] ## 重要連接 - **Github** - https://github.com/common-workflow-language - [cwl-runner](https://github.com/common-workflow-language/cwltool) - www.commonwl.org - **使用者指南** - https://www.commonwl.org/user_guide/index.html - **類別與屬性文件(v1.0)** - https://www.commonwl.org/v1.0/CommandLineTool.html ## 使用者指南 ### 0. 網址 - http://www.commonwl.org/user_guide/index.html ### 1. [簡介](http://www.commonwl.org/user_guide/01-introduction/index.html) - 內文 - CWL 起源於 make 和其他許多類似工具 - 這些工具根據任務之間的相依關係，決定執行順序 - 但 CWL 還必須明確定義「輸入」與「輸出」 - 重點 - CWL 是將命令列工具串在一起的一種描述方式 - CWL 並不是軟體套件，而是一種規範 - CWL 具有在不同的平台間的移植性 ### 2. [First Example](https://www.commonwl.org/user_guide/02-1st-example/index.html) - 預備環境 - [安裝cwl-runner](https://github.com/common-workflow-language/cwltool#install) ```bash # 使用 virtualenv 安裝虛擬環境 virtualenv -p python3 venv # Create a virtual environment source venv/bin/activate # Activate environment before installing `cwltool` # 安裝 cwl 工具 pip install cwlref-runner # 印出工具版本 cwl-runner --version cwltool --version ``` - [指令用法](https://github.com/common-workflow-language/cwltool#usage) - 預設 INFO 模式 ```cwl-runner [tool-or-workflow-description] [input-job-settings]``` - 啟用 DEBUG 模式 ```cwl-runner --debug [tool-or-workflow-description] [input-job-settings]``` - ==**簡易範例程式**== - test.cwl ```yaml cwlVersion: v1.0 class: CommandLineTool baseCommand: date inputs: [] outputs: [] ``` - 執行 1st-tool.cwl ```bash $ cwl-runner test.cwl INFO /home/tj/workspace/cwl/env-python3/bin/cwl-runner 3.0.20200324120055 INFO Resolved 'test.cwl' to 'file:///home/tj/workspace/cwl/test.cwl' INFO [job test.cwl] /tmp/jt1_76z4$ date Tue Apr 7 17:51:19 CST 2020 INFO [job test.cwl] completed success {} INFO Final process status is success ``` - 按照內文執行，其中 - cwlVersion(\*) - 表示此份文件使用的語法版本 - class - 表示此份文件的類型 - 類型為 command-line tool - baseCommand - 表示要執行的工具名稱或指令 ### 3. [Essential Input Parameters](http://www.commonwl.org/user_guide/03-input/index.html) - 關於 /tmp 目錄 > The CWL reference runner (cwltool) and other runners create temporary directories with symbolic (“soft”) links to your input files to ensure that the tools aren’t accidentally accessing files that were not explicitly specified > - 重點 - 如何傳遞參數到命令？ - 參數類型 - 為「原生類型(primitive types)」如 boolean, string, int，要如何配置？ - 為「物件類型(object types)」如 File，要如何配置？ - 參數配置 - 參數 inputBinding 配置是「選擇性的(optional)」 - 當參數為「選擇性(optional)」時在類型的後面加上「?」(如同 reg-exp)，即便變成可有可無 - 透過 ```prefix``` 和 ```separate``` 定義輸出格式 - ```-f``` - ```-i 123``` - ```-i123``` - ```--integer 123``` - ```--integer=123``` - 如何配置參數在命令中的位置順序？ ### 4. [Returning Output Files](http://www.commonwl.org/user_guide/04-output/index.html) - 重點 - 如何定義命令程式的輸出規範 - 呼叫「解壓縮程式」來執行解壓縮，並回傳單一檔案 - 程式所產生的輸出檔案，若要回傳，必須明確定義輸出規範 - 此案例一次只能回傳單一檔案；若回傳多個檔案，會有錯誤 ``` ERROR [job 04-test.cwl] Job error: ("Error collecting output for parameter 'file_list':\n04-test.cwl:13:3: Multiple matches for output item that is a single file.", {}) ``` - 沙相運作方式 - 在沙箱中，執行 ```tar --extract --file 001.tar``` - log ``` INFO [job 04-test.cwl] /tmp/jxbmvzdr$ tar \ --extract \ --file \ /tmp/tmpjv4fllw4/stgab29b72c-d04e-4a6f-8099-cc9a2aa024fa/001.tar ``` - 看起來應該不是在 docker 上跑的在 /tmp 目錄，建立隨機名稱目錄，在裡面執行 cwl script 要參考的檔案，會在沙箱目錄中建立 synbolic link 連接到呼叫端 ### 5. [Capturing Standard Output](http://www.commonwl.org/user_guide/05-stdout/index.html) - 重點 - 如何從標準輸出擷取訊息 ### 6. [Parameter References](http://www.commonwl.org/user_guide/06-params/index.html) - 重點 - 在 cwl 描述檔裡，使用變數來參考其他欄位 - 例如 - ```$(inputs.extractfile)``` - ```$(inputs["extractfile"])``` - ```$(inputs['extractfile']) ``` ### 7. [Running Tools Inside Docker](http://www.commonwl.org/user_guide/07-containers/index.html) - #### 錯誤訊息1： - Docker is not available - docker executable is not available ```bash ERROR Workflow error, try again with --debug for more information: Docker is not available for this tool, try --no-container to disable Docker, or install a user space Docker replacement like uDocker with --user-space-docker-cmd.: docker executable is not available $ docker Command 'docker' not found, but can be installed with: sudo snap install docker # version 18.09.9, or sudo apt install docker.io See 'snap info docker' for additional versions. ``` - 安裝 docker ```bash $ sudo apt install docker.io ``` - #### 錯誤訊息2 - Docker is not available - returned non-zero exit status 1. ``` ERROR Workflow error, try again with --debug for more information: Docker is not available for this tool, try --no-container to disable Docker, or install a user space Docker replacement like uDocker with --user-space-docker-cmd.: Command '['docker', 'images', '--no-trunc', '--all']' returned non-zero exit status 1. ``` - 進一步檢測，是否為 docker permission 問題 ```bash # 方法一 # 尋找 cwl-runner 所 $ whereis cwl-runner在位置 # 授權 sudo 給 docker $ sudo env-python3/bin/cwl-runner docker.cwl docker-job.yml INFO env-python3/bin/cwl-runner 3.0.20200324120055 INFO Resolved 'docker.cwl' to 'file:///home/tj/workspace/cwl/docker.cwl' INFO ['docker', 'pull', 'node:slim'] slim: Pulling from library/node 5e35bd43cf78: Pull complete cda0aae130a5: Pull complete 07ee8c9897cf: Pull complete 5dec90c14aef: Pull complete 3ab2e4288749: Pull complete Digest: sha256:f16cebf688d3c2c4cc35d2a8cf7523b5a9fdcf56e776d9e9e622a79566da84ad Status: Downloaded newer image for node:slim ... ... INFO Final process status is success # 表示執行成功 ``` ``` # 方法二 $ docker run hello-world 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.40/containers/create: dial unix /var/run/docker.sock: connect: permission denied. See 'docker run --help'. ``` - 將 ``` docker:x:127:tj docker:x:127:tj ``` - [如何挑選node docker鏡像](https://kknews.cc/code/2ym8n4r.html) ## CWL 視覺化工具 - [Rabix Composer](https://github.com/rabix/composer) - 注意事項 - ```9.4.3``` 版本不存在 ```json "@types/node": { "version": "9.4.6", "resolved": "https://registry.npmjs.org/@types/node/-/node-9.4.6.tgz", "integrity": "sha512-CTUtLb6WqCCgp6P59QintjHWqzf4VL1uPA27bipLAPxFqrtK1gEYllePzTICGqQ8rYsCbpnsNypXjjDzGAAjEQ==", "dev": true }, ``` - 需要將 ```node-9.4.3.tgz``` 換成 ```node-9.4.6.tgz``` - integrity 欄位的 hashcode 也要更新 - 參考資料 - [Missing .tgz files for @types/node 9.4.2 and 9.4.3 #347](https://github.com/npm/registry-issue-archive/issues/347) - [Docker fails to build due to Not Found “@types/node@9.4.2”](https://medium.com/@martinratinaud/docker-fails-to-build-due-to-not-found-types-node-9-4-2-918d60c2f79e) - [node-9.4.1.tgz 版本](https://github.com/sandeepnamburi/PickYourProf/blob/master/package-lock.json) ## WES API ### GA4GH - [2018-GA4GH WES API enables portable genomic analysis](https://www.ga4gh.org/news/ga4gh-wes-api-enables-portable-genomic-analysis/) - [[Video] GA4GH Connect: Workflow Execution Service (WES) & Interoperability Testbed](https://youtu.be/w3xWPEMm8S4) ## 關於 WES (tmp) - [Workflow Execution Service (WES) API](http://ga4gh.github.io/workflow-execution-service-schemas/)  ## CWL 跟 WDL 的關係 - [「生資無價系列專題」- 如何寫出專業的生物資訊分析流程](https://chungtsai.medium.com/468875223273) - CWL: 比較像 YAML 這樣層級的語法，參與者有 Broad Institute - WDL: 後來由 Broad Institute 推出，比較像程式語言，有支援 function call

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.