运行 GATK 最佳做法

本页面介绍了如何使用 Genome Analysis Toolkit (GATK) 最佳做法在 Google Cloud 上运行辅助基因组分析流水线。GATK 最佳做法由 Broad Institute 提供。

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

目标

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

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

费用

在本文档中,您将使用 Google Cloud 的以下收费组件:

  • Compute Engine
  • Cloud Storage

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

准备工作

  1. 登录您的 Google Cloud 账号。如果您是 Google Cloud 新手,请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金,用于运行、测试和部署工作负载。
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. 确保您的 Google Cloud 项目已启用结算功能

  4. Enable the Cloud Life Sciences, Compute Engine, and Cloud Storage APIs.

    Enable the APIs

  5. Install the Google Cloud CLI.
  6. To initialize the gcloud CLI, run the following command:

    gcloud init
  7. Update and install gcloud components:

    gcloud components update
    gcloud components install beta
  8. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  9. 确保您的 Google Cloud 项目已启用结算功能

  10. Enable the Cloud Life Sciences, Compute Engine, and Cloud Storage APIs.

    Enable the APIs

  11. Install the Google Cloud CLI.
  12. To initialize the gcloud CLI, run the following command:

    gcloud init
  13. Update and install gcloud components:

    gcloud components update
    gcloud components install beta
  14. 安装 git 以下载所需的文件。

    下载 git

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

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

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

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

创建 Cloud Storage 存储桶

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

gcloud storage buckets create 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

gatk-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. 运行流水线:

    根据您使用的是默认 VPC 还是自定义 VPC,选择以下选项之一:

    默认 VPC

    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/

    自定义 VPC

    1. 创建环境变量 NETWORKSUBNETWORK 以指定 VPC 网络和子网的名称:

      export NETWORK=VPC_NETWORK
      export SUBNETWORK=VPC_SUBNET
    2. 修改位于 broad-prod-wgs-germline-snps-indels 目录中的 PairedEndSingleSampleWf.options.json 文件,并修改可用区以仅包含子网所在区域中的可用区。例如,如果您使用的是 us-central1 子网,则 zones 字段将如下所示:"zones": "us-central1-a us-central1-b us-central1-c us-central1-f"

    3. gcloud beta lifesciences pipelines run \
      --pipeline-file wdl_pipeline.yaml \
      --location us-central1 \
      --regions us-central1 \
      --network ${NETWORK} \
      --subnetwork ${SUBNETWORK} \
      --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,\
      NETWORK=${NETWORK},\
      SUBNETWORK=${SUBNETWORK} \
      --logging ${GATK_OUTPUT_DIR}/logging/
  5. 该命令以 Running [operations/OPERATION_ID] 格式返回一个操作 ID。您可以使用 gcloud beta lifesciences describe 命令来跟踪流水线的状态:运行以下命令(确保 --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 存储分区中的输出:

    gcloud storage ls gs://BUCKET/FOLDER/output/

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

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

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

复制输入文件

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

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

gcloud storage cp FILE gs://BUCKET/FOLDER

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

gcloud CLI 会自动验证校验和,因此如果传输成功,您的数据将兼容 GATK 最佳做法。

在您的数据上运行流水线

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

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

问题排查

  • 流水线配置为在特定区域和地区中使用 Compute Engine 实例。 运行 gcloud CLI 时,它会根据您创建 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 运行失败,可以通过运行以下命令来检查日志:

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

清理

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

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

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

gcloud storage du gs://BUCKET/FOLDER/work --readable-sizes --summarize

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

gcloud storage rm gs://BUCKET/FOLDER/work/**

删除项目

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

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

  1. 在 Google Cloud 控制台中,前往“项目”页面。

    转到“项目”页面

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

后续步骤

  • Broad Institute GATK 网站论坛中提供了有关 GATK 工具和 WDL 的更多背景信息、文档和支持。