|
|
@@ -0,0 +1,321 @@ |
|
|
|
--- |
|
|
|
id: quick-intro |
|
|
|
title: 快速指南:Choppy for Reproducible Omics Pipeline |
|
|
|
sidebar_label: 快速指南 |
|
|
|
--- |
|
|
|
{% raw %} |
|
|
|
> Author: Yechao Huang |
|
|
|
> |
|
|
|
> Email: 17210700095@fudan.edu.cn |
|
|
|
> |
|
|
|
> Date: 2019-01-18 |
|
|
|
|
|
|
|
# Choppy快速指南 |
|
|
|
|
|
|
|
## Pipeline 分析三步走 |
|
|
|
|
|
|
|
基于`Choppy平台`进行 Pipeline 分析十分简单高效,只需要三步即可轻松搞定(**点击进入[演示视频](http://kancloud.nordata.cn/2019-01-20-choppy.mp4)**): |
|
|
|
|
|
|
|
1. 登陆**[Choppy App Store](http://choppy.3steps.cn)**,挑选符合自己需求的 App,并安装 |
|
|
|
2. 准备 App 所需的 Samples 文件 |
|
|
|
3. 提交任务 |
|
|
|
|
|
|
|
## 使用 APP 提交任务 |
|
|
|
|
|
|
|
> 基于 choppy 封装的 app 可以使得用户可以通过自定义或者下载的 `app` 简单快速的进行可重复并且可溯源的任务提交 |
|
|
|
|
|
|
|
- 选择所要使用的 **app** 并生成相应的 **samples.csv** 文件(以 dna-germline-0.1.0 为例) |
|
|
|
|
|
|
|
```bash |
|
|
|
choppy samples dna-germline-0.1.0 --output dna-germline.csv |
|
|
|
``` |
|
|
|
|
|
|
|
通过上述命令会生成一个对应于使用的 app 的一个 .csv 格式文件,按照表头的内容将所涉及到的变量(如:fastq 文件在 OSS 上的路径、对应的 sample 的名字、sample_id 等)填入到文件中(注意以 “,” 进行分隔),在填写的过程中可以直接在 linux 系统下进行操作也可以下载到本地 PC 上使用 excel 进行操作。 |
|
|
|
|
|
|
|
> sample_id : 对于每一个提交的样本名会根据 sample_id 来创建一个目录,里面包含了当前样本所运行时使用的 wdl 文件以及 input 文件,以便于对样本任务的溯源工夫 |
|
|
|
|
|
|
|
- 根据生成的 samples.csv 文件批量提交任务 |
|
|
|
|
|
|
|
```bash |
|
|
|
choppy batch dna-germline-0.1.0 samples.csv --project-name project |
|
|
|
``` |
|
|
|
|
|
|
|
当出现如下所示的信息时,表明当前任务提交成功: |
|
|
|
|
|
|
|
```bash |
|
|
|
Sample ID: 1, Workflow ID: a6a24b7d-bea3-48fe-93f6-7b7aa8ce9b5f |
|
|
|
Successed: 1, /home/huangyechao/project/submitted.csv |
|
|
|
``` |
|
|
|
|
|
|
|
其中,第一行为所提交的样本的名字以及每一个样本对应的 workflow ID ,可用于查询该任务的运行状态;当有多个样本时,会有多行出现。 |
|
|
|
第二行为统计 app 端成功的样本数,并且会生成包含有当次任务成功提交时的所有信息 |
|
|
|
第三行为为统计 app 端失败的样本数(若没有失败则不会产生) |
|
|
|
|
|
|
|
- 根据生成的 Workflow ID 可以进行任务状态的查询,使用命令如下 |
|
|
|
|
|
|
|
```bash |
|
|
|
choppy query -s a6a24b7d-bea3-48fe-93f6-7b7aa8ce9b5f |
|
|
|
``` |
|
|
|
|
|
|
|
此时会显示出该样本任务的状态信息,当显示为 submitted 时,表示任务正在向云端及进行投递过程中; 显示为 Running 时,表示任务已经成功在云端运行;当显示为 Failed 时,表示任务运行失败。 |
|
|
|
使用 **-m** 参数可以查看更多关于任务的日志信息: |
|
|
|
|
|
|
|
```bash |
|
|
|
choppy query -s -m a6a24b7d-bea3-48fe-93f6-7b7aa8ce9b5f |
|
|
|
``` |
|
|
|
|
|
|
|
- 当任务提交成功之后,可登陆到阿里云控制台中,在批量计算的作业列表中查询任务的运行情况;通常当任务提交到阿里云计算平台时,会需要几分钟的服务器配置时间之后任务才会开始进行计算。 |
|
|
|
|
|
|
|
## 构建属于自己 WDL |
|
|
|
|
|
|
|
在构建 **WDL** 之前,需要先对 **WDL** 的基本结果有一定的了解,其基本结构包含以下部分:`workflow`,`task`,`call`, `command`以及`output`(详见[WDL Base Structure](https://software.broadinstitute.org/wdl/documentation/structure)) |
|
|
|
|
|
|
|
以下是对构建 **WDL** 脚本的一个简单教程(以 [Sentieon](http://goldenhelix.com/products/sentieon/index.html) 的 DNA-seq 为例): |
|
|
|
|
|
|
|
## 单个 task 的构建 |
|
|
|
|
|
|
|
- **command**: 通常我们在构建**pipeline** 时,是将每一步分析写入到一个脚本中,并调用脚本的方式串行使用,如下所示: |
|
|
|
|
|
|
|
```bash |
|
|
|
$SENTIEON_INSTALL_DIR/bin/bwa mem -M -R "@RG\tID:$group\tSM:$sample\tPL:$pl" -t $nt $fasta $fastq_1 $fastq_2 | $SENTIEON_INSTALL_DIR/bin/sentieon util sort -o ${sam}.sorted.bam -t $nt --sam2bam -i - |
|
|
|
``` |
|
|
|
|
|
|
|
以上为 **DNA-seq** 中比对的命令,在 **WDL** 中这部分将会书写在 `command` 部分,如下所示: |
|
|
|
|
|
|
|
``` |
|
|
|
command <<< |
|
|
|
set -o pipefail |
|
|
|
set -e |
|
|
|
export SENTIEON_LICENSE=此处替换为你的license |
|
|
|
nt=$(nproc) |
|
|
|
${SENTIEON_INSTALL_DIR}/bin/bwa mem -M -R "@RG\tID:${group}\tSM:${sample}\tPL:${pl}" -t $nt ${ref_dir}/${fasta} ${fastq_1} ${fastq_2} | ${SENTIEON_INSTALL_DIR}/bin/sentieon util sort -o ${sample}.sorted.bam -t $nt --sam2bam -i - |
|
|
|
>>> |
|
|
|
``` |
|
|
|
|
|
|
|
可以看到在 **WDL** 中,就是将日常所使用的命令填入在 `command` 中,并用`{ }`或者`<<< >>>`进行引用(后者主要是在于有多个命令运行时使用)。 |
|
|
|
|
|
|
|
> 注意: `${变量}`的形式是 **WDL** 所识别的变量,当命令中的变量是`$变量`的形式时,**WDL**是无法识别的,如例子中的 `$nt` 在之前已经对其进行了定义; |
|
|
|
|
|
|
|
- **output**: `command` 部分完成之后,需要对于该命令的输出进行定义,比对的结果产生的文件为`${sample}.sorted.bam` 以及 `${sample}.sorted.bam.bai` ,因此需要在 `output` 中对结果的输出进行定义: |
|
|
|
|
|
|
|
```bash |
|
|
|
output { |
|
|
|
File sorted_bam = "${sample}.sorted.bam" |
|
|
|
File sorted_bam_index = "${sample}.sorted.bam.bai" |
|
|
|
} |
|
|
|
``` |
|
|
|
|
|
|
|
左边为当前 `task` 输出结果的命名,右边为所输出结果文件名,用 `" "` 进行引用; |
|
|
|
|
|
|
|
当有多个结果文件输出时,只有在 `output` 中进行了定义的结果文件才会输出,没有定义的将不会输出到结果目录中; |
|
|
|
|
|
|
|
- **runtime**: 对于每一个 `task` 的运行环境需要进行定义,包括所使用的软件的 `docker`信息,所使用的服务器配置信息,以及服务器的系统盘以及数据盘大小: |
|
|
|
|
|
|
|
```bash |
|
|
|
runtime { |
|
|
|
dockerTag:docker |
|
|
|
cluster: cluster_config |
|
|
|
systemDisk: "cloud_ssd 40" |
|
|
|
dataDisk: "cloud_ssd " + disk_size + " /cromwell_root/" |
|
|
|
} |
|
|
|
``` |
|
|
|
|
|
|
|
`dockerTag` 为所使用的 `docker` 信息,此处以变量表示 |
|
|
|
|
|
|
|
`cluster` 为运行命令是所选用的服务器实例信息([参照阿里云服务器 ECS](https://help.aliyun.com/document_detail/25378.html?spm=a2c4g.11186623.6.545.8e452f98mSzIST)) |
|
|
|
|
|
|
|
`systemDisk` 为使用的系统盘的大小,默认为 cloud_ssd 40G |
|
|
|
|
|
|
|
`dataDisk` 为使用的数据盘的大小信息,默认类型为 `cloud_ssd` ,挂载点为 `/cromwell_root/` |
|
|
|
|
|
|
|
> 注意:在系统盘和数据盘的写法上,需注意不同的变量之间存在空格 |
|
|
|
|
|
|
|
- 在将 `command` 主体部分改写完成之后,需要在 `task` 中声明 `command` 中所使用的变量形式: |
|
|
|
|
|
|
|
```bash |
|
|
|
task mapping { |
|
|
|
File fastq_1 |
|
|
|
File fastq_2 |
|
|
|
File ref_dir |
|
|
|
String fasta |
|
|
|
String SENTIEON_INSTALL_DIR |
|
|
|
String group |
|
|
|
String sample |
|
|
|
String pl |
|
|
|
String docker |
|
|
|
String cluster_config |
|
|
|
String disk_size |
|
|
|
|
|
|
|
command <<< |
|
|
|
.... |
|
|
|
>>> |
|
|
|
runtime { |
|
|
|
... |
|
|
|
} |
|
|
|
|
|
|
|
output { |
|
|
|
... |
|
|
|
} |
|
|
|
} |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
对于在 `task` 中所使用到的变量,都需要在 `task` 上面先进行声明,通常有两种形式 `File` 以及 `String` |
|
|
|
|
|
|
|
## workflow 的构建 |
|
|
|
|
|
|
|
> `workflow` 应用于在所有的 `task` 构建完成之后,对于每个步骤进行调用以及每个步骤之间的依赖关系的一个说明,包括以下两个部分 `import`,`call` |
|
|
|
|
|
|
|
```bash |
|
|
|
import "./tasks/mapping.wdl" as mapping |
|
|
|
import "./tasks/Metrics.wdl" as Metrics |
|
|
|
|
|
|
|
workflow sentieon { |
|
|
|
call mapping.mapping as mapping { |
|
|
|
input: |
|
|
|
SENTIEON_INSTALL_DIR=SENTIEON_INSTALL_DIR, |
|
|
|
group=sample, |
|
|
|
sample=sample, |
|
|
|
pl="ILLUMINAL", |
|
|
|
.... |
|
|
|
} |
|
|
|
call Metrics.Metrics as Metrics { |
|
|
|
input: |
|
|
|
.... |
|
|
|
} |
|
|
|
} |
|
|
|
``` |
|
|
|
|
|
|
|
- **import** :表明构建的 `workflow` 中所需要使用的步骤信息,这部分内容可根据使用者分析过程中需要的内容进行自定义: |
|
|
|
|
|
|
|
```bash |
|
|
|
import "./tasks/mapping.wdl" as mapping |
|
|
|
import "./tasks/Metrics.wdl" as Metrics |
|
|
|
import "./tasks/Dedup.wdl" as Dedup |
|
|
|
import "./tasks/deduped_Metrics.wdl" as deduped_Metrics |
|
|
|
import "./tasks/Realigner.wdl" as Realigner |
|
|
|
import "./tasks/BQSR.wdl" as BQSR |
|
|
|
import "./tasks/Haplotyper.wdl" as Haplotyper |
|
|
|
``` |
|
|
|
|
|
|
|
引号内的内容为所要调用的 `task` 信息, `as` 之后的内容(如 `mapping` `Dedup` 等为所定义的步骤的别名)在命名时,应尽量使得命名简单并能包含所需的信息 |
|
|
|
|
|
|
|
- **call** : 是对所引用的 `task` 中的变量进行传递以及对不同的步骤之间的依赖关系进行说明: |
|
|
|
|
|
|
|
```bash |
|
|
|
call mapping.mapping as mapping { |
|
|
|
input: |
|
|
|
SENTIEON_INSTALL_DIR=SENTIEON_INSTALL_DIR, |
|
|
|
group=sample, |
|
|
|
sample=sample, |
|
|
|
pl="ILLUMINAL", |
|
|
|
fasta=fasta, |
|
|
|
ref_dir=ref_dir, |
|
|
|
fastq_1=fastq_1, |
|
|
|
fastq_2=fastq_2, |
|
|
|
docker=docker, |
|
|
|
disk_size=disk_size, |
|
|
|
cluster_config=cluster_config |
|
|
|
} |
|
|
|
|
|
|
|
call Metrics.Metrics as Metrics { |
|
|
|
input: |
|
|
|
SENTIEON_INSTALL_DIR=SENTIEON_INSTALL_DIR, |
|
|
|
fasta=fasta, |
|
|
|
ref_dir=ref_dir, |
|
|
|
sorted_bam=mapping.sorted_bam, |
|
|
|
sorted_bam_index=mapping.sorted_bam_index, |
|
|
|
sample=sample, |
|
|
|
docker=docker, |
|
|
|
disk_size=disk_size, |
|
|
|
cluster_config=cluster_config |
|
|
|
} |
|
|
|
``` |
|
|
|
|
|
|
|
首先需要对 `call` 进行声明,`mapping.mapping as mapping` 中,第一个 `mapping` 是与 `import` 中的别名保持一致,第二个 `mapping` 是与 `task` 中使用的命名保持一致(`task mapping {...}`),第三个 `mapping` 是作为在 `workflow` 中的命名; `input` 是将 `task` 中所使用的变量进行定义,`=`左边是变量名,右边是对变量的赋值,当所使用的变量会重复使用时,可以将其继续以变量的形式进行声明,并在`call`的外部进行声明; |
|
|
|
|
|
|
|
在构建 `pipeline` 中,通常某步的输入文件是上一步的结果输出,在 `call` 中,可以通过对上一步结果文件的引用使得 `workflow` 能自动判别程序的依赖关系,并采取串行或者并行计算;如上所示,`Metrics` 的输入文件是上一步 `mapping` 的输出结果文件,因此在 `input` 中 `mapping.sorted_bam` 表明该步骤使用到 `mapping` 中的 `sorted_bam` 文件,因此只有当 `mapping` 这一步运行结束时,`Metrics` 才会启动运行。 |
|
|
|
|
|
|
|
- **变量声明**:在`workflow` 中,同样需要对 `call` 中没有赋值的变量进行声明: |
|
|
|
|
|
|
|
```bash |
|
|
|
File fastq_1 |
|
|
|
File fastq_2 |
|
|
|
|
|
|
|
String SENTIEON_INSTALL_DIR |
|
|
|
String sample |
|
|
|
String docker |
|
|
|
|
|
|
|
File ref_dir |
|
|
|
File dbmills_dir |
|
|
|
File dbsnp_dir |
|
|
|
String db_mills |
|
|
|
String fasta |
|
|
|
String dbsnp |
|
|
|
String disk_size |
|
|
|
String cluster_config |
|
|
|
``` |
|
|
|
|
|
|
|
类似于 `task` 中的变量声明方式,需要 `File` 及 `String` 声明变量类型, 对于 `workflow` 中的变量,都会在 `input` 中进行赋值; |
|
|
|
|
|
|
|
- **input**: 在 WDL 中所使用的变量,都会在 `input` 文件中进行赋值。变量的读取规则为,在 `call` 的内部使用的变量如果在 `workflow` 中的变量声明中同样进行了定义,则变量的传递顺序为 `input` --> `workflow` 变量声明 --> `call` ,当没有在 `workflow` 中声明,则变量的传递顺序为 `input` --> `call` |
|
|
|
|
|
|
|
```bash |
|
|
|
{ |
|
|
|
"sentieon.fasta": "GRCh38.d1.vd1.fa", |
|
|
|
"sentieon.ref_dir": "oss://pgx-reference-data/GRCh38.d1.vd1/", |
|
|
|
"sentieon.dbsnp": "dbsnp_146.hg38.vcf", |
|
|
|
"sentieon.fastq_1": "oss://pgx-storage-backend/WGS_germline/WGC107658D_combined_R1.fastq.gz", |
|
|
|
"sentieon.SENTIEON_INSTALL_DIR": "/opt/sentieon-genomics", |
|
|
|
"sentieon.dbmills_dir": "oss://pgx-reference-data/GRCh38.d1.vd1/", |
|
|
|
"sentieon.db_mills": "Mills_and_1000G_gold_standard.indels.hg38.vcf", |
|
|
|
"sentieon.cluster_config": "OnDemand ecs.sn2ne.2xlarge img-ubuntu-vpc", |
|
|
|
"sentieon.docker": "localhost:5000/sentieon-genomics:v2018.08.01 oss://pgx-docker-images/dockers", |
|
|
|
"sentieon.dbsnp_dir": "oss://pgx-reference-data/GRCh38.d1.vd1/", |
|
|
|
"sentieon.sample": "WGC107658D", |
|
|
|
"sentieon.disk_size": "500", |
|
|
|
"sentieon.fastq_2": "oss://pgx-storage-backend/WGS_germline/WGC107658D_combined_R2.fastq.gz" |
|
|
|
} |
|
|
|
``` |
|
|
|
|
|
|
|
`input` 文件的生成可以使用 `womtool`(参见[womtool](https://github.com/broadinstitute/cromwell/releases/tag/36)使用), 同时也可使用 `womtool` 对所写的 **WDL** 进行验证。 |
|
|
|
|
|
|
|
```bash |
|
|
|
java -jar womtool.jar validate 2.wdl ####WDL验证 |
|
|
|
java -jar womtool.jar inputs 3step.wdl ### 生成input文件生成 |
|
|
|
``` |
|
|
|
|
|
|
|
- **将 WDL 脚本封装成为 APP**:单个 **WDL** 文件撰写完成之后,可以通过简单的改写就可将 **WDL** 文件封装成为``choppy`中的 **APP** 使用,用于批量提交,改写规则如下: |
|
|
|
|
|
|
|
- 将`workflow` 中的 `workflow_name`变为变量引用形式: |
|
|
|
|
|
|
|
```bash |
|
|
|
workflow {{ project_name }} { |
|
|
|
... |
|
|
|
} |
|
|
|
``` |
|
|
|
|
|
|
|
在 `choppy` 中对于变量是通过 `{{ }}`的形式进行引用,此处 `project_name` 是在使用 **APP** 提交任务时定义的变量,可用于提交任务之后所生成的可追溯的文件; |
|
|
|
|
|
|
|
- 将 `input` 中的相应的 `project_name` (即上面所示例子中的 `sentieon` )改为 `{{project_name}}` ;此外对于后面所需要改变的参数变量,可以使用 `{{ }}` 进行变量引用: |
|
|
|
|
|
|
|
```bash |
|
|
|
{ |
|
|
|
"{{ project_name }}.fasta": "GRCh38.d1.vd1.fa", |
|
|
|
"{{ project_name }}.ref_dir": "oss://pgx-reference-data/GRCh38.d1.vd1/", |
|
|
|
"{{ project_name }}.dbsnp": "dbsnp_146.hg38.vcf", |
|
|
|
"{{ project_name }}.fastq_1": "{{ read1 }}", |
|
|
|
"{{ project_name }}.SENTIEON_INSTALL_DIR": "/opt/sentieon-genomics", |
|
|
|
"{{ project_name }}.dbmills_dir": "oss://pgx-reference-data/GRCh38.d1.vd1/", |
|
|
|
"{{ project_name }}.db_mills": "Mills_and_1000G_gold_standard.indels.hg38.vcf", |
|
|
|
"{{ project_name }}.cluster_config": "{{ cluster if cluster != '' else 'OnDemand ecs.sn1ne.4xlarge img-ubuntu-vpc' }}", |
|
|
|
"{{ project_name }}.docker": "localhost:5000/sentieon-genomics:v2018.08.01 oss://pgx-docker-images/dockers", |
|
|
|
"{{ project_name }}.dbsnp_dir": "oss://pgx-reference-data/GRCh38.d1.vd1/", |
|
|
|
"{{ project_name }}.sample": "{{ sample_name }}", |
|
|
|
"{{ project_name }}.disk_size": "{{ disk_size }}", |
|
|
|
"{{ project_name }}.regions": "{{ regions }}", |
|
|
|
"{{ project_name }}.fastq_2": "{{ read2 }}" |
|
|
|
} |
|
|
|
``` |
|
|
|
{{% endraw %}} |
|
|
|
至此整个 APP 封装完毕,可以在 `choppy` 中使用 |