このページでは、大規模な分析を行うために、Variant Transforms ツールを使用して VCF ファイルを変換し、BigQuery に直接読み込む方法について説明します。
多数のファイルを読み込む場合、パフォーマンスの向上とコストの削減に関する推奨事項について大量入力の処理をご覧ください。
VCF ファイルを BigQuery に読み込んで変換する
始める前に
ツールを実行するには、次の条件を満たしている必要があります。
Google Cloud プロジェクト(課金が有効であること)と Cloud Life Sciences、Compute Engine、Cloud Storage、Dataflow API が有効化されていること。
BigQuery データセットと Cloud Storage バケットがすでにあること。
既存の VCF ファイル、または VCF ファイルが格納された GZIP または BZIP ファイルが Cloud Storage バケットに存在すること。手持ちの VCF ファイルがない場合は、一般公開データセットを使用してください。
ツールの実行
このツールを実行するには、必要なバイナリと依存関係がすべてインストール済みである Docker イメージを使用します。
Docker イメージを使用してこのツールを実行する手順は次のとおりです。
最新バージョンの Variant Transforms を入手するには、次のコマンドを使用します。
docker pull gcr.io/cloud-lifesciences/gcp-variant-transforms
次のテキストをコピーして、
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 内の任意のディレクトリにできます。次のコマンドを実行して、
script.sh
を実行可能にします。chmod +x script.sh
script.sh
を実行します。./script.sh
さまざまな要因、たとえばデータのサイズにより、ジョブ完了までの時間は異なります。数分で済むこともあれば、1 時間以上かかる場合もあります。
このツールは Dataflow を使用するため、Dataflow Console に移動するとジョブの詳細情報を見ることができます。たとえば、処理されたレコードの数や、ワーカーの数、詳細なエラーログを確認できます。
ジョブが完了した後で、次のコマンドを実行してデータセット内のすべてのテーブルのリストを取得します。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 ツールで複数のファイルを読み込むと、次の操作が実行されます。
--input_pattern
フラグのリストにある、一致するすべての VCF ファイルのデータからなるマージされた BigQuery スキーマが作成されます。たとえば、VCF ファイル間で共有されるINFO
フィールドとFORMAT
フィールドがマージされます。このステップでは、同じキーを持つ複数のファイルで定義されたフィールドに互換性があることを想定しています。すべての 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
型のフィールド スキーマと一致します)。
次のステップ
- Variant Transforms プリプロセッサ ツールを実行して VCF ファイルを検証する方法を学習します。
- BigQuery でのバリアントの分析を読んで、読み込んだデータを分析します。
- BigQuery バリアント スキーマについて学習します。
Operations
リソースとgcloud alpha genomics operations describe
コマンドから返される情報については、API ドキュメントをご覧ください。- 並列複合アップロードを使用して、大きなローカル ファイルを複数並列でアップロードする方法を学習します。