執行 GATK 最佳做法

本頁面說明如何使用 Genome Analysis Toolkit (GATK) 最佳做法，在 Google Cloud 上執行次要基因體分析管道。GATK 最佳做法由 Broad Institute 提供。

本教學課程中使用的工作流程是針對全基因體定序 (WGS) 資料中的變異基因段探索實作 GATK 最佳做法。工作流程以 Broad Institute 的工作流程定義語言 (WDL) 編寫，並且會在 Cromwell WDL 執行器上執行。

目標

完成本教學課程後，您將會學到以下內容：

  • 使用 GATK 最佳做法，對人類參照基因體 38 版中的資料執行管道
  • 使用 GATK 最佳做法，對您自己的資料執行管道

費用

在本文件中，您會使用 Google Cloud的下列計費元件：

  • Compute Engine
  • Cloud Storage

如要根據預測用量估算費用，請使用 Pricing Calculator。

初次使用 Google Cloud 的使用者可能符合免費試用資格。

事前準備

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

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

    Enable the APIs

  5. Install the Google Cloud CLI.

  6. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  7. To initialize the gcloud CLI, run the following command: 

    gcloud init

  8. After initializing the gcloud CLI, update it and install the required components: 

    gcloud components update
gcloud components install beta

  9. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  10. Make sure that billing is enabled for your Google Cloud project.

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

    Enable the APIs

  12. Install the Google Cloud CLI.

  13. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  14. To initialize the gcloud CLI, run the following command: 

    gcloud init

  15. After initializing the gcloud CLI, update it and install the required components: 

    gcloud components update
gcloud components install beta
  16. 安裝 git 以下載必要檔案。

    下載 Git

  17. 根據預設，Compute Engine 設有資源配額，可防止不慎超出使用量。您可以增加配額來並行啟動更多虛擬機器，藉以增加總處理量並減少作業時間。

    如要在本教學課程中獲得最佳結果，您應要求高於專案預設配額的更多配額。以下清單提供了增加配額的建議，還有執行教學課程所需的最低配額。請在 us-central1 地區提出配額要求：

    • CPU：101 個 (下限為 17 個)
    • 永久磁碟標準 (GB)：10,500 (下限為 320)
    • 使用中 IP 位址：51 個 (最低為 2 個)

    如要保留目前的配額，可將其他配額要求欄位保留空白。

    18. 建立 Cloud Storage 值區

    使用 gcloud storage buckets create 指令建立 Cloud Storage bucket。基於 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 管道定義檔案。

    使用樣本資料執行管道

    本節說明如何使用人類參照基因體 38 版的 WGS 資料執行管道。輸入檔案是未校正的 BAM 檔案。

    如要執行管道，請完成下列步驟：

    1. 建立環境變數 GATK_GOOGLE_DIR，指向包含 Broad 管道檔案的資料夾：

      export GATK_GOOGLE_DIR="${PWD}"/broad-prod-wgs-germline-snps-indels

    2. 建立環境變數 GATK_OUTPUT_DIR，指向工作流程 output、中繼 work 檔案與 logging 的 Cloud Storage 值區和資料夾：

      export GATK_OUTPUT_DIR=gs://BUCKET/FOLDER

    3. 將目錄變更為您下載的存放區中的 /wdl_runner 資料夾。這個目錄包含管道定義檔案，可用於在 Google Cloud上執行 WDL 管道：

      cd wdl-runner/wdl_runner/

    4. 執行管道：

      根據您使用的是預設 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/

      自訂虛擬私有雲

      1. 建立 NETWORK 和 SUBNETWORK 環境變數，指定虛擬私有雲網路和子網路的名稱：

        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. 指令會傳回作業 ID，其格式為 Running [operations/OPERATION_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。您可以在本機轉換，也可以使用 Pipelines 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 控制台的「Projects」(專案) 頁面。

      前往「Projects」(專案) 頁面

    2. 在專案清單中，選取要刪除的專案，然後按一下「刪除專案」。 選擇專案名稱旁邊的核取方塊後，按一下「刪除專案」
    3. 在對話方塊中輸入專案 ID，然後按一下 [Shut down] (關閉) 以刪除專案。

    後續步驟

    • Broad Institute GATK 網站和論壇提供 GATK 工具和 WDL 的更完整背景資訊、說明文件及支援。