alterlab-tiledbvcf

TileDB-VCF

概述

TileDB-VCF 是一个高性能 C++ 库，提供 Python 和 CLI 接口，可高效存储和检索基因组变异调用数据。它基于 TileDB 的稀疏数组技术构建，支持大规模导入 VCF/BCF 文件、增量添加样本而无需执行成本高昂的合并操作，并可高效并行查询本地或云端存储的变异数据。

何时使用此技能

在以下情况下应使用此技能：

• 从大量单样本 VCF/BCF 文件构建可查询的压缩变异存储（适用于过大而无法使用平面 VCF 的队列/群体数据集）
• 向现有存储中增量添加新样本，无需重新合并
• 跨大量样本查询特定基因组区域（按区域/样本分区读取）
• 将区域/样本子集导出回 VCF/BCF，供下游工具使用
• 在云存储（S3、Azure、GCS）或 TileDB Cloud 上处理变异数据
• 为可扩展的基因组变异工作流进行原型设计或教学

不适用场景

场景	改用
在 Python 中读取、筛选或遍历少量 VCF/BAM 文件（pysam/htslib）	alterlab-pysam
从头生成 VCF 文件（FASTQ -> 比对 -> 变异调用）	alterlab-nf-core-sarek
对特定变异进行临床解读或查询群体频率	alterlab-clinvar / alterlab-gnomad
为非变异数据（图像、张量、矩阵）提供通用分块数组存储	alterlab-zarr
对导出表格执行超内存数据框分析	alterlab-polars / alterlab-dask

快速入门

安装

首选方法：从 tiledb channel 使用 conda/mamba。 tiledbvcf-py 不在 PyPI、conda-forge 或 bioconda 上提供，而是从 tiledb Anaconda channel 发布，并提供原生 osx-arm64 构建（Apple Silicon 上无需使用 Rosetta/CONDA_SUBDIR 变通方案）。当前版本为 0.40.3（2026 年 4 月），面向 Python 3.9–3.12 提供 linux-64、osx-64 和 osx-arm64 构建。没有 3.13 版本的构建，因此创建环境时请固定解释器版本；默认的 conda create 若解析到较新的 Python，会报告软件包不可用，而不会说明原因。

# Native Apple Silicon (osx-arm64) — also works on osx-64 / linux-64
conda create -n tiledb-vcf -c conda-forge -c tiledb \
  python=3.12 tiledbvcf-py=0.40 pandas pyarrow numpy
conda activate tiledb-vcf

替代方案：Docker 镜像（可拉取 CLI/Python 接口；最新标签跟踪当前版本）

docker pull tiledb/tiledbvcf-py     # Python interface
docker pull tiledb/tiledbvcf-cli    # Command-line interface

基本示例

创建并填充数据集：

import tiledbvcf

# Create a new dataset
ds = tiledbvcf.Dataset(uri="my_dataset", mode="w",
                      cfg=tiledbvcf.ReadConfig(memory_budget_mb=1024))

# Ingest VCF files (must be single-sample with indexes)
# Requirements:
# - VCFs must be single-sample (not multi-sample)
# - Must have indexes: .csi (bcftools) or .tbi (tabix)
ds.ingest_samples(["sample1.vcf.gz", "sample2.vcf.gz"])

查询变异数据：

# Open existing dataset for reading
ds = tiledbvcf.Dataset(uri="my_dataset", mode="r")

# Query specific regions and samples
df = ds.read(
    attrs=["sample_name", "pos_start", "pos_end", "alleles", "fmt_GT"],
    regions=["chr1:1000000-2000000", "chr2:500000-1500000"],
    samples=["sample1", "sample2", "sample3"]
)
print(df.head())

导出为 VCF：

import os

# Export two VCF samples
ds.export(
    regions=["chr21:8220186-8405573"],
    samples=["HG00101", "HG00097"],
    output_format="v",
    output_dir=os.path.expanduser("~"),
)

核心功能

1. 数据集创建与导入

创建 TileDB-VCF 数据集，并从多个 VCF/BCF 文件中增量导入变异数据。适用于构建群体基因组学数据库和队列研究数据集。

要求：

• 仅支持单样本 VCF：不支持多样本 VCF
• 必须提供索引文件：VCF/BCF 文件必须有索引（.csi 或 .tbi）

常见操作：

• 使用经过优化的数组架构创建新数据集
• 并行导入单个或多个 VCF/BCF 文件
• 增量添加新样本，无需重新处理已有数据
• 配置内存用量和压缩设置
• 处理各种 VCF 格式以及 INFO/FORMAT 字段
• 恢复中断的导入流程
• 在导入过程中验证数据完整性

2. 高效查询与筛选

跨基因组区域、样本和变异属性高性能查询变异数据。适用于关联研究、变异发现和群体分析。

常见操作：

• 查询特定基因组区域（单个或多个）
• 按样本名称或样本组筛选
• 提取特定变异属性（位置、等位基因、基因型、质量）
• 高效访问 INFO 和 FORMAT 字段
• 结合空间筛选与基于属性的筛选
• 流式处理大型查询结果
• 跨样本或区域执行聚合

3. 数据导出与互操作性

以各种格式导出数据，供下游分析或与其他基因组学工具集成。适用于共享数据集、创建分析子集或为其他流水线提供数据。

常见操作：

• 导出为标准 VCF/BCF 格式
• 使用所选字段生成 TSV 文件
• 创建特定样本或区域的子集
• 保留数据来源和元数据
• 无损导出数据，保留所有注释
• 压缩输出格式
• 对大型数据集进行流式导出

4. 群体基因组学工作流

TileDB-VCF 擅长大规模群体基因组学分析，可高效访问多个样本和基因组区域中的变异数据。

常见工作流：

• 准备全基因组关联研究（GWAS）数据
• 稀有变异负荷检验
• 群体分层分析
• 计算不同群体中的等位基因频率
• 对大型队列进行质量控制
• 变异注释和筛选
• 跨群体比较分析

核心概念

数组架构与数据模型

TileDB-VCF 数据模型：

• 将变异存储为稀疏数组，并以基因组坐标作为维度
• 将样本存储为属性，以便高效执行特定样本查询
• 保留 INFO 和 FORMAT 字段及其原始数据类型
• 自动压缩和分块，以实现最佳存储效果

架构配置：

# Partition a large read across region/sample space
config = tiledbvcf.ReadConfig(
    memory_budget_mb=2048,        # memory budget in MB
    region_partition=(0, 10),     # (partition_index, num_partitions) over regions
    sample_partition=(0, 4),      # (partition_index, num_partitions) over samples
)

坐标系统与区域

重要： TileDB-VCF 遵循 VCF 标准，使用 从 1 开始的基因组坐标：

• 位置从 1 开始（第一个碱基的位置为 1）
• 范围的起点和终点均包含在内
• 区域 "chr1:1000-2000" 包含位置 1000-2000（共 1001 个碱基）

区域指定格式：

# Single region
regions = ["chr1:1000000-2000000"]

# Multiple regions
regions = ["chr1:1000000-2000000", "chr2:500000-1500000"]

# Whole chromosome
regions = ["chr1"]

注意： regions= 字符串始终采用从 1 开始且包含终点的坐标——起点 <= 0 会引发 "Regions must be 1-based" 错误。不会隐式转换为 BED 风格。若要使用从 0 开始、左闭右开的 BED 区间，请通过 read(bed_file="regions.bed", ...) 传入 BED 文件，而不要使用 regions= 列表。

内存管理

性能注意事项：

1. 根据可用系统内存设置合适的内存预算
2. 对非常大的结果集使用流式查询
3. 分批导入大型数据，以避免内存耗尽
4. 配置磁贴缓存，以便重复访问区域
5. 对多个文件使用并行导入
6. 合并相邻区域，以优化区域查询

云存储集成

TileDB-VCF 可无缝使用云存储：

# S3 dataset
ds = tiledbvcf.Dataset(uri="s3://bucket/dataset", mode="r")

# Azure Blob Storage
ds = tiledbvcf.Dataset(uri="azure://container/dataset", mode="r")

# Google Cloud Storage
ds = tiledbvcf.Dataset(uri="gcs://bucket/dataset", mode="r")

常见问题

1. 导入期间内存耗尽： 对大型 VCF 文件使用合适的内存预算和批处理
2. 区域查询效率低下： 合并相邻区域，而不是进行许多次单独查询
3. 缺少样本名称： 确保 VCF 标头中的样本名称与查询指定的样本一致
4. 混淆坐标系统： 请记住，TileDB-VCF 与 VCF 标准一样使用从 1 开始的坐标
5. 结果集过大： 对返回数百万个变异的查询使用流式处理或分页
6. 云权限： 确保已正确进行身份验证，以访问云存储
7. 并发访问： 多个写入者同时访问同一数据集可能导致损坏——请使用适当的锁定机制

CLI 用法

TileDB-VCF 提供包含以下子命令的命令行界面：

可用子命令：

• create - 创建空的 TileDB-VCF 数据集
• store - 将样本导入 TileDB-VCF 数据集
• export - 从 TileDB-VCF 数据集导出数据
• list - 列出 TileDB-VCF 数据集中存在的所有样本名称
• stat - 输出 TileDB-VCF 数据集的高级统计信息
• utils - 用于处理 TileDB-VCF 数据集的实用工具
• version - 输出版本信息并退出

# Create empty dataset
tiledbvcf create --uri my_dataset

# Ingest samples (requires single-sample VCFs with indexes)
tiledbvcf store --uri my_dataset --samples sample1.vcf.gz,sample2.vcf.gz

# Export data
tiledbvcf export --uri my_dataset \
  --regions "chr1:1000000-2000000" \
  --sample-names "sample1,sample2"

# List all samples
tiledbvcf list --uri my_dataset

# Show dataset statistics
tiledbvcf stat --uri my_dataset

高级功能

以下是 Dataset 对象上的方法（以 mode="r" 打开），而非顶层 tiledbvcf 函数。不存在 read_allele_frequency 或 sample_qc 函数——请使用以下方法。

等位基因计数 / 频率

ds = tiledbvcf.Dataset(uri="my_dataset", mode="r")

# Internal allele-count (AC) array, returned as a pandas DataFrame
ac_df = ds.read_allele_count(region="chr1:1000000-2000000")

# Apply an allele-frequency filter at read time on a normal read()
df = ds.read(
    attrs=["sample_name", "pos_start", "alleles", "fmt_GT"],
    regions=["chr1:1000000-2000000"],
    set_af_filter="<0.01",  # keep variants with AF below threshold
)

变异统计（QC）

# Internal variant-stats array (per-variant aggregate stats) as a DataFrame
stats_df = ds.read_variant_stats(region="chr1:1000000-2000000")

注意：read_allele_count 和 read_variant_stats 要求数据集在摄取时启用了相应的内部数组（近期版本默认启用）。

TileDB 配置透传

# Pass raw TileDB Embedded config keys (e.g. cloud creds, cache sizing)
config = tiledbvcf.ReadConfig(
    memory_budget_mb=4096,
    tiledb_config={
        "sm.tile_cache_size": "1000000000",
        "vfs.s3.region": "us-east-1",
    },
)

资源

• TileDB-VCF GitHub（源代码、问题、发布版本）：https://github.com/TileDB-Inc/TileDB-VCF
• Population Genomics Guide（Academy）：https://cloud.tiledb.com/academy/structure/life-sciences/population-genomics/
• Python API 参考：https://tiledb-inc.github.io/TileDB-VCF/documentation/reference/Dataset.html
• TileDB Cloud（托管式、分布式）：https://cloud.tiledb.com

扩展至 TileDB-Cloud

当工作负载超出单节点处理能力时（大致而言：样本数超过 1000、VCF 超过 100 GB，或需要分布式计算 / 共享访问），可通过 tiledb-cloud-py 在 TileDB Cloud 上摄取和查询相同的数据集。本地 tiledbvcf API 保持不变；云端软件包则增加了分布式编排功能。

设置

pip install "tiledb-cloud[life-sciences]"   # cloud client with genomics extras
export TILEDB_REST_TOKEN="your_api_token"   # auth is automatic from this env var

分布式摄取和读取。 云端的 VCF 入口位于 tiledb.cloud.vcf：

• tiledb.cloud.vcf.ingest(...) — 将数据分布式摄取至 tiledb://namespace/dataset URI
• tiledb.cloud.vcf.build_read_dag(...) — 构建针对区域 / 样本的分布式读取 DAG

不同版本间的确切签名和资源参数会有所变化，因此请查阅当前的 Cloud API 参考，而不要将其硬编码：https://cloud.tiledb.com/academy/structure/life-sciences/population-genomics/api-reference/cloud/

托管在云端的数据集仍可通过常规的 tiledbvcf.Dataset API 打开，传入 tiledb:// URI 和包含凭据的 tiledb_config 即可：

import tiledbvcf

cfg = {"rest.token": "your_api_token"}  # or rely on TILEDB_REST_TOKEN
ds = tiledbvcf.Dataset("tiledb://TileDB-Inc/gvcf-1kg-dragen-v376",
                       mode="r", tiledb_config=cfg)
df = ds.read(
    attrs=["sample_name", "fmt_GT", "fmt_AD", "fmt_DP"],
    regions=["chr13:32396898-32397044", "chr13:32398162-32400268"],
    samples=ds.samples(),
)