maftools/report/about/choppy.md

---
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` 中使用