存储和加载基因组变异片段

本页面介绍了如何使用 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 文件的位置时，可以指定单个文件，也可以使用通配符 (*) 一次加载多个文件。可接受的文件格式包括 GZIP、BZIP 和 VCF。如需了解详情，请参阅加载多个文件。

    请记住，该工具运行压缩文件时速度较慢，因为压缩文件是不可以拆分的。如果您要跨文件合并样本，请参阅变体合并。

    请注意，TEMP_LOCATION 目录用于存储运行该工具所需的临时文件。它可以是 Cloud Storage 中您具有写入权限的任何目录。

  3. 运行以下命令来使 script.sh 可执行：

    chmod +x script.sh

  4. 运行 script.sh：

    ./script.sh

  5. 完成作业所需的时间因数据大小等多个因素而异，从几分钟到一小时或更长时间不等。

    由于此工具使用 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 标志指定要将哪些 VCF 文件加载到 BigQuery 中。例如，要加载 my-bucket Cloud Storage 存储分区中的所有 VCF 文件，请将该标志设置为以下格式：

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

使用 Variant Transforms 工具加载多个文件时，会发生以下操作：

  1. 会创建合并的 BigQuery 架构，来包含 --input_pattern 标志中列出的所有相匹配的 VCF 文件中的数据。例如，各个 VCF 文件之间共享的 INFO 和 FORMAT 字段合并。此步骤假定，在使用同一个密钥的多个文件中定义的字段是兼容的。

  2. 所有 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 类型的字段架构）。

后续步骤