运行 GATK 最佳做法

本页面介绍了如何使用 Broad Institute 提供的 GATK 最佳做法在 Google Cloud 上运行流水线。

本教程中使用的工作流是 GATK 最佳做法的实现,用于在全基因组测序 (WGS) 数据中发现变体。 该工作流使用 Broad Institute 的工作流定义语言 (WDL) 编写,并在 Cromwell WDL 运行程序上运行。

目标

完成本教程后,您将了解如何执行以下任务:

  • 使用 GATK 最佳做法运行流水线,使用人类参考基因组 build 38 的数据
  • 使用您自己的数据和 GATK 最佳做法运行流水线

费用

本教程使用 Google Cloud 的计费组件,包括:

  • Compute Engine
  • Cloud Storage

请使用价格计算器根据您的预计使用情况来估算费用。Cloud Platform 新用户可能有资格免费试用

准备工作

  1. 登录您的 Google 帐号。

    如果您还没有 Google 帐号,请注册一个新帐号

  2. 在 Google Cloud Console 的项目选择器页面上,选择或创建一个 Google Cloud 项目。

    转到项目选择器页面

  3. 确保您的 Cloud 项目已启用结算功能。 了解如何确认您的项目是否已启用结算功能

  4. 启用 Cloud Life Sciences, Compute Engine, and Cloud Storage API。

    启用 API

  5. 安装并初始化 Cloud SDK
  6. 更新并安装 gcloud 组件:
    gcloud components update &&
    gcloud components install beta
  7. 安装 git 以下载所需的文件。

    下载 git

  8. 默认情况下,Compute Engine 已配置适当的资源配额以防止意外错误使用。 通过增加配额,您可以同时启动更多虚拟机,从而提高吞吐量并缩短周转时间。

    为了在本教程中获得最佳结果,您应该在项目默认配额的基础上申请更多配额。以下列表提供了增加配额的建议,以及运行本教程所需的最低配额。在 us-central1 区域申请配额:

    • CPU:101(最少 17)
    • 永久性磁盘(标准,单位为 GB):10500(最少 320)
    • 使用中的 IP 地址:51(最少 2 个)

    您可以将其他配额申请字段留空以保留当前配额。

创建 Cloud Storage 存储分区

使用 gsutil mb 命令创建 Cloud Storage 存储分区。由于 Cromwell 引擎中的要求,请勿在存储分区名称中使用下划线 (_) 字符,否则将出现错误。

gsutil mb gs://BUCKET

流水线将输出结果、日志和中间文件到此存储分区。

下载示例文件

下载 WDL 和帮助程序脚本:

git clone https://github.com/broadinstitute/wdl-runner.git
git clone https://github.com/gatk-workflows/broad-prod-wgs-germline-snps-indels.git

workflows/broad-prod-wgs-germline-snps-indels 代码库包含运行流水线所需的以下文件:

  • *.wdl:工作流定义
  • *.inputs.json:输入参数,包括 BAM 文件和参考基因组的路径
  • *.options.json:工作流运行时选项

您可以在 broadinstitute/wdl-runner/wdl_runner/ 代码库找到用于运行 WDL 流水线的 Cromwell 流水线定义文件。

使用样本数据运行流水线

该流水线使用人体参考基因组的 build 38 与 WGS 数据一起运行。输入文件是未对齐的 BAM 文件。

要运行流水线,请执行以下操作:

  1. 创建环境变量 GATK_GOOGLE_DIR,该变量指向包含 Broad 流水线文件的文件夹:

    export GATK_GOOGLE_DIR="${PWD}"/broad-prod-wgs-germline-snps-indels
    
  2. 创建指向 Cloud Storage 存储分区的环境变量 GATK_OUTPUT_DIR 以及用于工作流的 output 及中间 work 文件和 logging 的文件夹:

    export GATK_OUTPUT_DIR=gs://BUCKET/FOLDER
    
  3. 将目录更改为您下载的代码库中的 /wdl_runner 文件夹。此目录包含用于在 Google Cloud 上运行基于 WDL 的流水线的流水线定义文件:

    cd wdl-runner/wdl_runner/
    
  4. 运行流水线:

    gcloud beta lifesciences pipelines run \
      --pipeline-file wdl_pipeline.yaml \
      --location us-central1 \
      --regions us-central1 \
      --inputs-from-file WDL=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.wdl,\
    WORKFLOW_INPUTS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.hg38.inputs.json,\
    WORKFLOW_OPTIONS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.options.json \
      --env-vars WORKSPACE=${GATK_OUTPUT_DIR}/work,\
    OUTPUTS=${GATK_OUTPUT_DIR}/output \
      --logging ${GATK_OUTPUT_DIR}/logging/
    
  5. 该命令以 Running [operations/OPERATION_ID] 格式返回一个操作 ID。您可以运行以下命令来使用操作 ID 跟踪流水线的状态(确保 --location 标志的值与上一步中指定的位置匹配):

    gcloud beta lifesciences operations describe OPERATION_ID \
        --location=us-central1 \
        --format='yaml(done, error, metadata.events)'
    
  6. 当流水线运行完成时,operations describe 命令返回 done: true

    您可以运行 wdl_runner 附带的脚本来检查作业是否正在运行、已完成或返回错误,每 300 秒检查一次:

    ../monitoring_tools/monitor_wdl_pipeline.sh OPERATION_ID us-central1 300
    
  7. 流水线完成后,运行以下命令以列出 Cloud Storage 存储分区中的输出:

    gsutil ls gs://BUCKET/FOLDER/output/
    

您可以查看流水线创建的中间文件,并选择要保留或删除它们以降低 Cloud Storage 相关的成本。要删除文件,请参阅删除 Cloud Storage 存储分区中的中间文件

在您的数据上运行 GATK 最佳做法流水线

在对本地数据运行流水线之前,需要将数据复制到 Cloud Storage 存储分区中。

复制输入文件

流水线可以使用存储在 Cloud Storage 中的未对齐 BAM 文件运行。如果您的文件采用不同的格式(例如对齐的 BAM 或 FASTQ),则必须先将其转换为可以上传到 Cloud Storage 的格式。您可以在本地转换它们,也可以使用流水线 API 在云端转换它们。

以下示例显示如何将单个文件从本地文件系统复制到 Cloud Storage 存储分区:

gsutil -m -o 'GSUtil:parallel_composite_upload_threshold=150M' cp FILE \
    gs://BUCKET/FOLDER

如需了解如何将文件复制到 Cloud Storage 存储分区的更多示例,请参阅将数据复制到 Cloud Storage 部分。

gsutil 命令行工具会自动验证校验和,因此如果传输成功,您的数据将兼容 GATK 最佳做法。

在您的数据上运行流水线

要在您自己的未对齐 BAM 文件上运行 GATK 最佳做法,请复制 PairedEndSingleSampleWf.hg38.inputs.json,然后更新路径以指向 Cloud Storage 存储分区中的文件。然后,您可以使用更新的 PairedEndSingleSampleWf.hg38.inputs.json 文件,按照使用样本数据运行流水线中的步骤进行操作。

如果您的数据不是由未对齐的 BAM 文件组成,并且包含参考基因组、外显子组序列、目标面板和体细胞数据,则必须使用不同的工作流。如需了解详情,请参阅 GATK 支持论坛Broad Institute GitHub 代码库

问题排查

  • 流水线配置为在特定区域和地区中使用 Compute Engine 实例。 运行 gcloud 工具时,它会根据您创建 Google Cloud 项目的位置自动使用默认区域和地区。这可能导致在运行流水线时出现以下错误消息:

    "ERROR: (gcloud.beta.lifesciences.pipelines.run) INVALID_ARGUMENT: Error: validating pipeline: zones and regions cannot be specified together"

    要解决此问题,请通过运行以下命令移除默认区域和地区,然后再次运行流水线:

    gcloud config unset compute/zone
    gcloud config unset compute/region
    

    如需详细了解如何为 Google Cloud 项目设置默认区域和地区,请参阅更改默认地区或区域

  • 如果您在运行流水线时遇到问题,请参阅 Cloud Life Sciences API 问题排查

  • GATK 对输入文件格式有严格的要求。为避免出现问题,您可以验证文件是否通过了 ValidateSamFile

  • 如果您的 GATK 运行失败,可以通过运行以下命令来检查日志:

    gsutil ls gs://BUCKET/FOLDER/logging
    
  • 如果遇到权限错误,请检查您的服务帐号是否具有对输入文件的读取权限以及对输出存储分区路径的写入权限。如果您正在将输出文件写入不属于您的 Google Cloud 项目中的存储分区,则需要授予服务帐号访问存储分区的权限。

清理

删除 Cloud Storage 存储分区中的中间文件

当您运行流水线时,中间文件将存储在 gs://BUCKET/FOLDER/work 中。您可以在工作流完成后移除这些文件,以减少 Cloud Storage 费用。

如需查看 work 目录中使用的空间量,请运行以下命令。鉴于目录中的文件大小,该命令可能需要几分钟才能运行。

gsutil du -sh gs://BUCKET/FOLDER/work

如需移除 work 目录中的所有中间文件,请运行以下命令:

gsutil -m rm gs://BUCKET/FOLDER/work/**

删除项目

避免支付费用的最简单方法是删除您为本教程使用的项目。

要删除项目,请执行以下操作:

  1. 在 Cloud Console 中,转到“项目”页面。

    转到“项目”页面

  2. 在项目列表中,选择要删除的项目,然后点击删除项目选择项目名称旁边的复选框后,点击“删除项目”
  3. 在对话框中输入项目 ID,然后点击关闭以删除项目。

后续步骤

  • 本教程介绍了如何在有限的使用场景中运行预定义的工作流,但该工作流并不一定会在生产环境中运行。如需了解如何在 Google Cloud 的生产环境中执行基因组数据处理,请参阅基因组数据处理参考架构
  • Broad Institute GATK 网站论坛中提供了有关 GATK 工具和 WDL 的更完整的背景信息、文档和支持。