このページでは、Genome Analysis Toolkit(GATK)のベスト プラクティスを使用して、Google Cloud でセカンダリ ゲノム解析パイプラインを実行する方法について説明します。GATK のベスト プラクティスは Broad Institute によって提供されています。
このチュートリアルで使用されているワークフローは、全ゲノム配列(WGS)データのバリアント検出のための GATK ベスト プラクティスの実装です。ワークフローは Broad Institute のワークフロー定義言語(WDL)で記述され、Cromwell WDL ランナーで実行されます。
目標
このチュートリアルを完了すると、以下のことが行えます。
- ヒト参照ゲノムのビルド 38 のデータで GATK ベスト プラクティスを使用してパイプラインを実行する
- 独自のデータで GATK ベスト プラクティスを使用してパイプラインを実行する
費用
このドキュメントでは、Google Cloud の次の課金対象のコンポーネントを使用します。
- Compute Engine
- Cloud Storage
料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。
始める前に
- 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Cloud Life Sciences, Compute Engine, and Cloud Storage APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Update and install
gcloud
components:gcloud components update
gcloud components install beta -
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Cloud Life Sciences, Compute Engine, and Cloud Storage APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Update and install
gcloud
components:gcloud components update
gcloud components install beta - git をインストールして、必要なファイルをダウンロードします。
-
デフォルトで Compute Engine にはリソースの割り当てがあり、不注意による使用を防ぎます。割り当てを増やすことで、より多くの仮想マシンを同時に起動できます。これにより、スループットが向上し、ターンアラウンド タイムが短縮します。
このチュートリアルでベストな結果を得るには、プロジェクトのデフォルトより多くの追加の割り当てをリクエストする必要があります。割り当ての増加に関する推奨事項は、チュートリアルを実行するために必要な最小限の割り当てとともに、次のリストに記載されています。
us-central1
リージョンで割り当てリクエストを作成します。- CPU: 101(最低 17)
- Persistent Disk Standard(GB): 10,500(最低 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
: ワークフロー ランタイム オプション
WDL パイプラインを実行するために使用する Cromwell パイプライン定義ファイルは、broadinstitute/wdl-runner/wdl_runner/ リポジトリにあります。
サンプルデータを使用したパイプラインの実行
このセクションでは、ヒト参照ゲノムのビルド 38 を使用して WGS データでパイプラインを実行する方法を説明します。入力ファイルは、非整列の BAM ファイルです。
パイプラインを実行するには、次の手順を実行します。
Broad パイプライン ファイルを含むフォルダを指す環境変数
GATK_GOOGLE_DIR
を作成します。export GATK_GOOGLE_DIR="${PWD}"/broad-prod-wgs-germline-snps-indels
環境変数
GATK_OUTPUT_DIR
を作成します。これは、ワークフローのoutput
用の Cloud Storage バケットとフォルダ、中間work
ファイル、logging
を指します。export GATK_OUTPUT_DIR=gs://BUCKET/FOLDER
ディレクトリを、ダウンロードしたリポジトリ内の
/wdl_runner
フォルダに変更します。このディレクトリには、Google Cloud で WDL ベースのパイプラインを実行するためのパイプライン定義ファイルが格納されています。cd wdl-runner/wdl_runner/
パイプラインを実行します。
デフォルト 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
環境変数
NETWORK
とSUBNETWORK
を作成して、VPC ネットワークとサブネットワークの名前を指定します。export NETWORK=VPC_NETWORK export SUBNETWORK=VPC_SUBNET
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"
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/
このコマンドからは、
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)'
operations describe
コマンドからdone: true
が返されたときは、パイプラインが完了しています。wdl_runner
に付属するスクリプトを実行して、ジョブの実行中、終了、またはエラーを返したかどうかを 300 秒ごとにチェックできます。../monitoring_tools/monitor_wdl_pipeline.sh OPERATION_ID us-central1 300
パイプラインが終了したら、次のコマンドを実行して 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/**
プロジェクトの削除
課金を停止する最も簡単な方法は、チュートリアル用に使用したプロジェクトを削除することです。
プロジェクトを削除するには:
- Google Cloud コンソールでプロジェクト ページに移動します。
- プロジェクト リストで、削除するプロジェクトを選択し、[プロジェクトの削除] をクリックします。
- ダイアログでプロジェクト ID を入力し、[シャットダウン] をクリックしてプロジェクトを削除します。