14KB

Surový Blame Historie

id: quick-intro title: 快速指南：Choppy for Reproducible Omics Pipeline

{% raw %}

Author: Yechao Huang

Email: 17210700095@fudan.edu.cn

Date: 2019-01-18

Choppy快速指南

Pipeline 分析三步走

基于Choppy平台进行 Pipeline 分析十分简单高效，只需要三步即可轻松搞定(点击进入演示视频)：

登陆Choppy App Store，挑选符合自己需求的 App，并安装
准备 App 所需的 Samples 文件
提交任务

使用 APP 提交任务

基于 choppy 封装的 app 可以使得用户可以通过自定义或者下载的 app 简单快速的进行可重复并且可溯源的任务提交

选择所要使用的 app 并生成相应的 samples.csv 文件（以 dna-germline-0.1.0 为例）

  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 文件批量提交任务

  choppy batch dna-germline-0.1.0 samples.csv --project-name project

当出现如下所示的信息时，表明当前任务提交成功：

  Sample ID: 1, Workflow ID: a6a24b7d-bea3-48fe-93f6-7b7aa8ce9b5f
  Successed: 1, /home/huangyechao/project/submitted.csv

其中，第一行为所提交的样本的名字以及每一个样本对应的 workflow ID ，可用于查询该任务的运行状态；当有多个样本时，会有多行出现。第二行为统计 app 端成功的样本数，并且会生成包含有当次任务成功提交时的所有信息第三行为为统计 app 端失败的样本数（若没有失败则不会产生）

根据生成的 Workflow ID 可以进行任务状态的查询，使用命令如下

  choppy query -s a6a24b7d-bea3-48fe-93f6-7b7aa8ce9b5f

此时会显示出该样本任务的状态信息，当显示为 submitted 时，表示任务正在向云端及进行投递过程中；显示为 Running 时，表示任务已经成功在云端运行；当显示为 Failed 时，表示任务运行失败。使用 -m 参数可以查看更多关于任务的日志信息：

  choppy query -s -m a6a24b7d-bea3-48fe-93f6-7b7aa8ce9b5f

当任务提交成功之后，可登陆到阿里云控制台中，在批量计算的作业列表中查询任务的运行情况；通常当任务提交到阿里云计算平台时，会需要几分钟的服务器配置时间之后任务才会开始进行计算。

构建属于自己 WDL

在构建 WDL 之前，需要先对 WDL 的基本结果有一定的了解，其基本结构包含以下部分：workflow，task，call, command以及output（详见WDL Base Structure）

以下是对构建 WDL 脚本的一个简单教程（以 Sentieon 的 DNA-seq 为例）：

单个 task 的构建

command：通常我们在构建pipeline 时，是将每一步分析写入到一个脚本中，并调用脚本的方式串行使用，如下所示：

  $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 中对结果的输出进行定义：

  output {
  		File sorted_bam = "${sample}.sorted.bam"
  		File sorted_bam_index = "${sample}.sorted.bam.bai"
  	}

左边为当前 task 输出结果的命名，右边为所输出结果文件名，用 " " 进行引用；

当有多个结果文件输出时，只有在 output 中进行了定义的结果文件才会输出，没有定义的将不会输出到结果目录中；

runtime：对于每一个 task 的运行环境需要进行定义，包括所使用的软件的 docker信息，所使用的服务器配置信息，以及服务器的系统盘以及数据盘大小：

  runtime {
  		dockerTag:docker
      	cluster: cluster_config
      	systemDisk: "cloud_ssd 40"
      	dataDisk: "cloud_ssd " + disk_size + " /cromwell_root/"
  	}

dockerTag 为所使用的 docker 信息，此处以变量表示

cluster 为运行命令是所选用的服务器实例信息（参照阿里云服务器 ECS）

systemDisk 为使用的系统盘的大小，默认为 cloud_ssd 40G

dataDisk 为使用的数据盘的大小信息，默认类型为 cloud_ssd ，挂载点为 /cromwell_root/

注意：在系统盘和数据盘的写法上，需注意不同的变量之间存在空格

在将 command 主体部分改写完成之后，需要在 task 中声明 command 中所使用的变量形式：

  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

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 中所需要使用的步骤信息，这部分内容可根据使用者分析过程中需要的内容进行自定义：

  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 中的变量进行传递以及对不同的步骤之间的依赖关系进行说明：

  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 中没有赋值的变量进行声明：

  	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

  {
    "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使用), 同时也可使用 womtool 对所写的 WDL 进行验证。

  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变为变量引用形式：

workflow {{ project_name }} {
   ...
}

在 choppy 中对于变量是通过 {{ }}的形式进行引用，此处 project_name 是在使用 APP 提交任务时定义的变量，可用于提交任务之后所生成的可追溯的文件；

将 input 中的相应的 project_name （即上面所示例子中的 sentieon ）改为 {{project_name}} ；此外对于后面所需要改变的参数变量，可以使用 {{ }} 进行变量引用：

{
    "{{ 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 中使用

14KB Surový Blame Historie

sidebar_label: 快速指南