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

本页面介绍了如何使用 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 文件之间共享的 INFOFORMAT 字段合并。此步骤假定,在使用同一个密钥的多个文件中定义的字段是兼容的。

  2. 所有 VCF 文件的记录都会加载到同一个表中。在相关列中,任何缺失的字段都会被设置为 null

您还可以采取第三步来合并样本。如需了解详情,请参阅变体合并

加载 VCF 文件时,其字段定义和值必须一致,否则该工具会出现故障。该工具可能会尝试修复这些不一致情况,但前提是已进行了这样的设置。如需了解详情,请参阅处理格式错误的文件

将数据附加到现有 BigQuery 表

通过在运行 Variant Transforms 工具时添加 --append 标志,您可以将数据附加到现有 BigQuery 表。

为了在附加数据时获得最佳结果,用于附加数据的架构应与现有表中的架构相同。如果附加数据的架构包含与现有表中的列同名的列,则两个列必须具有相同的名称、数据类型和模式。否则,Variant Transforms 工具将返回错误。

除了 --append 标志之外,您还可以通过添加 --update_schema_on_append 标志来附加具有与现有表不同架构的数据。来自附加数据的任何新列都将添加到现有架构中,现有架构在新列中的行值将被设置为 NULL。同样的,如果现有架构具有附加数据没有的列,则附加数据在该列中的行值也将为 NULL。

处理格式错误的文件

处理格式错误或不兼容的文件有多种方案。 在加载 VCF 文件前,您可以使用 VCF 文件预处理器工具检查格式错误和不兼容的文件。

处理字段不兼容

加载多个 VCF 文件时,Variant Transforms 工具会合并所有 INFOHEADER 字段以生成一个“代表性标头”。此代表性标头用于创建 BigQuery 架构。如果多个文件都定义了相同的密钥,其定义必须在所有文件中都是兼容的。 兼容性规则即:

  • 如果各个字段在其 NumberType 字段中都具有相同的值,则它们是兼容的。使用 --annotation_fields 标志指定的注释字段在其 Description 字段中也一定具有相同的值。
  • 在以下情况下,包含不同 Type 值的字段是兼容的:

    • 如果 IntegerFloat 字段兼容,并且两者都使用 Float 类型。
    • 如果您使用 --allow_incompatible_records 标志(可自动解决 StringInteger 等不兼容字段之间的冲突)运行 Variant Transforms 工具。这可确保不兼容的类型不会遭到静默忽略。
  • 在以下情况下,在 Number 字段中具有不同值的字段是兼容的:

    • 如果值包含彼此兼容的“重复”数字,例如:

      • Number=.(未知数字)
      • 大于 1 的任何 Number
      • Number=G(每个基因型一个值)和 Number=R(每个替换物和参考的一个值)
      • Number=A(每个替换物的一个值),不过前提是通过设置为 False--split_alternate_allele_info_fields 运行该工具。
    • 如果您使用 --allow_incompatible_records 标志(可自动解决 Number=1Number=. 等不兼容字段之间的冲突)运行 Variant Transforms 工具。这可确保不兼容的类型不会遭到静默忽略。

指定标头文件

运行 Variant Transforms 工具时,您可以通过用于生成 BigQuery 架构的标头文件传递 --representative_header_file 标志。该文件指定来自所有加载文件的合并标头。

Variant Transforms 工具仅读取文件的标头信息,并且会忽略所有 VCF 记录。这意味着该文件可能仅包含标头字段,也可能是一个真正的 VCF 文件。

提供标头文件具有以下好处:

  • 流水线运行速度更快,特别是您在加载大量文件时。Variant Transforms 工具使用标头文件生成 BigQuery 架构,并且跳过跨文件合并标头的步骤。如果所有文件都有相同的 VCF 标头,这将特别有用。

  • 您可以为任何缺失的标头字段提供定义。

  • 您可以解决跨文件字段定义的不兼容问题。

推断标头

运行 Variant Transforms 工具时,您可能拥有没有定义的字段,或者您可能想要该工具忽略与字段值不兼容的标头定义。在这种情况下,您可能想要该工具推断这些字段的正确标头定义。

您可以传递 --infer_headers 标志,接着该工具将为未定义字段推断 TYPENUMBER 值。它会根据所有 VCF 文件中的字段值进行推断。

传递此标志还会输出包含推断定义和标头中定义的代表性标头。

允许不兼容的记录

在下面两种情况下,Variant Transforms 工具会出现故障:

  • 如果字段定义与字段值之间存在不一致情况
  • 如果字段在两个不同的 VCF 文件中有两个不一致的定义

在这两种情况下,您都可以传递 --allow_incompatible_records 标志。这会使该工具自动解决标头定义中的冲突。如果字段的定义与其值之间存在不一致情况,则该工具还会转换字段值来匹配 BigQuery 架构(例如,Integer 字段值将转换为 String 以匹配 String 类型的字段架构)。

后续步骤