ゲノム バリアントの保存と読み込み

このページでは、大規模な分析を行うために、Variant Transforms ツールを使用して VCF ファイルを変換し、BigQuery に直接読み込む方法について説明します。

多数のファイルを読み込む場合、パフォーマンスの向上とコストの削減に関する推奨事項について大量入力の処理をご覧ください。

VCF ファイルを BigQuery に読み込んで変換する

始める前に

ツールを実行するには、次の条件を満たしている必要があります。

ツールの実行

このツールを実行するには、必要なバイナリと依存関係がすべてインストール済みである Docker イメージを使用します。

Docker イメージを使用してこのツールを実行する手順は次のとおりです。

  1. 最新バージョンの Variant Transforms を入手するには、次のコマンドを使用します。

    docker pull gcr.io/cloud-lifesciences/gcp-variant-transforms

  2. 次のテキストをコピーして、script.sh という名前のファイルに保存します。変数は、実際の Google Cloud プロジェクトの該当するリソースに置き換えてください。

    #!/bin/bash
# Parameters to replace:
# The GOOGLE_CLOUD_PROJECT is the project that contains your BigQuery dataset.
GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
INPUT_PATTERN=gs://BUCKET/*.vcf
OUTPUT_TABLE=GOOGLE_CLOUD_PROJECT:BIGQUERY_DATASET.BIGQUERY_TABLE
TEMP_LOCATION=gs://BUCKET/temp

COMMAND="vcf_to_bq \
    --input_pattern ${INPUT_PATTERN} \
    --output_table ${OUTPUT_TABLE} \
    --temp_location ${TEMP_LOCATION} \
    --job_name vcf-to-bigquery \
    --runner DataflowRunner"
docker run -v ~/.config:/root/.config \
    gcr.io/cloud-lifesciences/gcp-variant-transforms \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --zones us-west1-b \
    "${COMMAND}"

    Cloud Storage バケットの中の VCF ファイルの場所を指定するときは、ファイルを 1 つだけ指定することも、ワイルドカード（*）を使用して複数のファイルを一度に読み込むこともできます。受け入れられるファイル形式は、GZIP、BZIP、VCF があります。詳細については、複数ファイルの読み込みをご覧ください。

    ファイルが圧縮されている場合はこのツールの実行に時間がかかることに注意してください。圧縮ファイルはシャーディングできないからです。複数のファイルのサンプルをマージする必要がある場合は、バリアントのマージのドキュメントをご覧ください。

    TEMP_LOCATION ディレクトリには、このツールの実行に必要な一時ファイルが格納されます。これは、書き込みアクセス権を持つ Cloud Storage 内の任意のディレクトリにできます。

  3. 次のコマンドを実行して、script.sh を実行可能にします。

    chmod +x script.sh

  4. script.sh を実行します。

    ./script.sh

  5. さまざまな要因、たとえばデータのサイズにより、ジョブ完了までの時間は異なります。数分で済むこともあれば、1 時間以上かかる場合もあります。

    このツールは Dataflow を使用するため、Dataflow Console に移動するとジョブの詳細情報を見ることができます。たとえば、処理されたレコードの数や、ワーカーの数、詳細なエラーログを確認できます。

  6. ジョブが完了した後で、次のコマンドを実行してデータセット内のすべてのテーブルのリストを取得します。VCF データが格納されている新しいテーブルがこのリストにあることを確認してください。

    bq ls --format=pretty GOOGLE_CLOUD_PROJECT:BIGQUERY_DATASET

    テーブルに関する詳細情報を表示することもできます。たとえば、スキーマや最終変更日です。

    bq show --format=pretty GOOGLE_CLOUD_PROJECT:BIGQUERY_DATASET.BIGQUERY_TABLE

ゾーンとリージョンの設定

Google Cloud では、ゾーンに分割されたリージョンを使用して、物理的なコンピューティング リソースの地理的なロケーションを定義します。

Dataflow がサポートされているどのリージョンまたはゾーンでも、Variant Transforms ツールを実行できます。

ツールを実行するリージョンを変更するには、Docker COMMAND 環境変数と Cloud Life Sciences API gcloud コマンドの両方を更新します。たとえば、ジョブ処理をヨーロッパに限定する場合、前のセクションの Docker イメージ スクリプトは次のようになります。

#!/bin/bash
# Parameters to replace:
# The GOOGLE_CLOUD_PROJECT is the project that contains your BigQuery dataset.
GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
INPUT_PATTERN=gs://BUCKET/*.vcf
OUTPUT_TABLE=GOOGLE_CLOUD_PROJECT:BIGQUERY_DATASET.BIGQUERY_TABLE
TEMP_LOCATION=gs://BUCKET/temp

COMMAND="vcf_to_bq \
    --input_pattern ${INPUT_PATTERN} \
    --output_table ${OUTPUT_TABLE} \
    --temp_location ${TEMP_LOCATION} \
    --job_name vcf-to-bigquery \
    --runner DataflowRunner
    --region europe-west1
    --zone europe-west1-b"
docker run -v ~/.config:/root/.config \
    gcr.io/cloud-lifesciences/gcp-variant-transforms \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --zones europe-west1-b \
    "${COMMAND}"

BigQuery データセットのロケーションを設定する方法については、データセットの作成をご覧ください。

複数のファイルの読み込み

上記のスクリプトで --input_pattern フラグを使用して、BigQuery に読み込む VCF ファイルを指定できます。たとえば、すべての VCF ファイルを my-bucket Cloud Storage バケットに読み込むには、フラグを次のように設定します。

--input_pattern=gs://my-bucket/*.vcf

Variant Transforms ツールで複数のファイルを読み込むと、次の操作が実行されます。

  1. --input_pattern フラグのリストにある、一致するすべての VCF ファイルのデータからなるマージされた BigQuery スキーマが作成されます。たとえば、VCF ファイル間で共有される INFO フィールドと FORMAT フィールドがマージされます。このステップでは、同じキーを持つ複数のファイルで定義されたフィールドに互換性があることを想定しています。

  2. すべての VCF ファイルのレコードが単一のテーブルに読み込まれます。欠落しているすべてのフィールドは、該当する列で null に設定されます。

3 つ目のステップとしてサンプルをマージすることもできます。詳細については、バリアントのマージをご覧ください。

VCF ファイルを読み込むとき、ファイルのフィールド定義と値は一貫していなければならず、そうでなければツールはエラーになります。ツールは、これらの不整合を修正するように設定されている場合、修正を試行できます。詳細については、不正な形式のファイルの処理をご覧ください。

既存の BigQuery テーブルへのデータの追加

Variant Transforms ツールを実行するときに --append フラグを追加することで、既存の BigQuery テーブルにデータを追加できます。

データを追加するときに最良の結果を得るには、追加データで使用されるスキーマと既存のテーブルのスキーマが同じであることが推奨されます。追加データのスキーマに既存のテーブルの列と同じ名前の列が含まれる場合は、両方の列で名前、データ型、モードが同じになっている必要があります。そうでなければ、Variant Transforms ツールはエラーを返します。

--append フラグに加えて --update_schema_on_append フラグを指定することで、既存のテーブルとは異なるスキーマを持つデータを追加できます。追加データの新しい列が既存のスキーマに追加されます。既存のスキーマの各行では、それらの新しい列の値は NULL に設定されます。同様に、追加データにはない列が既存のスキーマにある場合、追加データの各行でのそれらの列の値も NULL になります。

不正な形式のファイルの処理

不正な形式のファイルや互換性のないファイルを処理するためのいくつかのオプションがあります。VCF ファイルを読み込む前に、VCF ファイル プリプロセッサ ツールを使用して、不正な形式のファイルや互換性のないファイルがないかを確認できます。

フィールドの非互換性の処理

複数の VCF ファイルを読み込む際、Variant Transforms ツールは、INFO フィールドと HEADER フィールドをすべてマージして、「代表的なヘッダー」を生成します。次に、代表的なヘッダーを使用して BigQuery スキーマを作成します。同じキーが複数のファイルで定義されている場合、すべてのファイルで定義に互換性がなければなりません。互換性の規則は次のとおりです。

  • Number フィールドと Type フィールドが同じ値を持つ場合、それらのフィールドには互換性があります。--annotation_fields フラグを使用して指定されるアノテーション フィールドも、Description フィールドに同じ値を持つ必要があります。

  • 異なる Type 値を含むフィールドは、次の場合に互換性があります。

    • Integer フィールドと Float フィールドに互換性があり、両方とも Float 型を使用する場合。
    • Variant Transforms ツールを --allow_incompatible_records フラグを指定して実行する場合。こうすることで、互換性のないフィールド（String と Integer など）の間の競合が自動的に解決されます。また、互換性のない型が暗黙的に無視されることがなくなります。

  • Number フィールドの値が異なるフィールドは、次の場合に互換性があります。

    • 次のような互換性のある「繰り返される」数が値に含まれている場合：

      • Number=.（不明な番号）
      • 1 より大きい任意の Number
      • Number=G（遺伝子型ごとに 1 つの値）および Number=R（代替および参照ごとに 1 つの値）
      • Number=A（代替ごとに 1 つの値）。--split_alternate_allele_info_fields を False に設定してツールを実行した場合のみ。

    • Variant Transforms ツールを --allow_incompatible_records フラグを指定して実行する場合。こうすることで、互換性のないフィールド（Number=1 と Number=. など）の間の競合が自動的に解決されます。また、互換性のない型が暗黙的に無視されることがなくなります。

ヘッダー ファイルの指定

Variant Transforms ツールを実行するときに、BigQuery スキーマの生成に使用されるヘッダー ファイルを --representative_header_file フラグを使用して渡すことができます。このファイルは、読み込まれるすべてのファイルのマージされたヘッダーを指定します。

Variant Transforms ツールはファイルからヘッダー情報のみを読み取り、すべての VCF レコードを無視します。つまり、ファイルにヘッダー フィールドのみを含めることも、実際の VCF ファイルにすることもできます。

ヘッダー ファイルを提供する利点は次のとおりです。

  • 特に膨大な数のファイルを読み込む場合は、パイプラインが高速に実行されます。Variant Transforms ツールはヘッダー ファイルを使用して BigQuery スキーマを生成し、複数のファイルにわたってヘッダーをマージするステップをスキップします。これは、すべてのファイルに同じ VCF ヘッダーがある場合に特に便利です。

  • 欠落しているヘッダー フィールドの定義を提供できます。

  • ファイル間で互換性のないフィールド定義を解決できます。

ヘッダーの推測

Variant Transforms ツールを実行するときに、定義のないフィールドがある場合や、フィールド値と互換性のないヘッダー定義をツールで無視したい場合があります。このような場合、これらのフィールドの正しいヘッダー定義をツールに推測させることができます。

--infer_headers フラグを渡すと、ツールは未定義フィールドの TYPE 値と NUMBER 値を推測します。推測は、すべての VCF ファイルのフィールド値に基づきます。

このフラグを渡すと、推測された定義とヘッダーからの定義を含む代表的なヘッダーも出力されます。

互換性のないレコードの許可

Variant Transforms ツールは、次の場合に失敗します。

  • フィールド定義とフィールド値の間に不整合がある場合
  • 1 つのフィールドに、2 つの異なる VCF ファイルからの整合性のない 2 つの定義がある場合

どちらの場合も、--allow_incompatible_records フラグを渡すことができます。これにより、ツールは自動的にヘッダー定義の競合を解決します。このツールは、フィールドの定義とその値に不整合がある場合、BigQuery のスキーマに一致するようにフィールドの値をキャストすることもできます（たとえば、Integer フィールド値が String にキャストされると、String 型のフィールド スキーマと一致します）。

次のステップ