本页面介绍了如何使用 Variant Transforms 工具来转换 VCF 文件并将其直接加载到 BigQuery 中进行大规模分析。
如果您要加载大量文件,请参阅处理大型输入来获取有关提高性能和降低成本的建议。
转换 VCF 文件,并将其加载到 BigQuery
准备工作
要运行该工具,您需要:
一个启用了结算功能以及 Cloud Life Sciences、Compute Engine、Cloud Storage 和 Dataflow API 的 Google Cloud 项目。
一个现有的 BigQuery 数据集和一个 Cloud Storage 存储分区。
一个现有的 VCF 文件或者一个包含 Cloud Storage 存储分区中的 VCF 文件的 GZIP 或 BZIP 文件。 如果您没有 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 文件的位置时,可以指定单个文件,也可以使用通配符 (
*
) 一次加载多个文件。可接受的文件格式包括 GZIP、BZIP 和 VCF。如需了解详情,请参阅加载多个文件。请记住,该工具运行压缩文件时速度较慢,因为压缩文件是不可以拆分的。如果您要跨文件合并样本,请参阅变体合并。
请注意,
TEMP_LOCATION
目录用于存储运行该工具所需的临时文件。它可以是 Cloud Storage 中您具有写入权限的任何目录。运行以下命令来使
script.sh
可执行:chmod +x script.sh
运行
script.sh
:./script.sh
完成作业所需的时间因数据大小等多个因素而异,从几分钟到一小时或更长时间不等。
由于此工具使用 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
标志指定要将哪些 VCF 文件加载到 BigQuery 中。例如,要加载 my-bucket
Cloud Storage 存储分区中的所有 VCF 文件,请将该标志设置为以下格式:
--input_pattern=gs://my-bucket/*.vcf
使用 Variant Transforms 工具加载多个文件时,会发生以下操作:
会创建合并的 BigQuery 架构,来包含
--input_pattern
标志中列出的所有相匹配的 VCF 文件中的数据。例如,各个 VCF 文件之间共享的INFO
和FORMAT
字段合并。此步骤假定,在使用同一个密钥的多个文件中定义的字段是兼容的。所有 VCF 文件的记录都会加载到同一个表中。在相关列中,任何缺失的字段都会被设置为
null
。
您还可以采取第三步来合并样本。如需了解详情,请参阅变体合并。
加载 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
类型。 - 如果您使用
--allow_incompatible_records
标志(可自动解决String
和Integer
等不兼容字段之间的冲突)运行 Variant Transforms 工具。这可确保不兼容的类型不会遭到静默忽略。
- 如果
在以下情况下,在
Number
字段中具有不同值的字段是兼容的:如果值包含彼此兼容的“重复”数字,例如:
Number=.
(未知数字)- 大于 1 的任何
Number
Number=G
(每个基因型一个值)和Number=R
(每个替换物和参考的一个值)Number=A
(每个替换物的一个值),不过前提是通过设置为False
的--split_alternate_allele_info_fields
运行该工具。
如果您使用
--allow_incompatible_records
标志(可自动解决Number=1
和Number=.
等不兼容字段之间的冲突)运行 Variant Transforms 工具。这可确保不兼容的类型不会遭到静默忽略。
指定标头文件
运行 Variant Transforms 工具时,您可以通过用于生成 BigQuery 架构的标头文件传递 --representative_header_file
标志。该文件指定来自所有加载文件的合并标头。
Variant Transforms 工具仅读取文件的标头信息,并且会忽略所有 VCF 记录。这意味着该文件可能仅包含标头字段,也可能是一个真正的 VCF 文件。
提供标头文件具有以下好处:
流水线运行速度更快,特别是您在加载大量文件时。Variant Transforms 工具使用标头文件生成 BigQuery 架构,并且跳过跨文件合并标头的步骤。如果所有文件都有相同的 VCF 标头,这将特别有用。
您可以为任何缺失的标头字段提供定义。
您可以解决跨文件字段定义的不兼容问题。
推断标头
运行 Variant Transforms 工具时,您可能拥有没有定义的字段,或者您可能想要该工具忽略与字段值不兼容的标头定义。在这种情况下,您可能想要该工具推断这些字段的正确标头定义。
您可以传递 --infer_headers
标志,接着该工具将为未定义字段推断 TYPE
和 NUMBER
值。它会根据所有 VCF 文件中的字段值进行推断。
传递此标志还会输出包含推断定义和标头中定义的代表性标头。
允许不兼容的记录
在下面两种情况下,Variant Transforms 工具会出现故障:
- 如果字段定义与字段值之间存在不一致情况
- 如果字段在两个不同的 VCF 文件中有两个不一致的定义
在这两种情况下,您都可以传递 --allow_incompatible_records
标志。这会使该工具自动解决标头定义中的冲突。如果字段的定义与其值之间存在不一致情况,则该工具还会转换字段值来匹配 BigQuery 架构(例如,Integer
字段值将转换为 String
以匹配 String
类型的字段架构)。
后续步骤
- 了解如何运行 Variant Transforms 预处理器工具来验证 VCF 文件。
- 阅读使用 BigQuery 分析变体来分析您加载的数据。
- 了解 BigQuery 变体架构。
- 了解如何使用并行复合上传来并行上传大型本地文件。