tiledbvcf

用途

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

主要能力

数据集创建与导入：创建 TileDB-VCF 数据集，并从多个 VCF/BCF 文件增量导入变异数据。要求 VCF 为单样本（不支持多样本 VCF），且必须带有索引文件（.csi 或 .tbi）。支持并行导入、增量添加新样本、配置内存与压缩设置、处理各类 VCF 格式及 INFO/FORMAT 字段、恢复中断的导入过程、在导入时校验数据完整性。
高效查询与过滤：跨基因组区域、样本和变异属性进行高性能查询。支持查询单个或多个基因组区域、按样本名或样本组过滤、提取特定变异属性（位置、等位基因、基因型、质量）、高效访问 INFO 与 FORMAT 字段、结合空间与属性过滤、流式返回大型查询结果、跨样本或区域聚合。
数据导出与互操作：导出为标准 VCF/BCF 格式或包含选定字段的 TSV 文件，创建样本/区域特定子集，保留数据来源与元数据，无损导出保留全部注释，支持压缩输出格式与大型数据集的流式导出。
群体基因组学工作流：适用于需要跨多样本和基因组区域高效访问变异数据的大规模分析，包括全基因组关联研究（GWAS）数据准备、罕见变异负荷检验、群体分层分析、跨群体等位基因频率计算、大队列质量控制、变异注释与过滤、跨群体比较分析。

使用方式

安装（推荐 Conda/Mamba）：

# M1 Mac 需先执行以下两行
CONDA_SUBDIR=osx-64
conda config --env --set subdir osx-64

# 创建 conda 环境
conda create -n tiledb-vcf "python<3.10"
conda activate tiledb-vcf

# Mamba 是更快更可靠的 conda 替代品
conda install -c conda-forge mamba

# 安装 TileDB-Py 与 TileDB-VCF
mamba install -y -c conda-forge -c bioconda -c tiledb tiledb-py tiledbvcf-py pandas pyarrow numpy

Docker 镜像：

docker pull tiledb/tiledbvcf-py     # Python 接口
docker pull tiledb/tiledbvcf-cli    # 命令行接口

创建并填充数据集：

import tiledbvcf

ds = tiledbvcf.Dataset(uri="my_dataset", mode="w",
                      cfg=tiledbvcf.ReadConfig(memory_budget=1024))
ds.ingest_samples(["sample1.vcf.gz", "sample2.vcf.gz"])

查询变异数据：

ds = tiledbvcf.Dataset(uri="my_dataset", mode="r")
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
ds.export(
    regions=["chr21:8220186-8405573"],
    samples=["HG00101", "HG00097"],
    output_format="v",
    output_dir=os.path.expanduser("~"),
)

CLI 子命令：create（创建空数据集）、store（导入样本）、export（导出数据）、list（列出样本名）、stat（打印统计信息）、utils（工具）、version（版本信息）。

tiledbvcf create --uri my_dataset
tiledbvcf store --uri my_dataset --samples sample1.vcf.gz,sample2.vcf.gz
tiledbvcf export --uri my_dataset --regions "chr1:1000000-2000000" --sample-names "sample1,sample2"
tiledbvcf list --uri my_dataset
tiledbvcf stat --uri my_dataset

云端存储：

ds = tiledbvcf.Dataset(uri="s3://bucket/dataset", mode="r")
ds = tiledbvcf.Dataset(uri="azure://container/dataset", mode="r")
ds = tiledbvcf.Dataset(uri="gcs://bucket/dataset", mode="r")

关键概念

数据模型：变异以稀疏数组存储，基因组坐标作为维度；样本作为属性存储，支持高效的样本特定查询；INFO 与 FORMAT 字段保留原始数据类型；自动压缩与分块以优化存储。

坐标系：TileDB-VCF 使用基于 1 的基因组坐标（遵循 VCF 标准），区间两端均为闭区间。区域 "chr1:1000-2000" 包含位置 1000 至 2000（共 1001 个碱基）。

内存管理：根据可用系统内存设置合适的内存预算；对超大结果集使用流式查询；对大型导入进行分区以避免内存耗尽；为重复区域访问配置 tile 缓存；对多个文件使用并行导入；通过合并邻近区域优化区域查询。

适用场景

学习 TileDB-VCF 概念与工作流
基因组学分析与流水线原型开发
中小规模数据集（少于 1000 个样本）
需要向已有数据集增量添加新样本
需要跨多样本高效查询特定基因组区域
处理云端存储的变异数据（S3、Azure、GCS）
需要导出大型 VCF 数据集的子集
构建队列研究的变异数据库
教学项目与方法开发
变异数据操作对性能要求较高时

限制与注意事项

仅支持单样本 VCF，不支持多样本 VCF。
VCF/BCF 文件必须带有索引（.csi 或 .tbi）。
导入时可能内存耗尽：需使用合适的内存预算和批处理。
区域查询效率：应合并邻近区域，而非执行大量独立查询。
样本名缺失：需确保 VCF 头部中的样本名与查询指定的样本一致。
坐标系混淆：需记住 TileDB-VCF 使用基于 1 的坐标。
大型结果集：对返回数百万变异的查询应使用流式或分页。
云端权限：需确保云存储访问的正确认证。
并发访问：多个写入者访问同一数据集可能导致损坏，需使用适当的锁定。

技能介绍

用途