GATK のベスト プラクティスの実行

注: このチュートリアルでは、限られたユースケースで事前定義されたワークフローを実行する方法について説明します。本番環境での実行は想定していません。

このページでは、Genome Analysis Toolkit（GATK）のベスト プラクティスを使用して、Google Cloud でセカンダリ ゲノム解析パイプラインを実行する方法について説明します。GATK のベスト プラクティスは Broad Institute によって提供されています。

このチュートリアルで使用されているワークフローは、全ゲノム配列（WGS）データのバリアント検出のための GATK ベスト プラクティスの実装です。ワークフローは Broad Institute のワークフロー定義言語（WDL）で記述され、Cromwell WDL ランナーで実行されます。

注: ユーザーは GATK エンドユーザー使用許諾契約の条項（帰属要件を含む）を遵守する責任を追います。

目標

このチュートリアルを完了すると、以下のことが行えます。

• ヒト参照ゲノムのビルド 38 のデータで GATK ベスト プラクティスを使用してパイプラインを実行する
• 独自のデータで GATK ベスト プラクティスを使用してパイプラインを実行する

費用

このドキュメントでは、Google Cloud の次の課金対象のコンポーネントを使用します。

• Compute Engine
• Cloud Storage

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。 新しい 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.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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. 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.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

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）
    • Persistent Disk Standard（GB）: 10,500（最低 320）
    • 使用中の IP アドレス: 51（最低 2）

    他の割り当てリクエスト フィールドは空のままにして、現在の割り当てを維持してもかまいません。

    注: 無料トライアルを使用してプロジェクトを作成した場合、Google Cloud で GATK のおすすめの方法を実行するには、より大きな割り当てをリクエストする必要があります。

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: ワークフロー ランタイム オプション

WDL パイプラインを実行するために使用する Cromwell パイプライン定義ファイルは、broadinstitute/wdl-runner/wdl_runner/ リポジトリにあります。

サンプルデータを使用したパイプラインの実行

このセクションでは、ヒト参照ゲノムのビルド 38 を使用して WGS データでパイプラインを実行する方法を説明します。入力ファイルは、非整列の BAM ファイルです。

パイプラインを実行するには、次の手順を実行します。

1. Broad パイプライン ファイルを含むフォルダを指す環境変数 GATK_GOOGLE_DIR を作成します。

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

2. 環境変数 GATK_OUTPUT_DIR を作成します。これは、ワークフローの output 用の Cloud Storage バケットとフォルダ、中間 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 バケット内の出力を一覧表示します。

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

パイプラインで作成された中間ファイルを表示し、保存するファイルを選択するか、それらを削除して Cloud Storage に関連する費用を削減できます。ファイルを削除するには、Cloud Storage バケット内の中間ファイルの削除をご覧ください。

データへの GATK ベスト プラクティス パイプラインの実行

ローカルデータに対してパイプラインを実行する前に、データを Cloud Storage バケットにコピーする必要があります。

入力ファイルのコピー

パイプラインは、Cloud Storage に格納された非整列の BAM ファイルで実行できます。整列 BAM や FASTQ などファイルの形式が異なる場合は、それらを変換してから Cloud Storage にアップロードする必要があります。それらはローカルで変換することも、Pipelines API を使用してクラウドで変換することもできます。

次の例は、1 つのファイルをローカル ファイル システムから Cloud Storage バケットにコピーする方法を示しています。

gcloud storage cp FILE gs://BUCKET/FOLDER

Cloud Storage バケットにファイルをコピーする方法の他の例については、Cloud Storage へのデータのコピーのセクションを参照してください。

gcloud CLI はチェックサムを自動的に検証するため、転送が成功すると、データは GATK ベスト プラクティスで使用できるようになります。

データへのパイプラインの実行

独自の非整列の BAM ファイルに対して GATK のおすすめの方法を実行するには、PairedEndSingleSampleWf.hg38.inputs.json のコピーを作成し、Google 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/**

プロジェクトの削除

課金を停止する最も簡単な方法は、チュートリアル用に使用したプロジェクトを削除することです。

プロジェクトを削除するには:

警告: プロジェクトを削除すると、以下のようになります。

• 既存のプロジェクトを使用した場合、そのプロジェクトで行っていた、他の作業も削除されます。
• 削除されたプロジェクトのプロジェクト ID は再使用できません。将来使用する予定のカスタム プロジェクト ID を作成していた場合は、代わりに、プロジェクト内のリソースを削除してください。この手順では、プロジェクト ID を使用する URL（appspot.com URL など）を引き続き使用できることを確認します。

複数のチュートリアルとクイックスタートを使用しているときは、プロジェクトを削除するのではなく、再利用することで、プロジェクトの割り当て制限を超過せずに済みます。

1. Google Cloud コンソールでプロジェクト ページに移動します。

   プロジェクト ページに移動

2. プロジェクト リストで、削除するプロジェクトを選択し、[プロジェクトの削除] をクリックします。
3. ダイアログでプロジェクト ID を入力し、[シャットダウン] をクリックしてプロジェクトを削除します。

次のステップ

• Broad Institute の GATK のサイトとフォーラムでは、GATK ツールと WDL に関する詳細な背景情報、ドキュメント、サポートを提供しています。