TileDB-VCF
概览
TileDB-VCF 是一个高性能 C++ 库，提供 Python 和 CLI 接口，用于高效存储和检索基因组变异调用数据。它构建在 TileDB 的稀疏数组技术之上，能够可扩展地导入 VCF/BCF 文件，无需昂贵的合并操作即可增量添加样本，并能够高效并行查询存储在本地或云端的变异数据。
何时使用此技能
以下情况应使用此技能：
- 学习 TileDB-VCF 概念和工作流程
- 构建基因组学分析原型和管线
- 处理中小型数据集（< 1000 个样本）
- 需要向现有数据集增量添加新样本
- 需要跨多个样本高效查询特定基因组区域
- 处理云端存储的变异数据（S3、Azure、GCS）
- 需要导出大型 VCF 数据集的子集
- 构建群体研究的变异数据库
- 教育项目和方法开发
- 追求变异数据操作的高性能
快速开始
安装
推荐方法：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))
# 导入 VCF 文件（必须是带索引的单样本文件）
# 要求：
# - VCF 文件必须是单样本（非多样本）
# - 必须有索引：.csi (bcftools) 或 .tbi (tabix)
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
# 导出两个 VCF 样本
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 字段保留原始数据类型
- 自动压缩和分块以实现最佳存储
模式配置：
# 具有特定图块范围的自定义模式
config = tiledbvcf.ReadConfig(
memory_budget=2048, # MB
region_partition=(0, 3095677412), # 完整基因组
sample_partition=(0, 10000) # 最多 1 万个样本
)
坐标系统和区域
关键： TileDB-VCF 使用遵循 VCF 标准的 1-based 基因组坐标：
- 位置是 1-based（第一个碱基是位置 1）
- 范围两端都包含
- 区域 "chr1:1000-2000" 包括位置 1000-2000（共 1001 个碱基）
区域指定格式：
# 单个区域
regions = ["chr1:1000000-2000000"]
# 多个区域
regions = ["chr1:1000000-2000000", "chr2:500000-1500000"]
# 整个染色体
regions = ["chr1"]
# BED 样式（内部转换 0-based 半开区间）
regions = ["chr1:999999-2000000"] # 等价于 1-based 的 chr1:1000000-2000000
内存管理
性能考虑：
- 根据可用的系统内存设置合适的内存预算
- 对于非常大的结果集，使用流式查询
- 将大型导入分区以避免内存耗尽
- 为重复的区域访问配置图块缓存
- 使用并行导入处理多个文件
- 通过合并附近的区域来优化区域查询
云存储集成
TileDB-VCF 无缝支持云存储：
# S3 数据集
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")
常见陷阱
- 导入期间内存耗尽： 对大型 VCF 文件使用合适的内存预算和批处理
- 低效的区域查询： 合并邻近区域，而不是进行多次单独查询
- 缺少样本名称： 确保 VCF 头部中的样本名称与查询样本匹配
- 坐标系统混淆： 记住 TileDB-VCF 使用与 VCF 标准相同的 1-based 坐标
- 大型结果集： 对返回数百万变异的查询使用流式或分页
- 云权限： 确保对云存储访问进行正确认证
- 并发访问： 多个写入者同时写入同一数据集可能导致损坏——使用适当的锁定机制
CLI 用法
TileDB-VCF 提供命令行界面，包含以下子命令：
可用子命令：
create- 创建一个空的 TileDB-VCF 数据集store- 将样本导入 TileDB-VCF 数据集export- 从 TileDB-VCF 数据集导出数据list- 列出 TileDB-VCF 数据集中存在的所有样本名称stat- 打印 TileDB-VCF 数据集的高级统计信息utils- 用于处理 TileDB-VCF 数据集的工具version- 打印版本信息并退出
# 创建空数据集
tiledbvcf create --uri my_dataset
# 导入样本（需要带索引的单样本 VCF）
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
高级功能
等位基因频率分析
# 计算等位基因频率
af_df = tiledbvcf.read_allele_frequency(
uri="my_dataset",
regions=["chr1:1000000-2000000"],
samples=["sample1", "sample2", "sample3"]
)
样本质量控制
# 执行样本质量控制
qc_results = tiledbvcf.sample_qc(
uri="my_dataset",
samples=["sample1", "sample2"]
)
自定义配置
# 高级配置
config = tiledbvcf.ReadConfig(
memory_budget=4096,
tiledb_config={
"sm.tile_cache_size": "1000000000",
"vfs.s3.region": "us-east-1"
}
)
资源
获取帮助
开源 TileDB-VCF 资源
开源文档：
- TileDB 学院：https://cloud.tiledb.com/academy/
- 群体基因组学指南：https://cloud.tiledb.com/academy/structure/life-sciences/population-genomics/
- TileDB-VCF GitHub：https://github.com/TileDB-Inc/TileDB-VCF
TileDB-Cloud 资源
针对大规模/生产级基因组学：
- TileDB-Cloud 平台：https://cloud.tiledb.com
- TileDB 学院（所有文档）：https://cloud.tiledb.com/academy/
入门指南：
- 免费账号注册：https://cloud.tiledb.com
- 企业需求请联系：[email protected]
扩展至 TileDB-Cloud
当您的基因组学工作负载超出单节点处理能力时，TileDB-Cloud 为生产级基因组学管线提供企业级功能。
注意：本节根据可用文档介绍 TileDB-Cloud 的功能。有关完整的 API 细节和当前功能，请查阅官方 TileDB-Cloud 文档和 API 参考。
设置 TileDB-Cloud
1. 创建账户并获取 API 令牌
# 在 https://cloud.tiledb.com 注册
# 在账户设置中生成 API 令牌
2. 安装 TileDB-Cloud Python 客户端
# 基础安装
uv pip install tiledb-cloud
# 安装基因组学特定功能
uv pip install tiledb-cloud[life-sciences]
3. 配置认证
# 设置包含您的 API 令牌的环境变量
export TILEDB_REST_TOKEN="your_api_token"
import tiledb.cloud
# 通过 TILEDB_REST_TOKEN 自动认证
# 代码中无需显式登录
从开源迁移到 TileDB-Cloud
大规模导入
# TileDB-Cloud：分布式 VCF 导入
import tiledb.cloud.vcf
# 使用专门的 VCF 导入模块
# 注意：确切 API 需要查阅 TileDB-Cloud 文档
# 以下表示可用的功能结构
tiledb.cloud.vcf.ingestion.ingest_vcf_dataset(
source="s3://my-bucket/vcf-files/",
output="tiledb://my-namespace/large-dataset",
namespace="my-namespace",
acn="my-s3-credentials",
ingest_resources={"cpu": "16", "memory": "64Gi"}
)
分布式查询处理
# TileDB-Cloud：跨分布式存储的 VCF 查询
import tiledb.cloud.vcf
import tiledbvcf
# 定义数据集 URI
dataset_uri = "tiledb://TileDB-Inc/gvcf-1kg-dragen-v376"
# 从数据集获取所有样本
ds = tiledbvcf.Dataset(dataset_uri, tiledb_config=cfg)
samples = ds.samples()
# 定义要查询的属性及范围
attrs = ["sample_name", "fmt_GT", "fmt_AD", "fmt_DP"]
regions = ["chr13:32396898-32397044", "chr13:32398162-32400268"]
# 执行读取，通过分布式方式完成
df = tiledb.cloud.vcf.read(
dataset_uri=dataset_uri,
regions=regions,
samples=samples,
attrs=attrs,
namespace="my-namespace", # 指定扣费的账户
)
df.to_pandas()
企业功能
数据共享与协作
# TileDB-Cloud 通过基于命名空间的权限和组管理提供企业级数据共享功能
# 通过 TileDB-Cloud URI 访问共享数据集
dataset_uri = "tiledb://shared-namespace/population-study"
# 通过共享笔记本和计算资源进行协作
# （具体 API 需要查阅 TileDB-Cloud 文档）
成本优化
- 无服务器计算：仅按实际计算时间付费
- 自动伸缩：根据工作负载自动伸缩
- 竞价实例：为批处理作业使用成本优化的计算
- 数据分层：自动管理冷/热存储
安全与合规
- 端到端加密：传输和静态数据加密
- 访问控制：细粒度权限和审计日志
- HIPAA/SOC2 合规：企业安全标准
- VPC 支持：在私有云环境中部署
何时迁移检查清单
✅ 如果您有以下情况，请迁移到 TileDB-Cloud：
- 数据集 > 1000 个样本
- 需要处理 > 100GB 的 VCF 数据
- 需要分布式计算
- 多个团队成员需要访问
- 需要企业级安全/合规
- 希望获得成本优化的无服务器计算
- 需要 24/7 生产级正常运行
TileDB-Cloud 入门
- 免费开始：TileDB-Cloud 提供免费层级用于评估
- 迁移支持：TileDB 团队提供迁移协助
- 培训：获取基因组学特定教程