GATK のおすすめの方法の実行

このページでは、Broad Institute によって提供されている GATK ベスト プラクティスを使用して、Google Cloud でパイプラインを実行する方法を説明します。

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

目標

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

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

費用

このチュートリアルでは、Google Cloud の課金対象となる以下のコンポーネントを使用します。

  • Compute Engine
  • Cloud Storage

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを出すことができます。Cloud Platform を初めて使用する方は、無料トライアルをご利用いただけます。

始める前に

  1. Google アカウントにログインします。

    Google アカウントをまだお持ちでない場合は、新しいアカウントを登録します。

  2. Cloud Console のプロジェクト セレクタページで、Cloud プロジェクトを選択または作成します。

    プロジェクト セレクタのページに移動

  3. Google Cloud プロジェクトに対して課金が有効になっていることを確認します。プロジェクトに対して課金が有効になっていることを確認する方法を学習する

  4. Cloud Life Sciences, Compute Engine, and Cloud Storage API を有効にします。

    API を有効にする

  5. Cloud SDK をインストールして初期化します。
  6. gcloud コンポーネントを更新してインストールします。
    gcloud components update &&
    gcloud components install beta
  7. git をインストールして、必要なファイルをダウンロードします。

    git のダウンロード

  8. デフォルトで Compute Engine にはリソースの割り当てがあり、不注意による使用を防ぎます。割り当てを増やすことで、より多くの仮想マシンを同時に起動し、スループットを向上させ、ターンアラウンド タイムを短縮できます。

    このチュートリアルでベストな結果を得るには、プロジェクトのデフォルトより多くの追加の割り当てをリクエストする必要があります。割り当ての増加に関する推奨事項は、チュートリアルを実行するために必要な最小限の割り当てとともに、次のリストに記載されています。us-central1 リージョンで割り当てリクエストを作成します。

    • CPU: 101(最低 17)
    • Persistent Disk Standard(GB): 10,500(最低 320)
    • 使用中の IP アドレス: 51(最低 2)

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

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

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. パイプラインを実行します。

    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/
    
  5. このコマンドからは、Running [operations/OPERATION_ID] という形式でオペレーション ID が返されます。次のコマンドを実行すると、オペレーション ID を使用してパイプラインのステータスを追跡できます(--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 にアップロードする必要があります。それらはローカルで変換することも、Pipelines API を使用してクラウドで変換することもできます。

次の例は、1 つのファイルをローカル ファイル システムから 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 のコピーを作成し、Google Cloud Storage バケット内のファイルを指すようにパスを更新します。その後、更新済みの PairedEndSingleSampleWf.hg38.inputs.json ファイルを使用して、サンプルデータを使用してパイプラインを実行するの手順を行えます。

データが非整列の BAM ファイルで構成されておらず、参照ゲノム、エクソーム配列、ターゲット設定パネル、体細胞データを含んでいる場合、異なるワークフローを使用する必要があります。詳細については、GATK サポート フォーラムBroad Institute GitHub リポジトリをご覧ください。

トラブルシューティング

  • パイプラインは、特定のリージョンおよびゾーンにある Compute Engine インスタンスを使用するように構成されています。gcloud ツールを実行すると、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/**

プロジェクトの削除

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

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

  1. Cloud Console で、プロジェクト ページに移動します。

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

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

次のステップ

  • このチュートリアルでは、限られたユースケースで事前定義されたワークフローを実行する方法について説明します。本番環境での実行は想定していません。Google Cloud の本番環境で遺伝子データ処理を行う方法については、遺伝子データ処理のリファレンス アーキテクチャをご覧ください。
  • The Broad Institute GATK のサイトフォーラムでは、GATK ツールと WDL に関する詳細な背景情報、ドキュメント、サポートを提供しています。