运行 GATK 最佳做法

注意：本教程介绍了如何在有限的使用场景中运行预定义的工作流，但该工作流并不一定会在生产环境中运行。如需了解如何在 Google Cloud 的生产环境中执行基因组数据处理，请参阅基因组数据处理参考架构。

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

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

注意 ：您负责遵守 GATK 最终用户许可协议的条款，包括归因要求。

目标

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

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

费用

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

• Compute Engine
• Cloud Storage

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

须知事项

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

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

   注意：如果您不打算保留在此过程中创建的资源，请创建新的项目，而不要选择现有的项目。完成本教程介绍的步骤后，您可以删除所创建的项目，并移除与该项目关联的所有资源。

   转到“项目选择器”

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

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

   启用 API

5. 安装 Google Cloud CLI。

6. 如需初始化 gcloud CLI，请运行以下命令：

   gcloud init

7. 更新并安装 gcloud 组件：

   gcloud components update
   gcloud components install beta

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

   注意：如果您不打算保留在此过程中创建的资源，请创建新的项目，而不要选择现有的项目。完成本教程介绍的步骤后，您可以删除所创建的项目，并移除与该项目关联的所有资源。

   转到“项目选择器”

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

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

    启用 API

11. 安装 Google Cloud CLI。

12. 如需初始化 gcloud CLI，请运行以下命令：

    gcloud init

13. 更新并安装 gcloud 组件：

    gcloud components update
    gcloud components install beta

14. 安装 git 以下载所需的文件。

    下载 git

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

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

    • CPU：101（最少 17）
    • Persistent Disk Standard (GB)：10500（最少 320）
    • 使用中的 IP 地址：51（最少 2 个）

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

    注意：如果您的项目是使用免费试用创建的，则必须申请更高的配额才能在 Google Cloud 上运行 GATK 最佳实践。

创建 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. 运行流水线：

   重要提示：如果您遇到错误消息 "ERROR: (gcloud.beta.lifesciences.pipelines.run) INVALID_ARGUMENT: Error: validating pipeline: zones and regions cannot be specified together"，请参阅问题排查。

   根据您使用的是默认 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. 创建环境变量 NETWORK 和 SUBNETWORK 以指定 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 存储桶中的输出：

   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 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 运行失败，可以通过运行以下命令来检查日志：

  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/**

删除项目

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

要删除项目，请执行以下操作：

警告：删除项目会产生以下后果：

• 如果您使用的是现有项目，则该项目中完成的任何其他工作也会被删除。
• 已删除项目的 ID 不可重复使用。 如果您创建了打算将来使用的自定义项目 ID，请改为删除项目内的资源。 这个步骤可确保使用项目 ID 的网址（例如 appspot.com 网址）仍然可用。

如果您正在探索多个教程和快速入门，重复使用项目（而不是删除项目）可以防止您超出项目配额上限。

1. 在 Google Cloud 控制台中，转到“项目”页面。

   转到“项目”页面

2. 在项目列表中，选择要删除的项目，然后点击删除项目。
3. 在对话框中输入项目 ID，然后点击关闭以删除项目。

后续步骤

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