TileDB-VCF
Descripción general
TileDB-VCF es una biblioteca C++ de alto rendimiento con interfaces Python y CLI para el almacenamiento y recuperación eficiente de datos de llamadas de variantes genómicas. Construida sobre la tecnología de arrays dispersos de TileDB, permite la ingesta escalable de archivos VCF/BCF, la adición incremental de muestras sin operaciones de fusión costosas, y consultas paralelas eficientes de datos de variantes almacenados localmente o en la nube.
Cuándo usar esta habilidad
Esta habilidad debe usarse cuando:
- Se aprenden conceptos y flujos de trabajo de TileDB-VCF
- Se prototipan análisis y pipelines genómicos
- Se trabaja con conjuntos de datos pequeños a medianos (< 1000 muestras)
- Se necesita agregar nuevas muestras de forma incremental a conjuntos de datos existentes
- Se requiere consultar eficientemente regiones genómicas específicas en muchas muestras
- Se trabaja con datos de variantes almacenados en la nube (S3, Azure, GCS)
- Se necesitan exportar subconjuntos de grandes conjuntos de datos VCF
- Se construyen bases de datos de variantes para estudios de cohortes
- Proyectos educativos y desarrollo de métodos
- El rendimiento es crítico para las operaciones con datos de variantes
Inicio rápido
Instalación
Método preferido: Conda/Mamba
# Ingrese las siguientes dos líneas si está en una Mac M1
CONDA_SUBDIR=osx-64
conda config --env --set subdir osx-64
# Crear el entorno conda
conda create -n tiledb-vcf "python<3.10"
conda activate tiledb-vcf
# Mamba es una alternativa más rápida y confiable a conda
conda install -c conda-forge mamba
# Instalar TileDB-Py y TileDB-VCF, alineados con otras bibliotecas útiles
mamba install -y -c conda-forge -c bioconda -c tiledb tiledb-py tiledbvcf-py pandas pyarrow numpy
Alternativa: Imágenes Docker
docker pull tiledb/tiledbvcf-py # Interfaz Python
docker pull tiledb/tiledbvcf-cli # Interfaz de línea de comandos
Ejemplos básicos
Crear y poblar un conjunto de datos:
import tiledbvcf
# Crear un nuevo conjunto de datos
ds = tiledbvcf.Dataset(uri="my_dataset", mode="w",
cfg=tiledbvcf.ReadConfig(memory_budget=1024))
# Ingerir archivos VCF (deben ser de una sola muestra con índices)
# Requisitos:
# - Los VCF deben ser de una sola muestra (no multi-muestra)
# - Deben tener índices: .csi (bcftools) o .tbi (tabix)
ds.ingest_samples(["sample1.vcf.gz", "sample2.vcf.gz"])
Consultar datos de variantes:
# Abrir conjunto de datos existente para lectura
ds = tiledbvcf.Dataset(uri="my_dataset", mode="r")
# Consultar regiones y muestras específicas
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())
Exportar a VCF:
import os
# Exportar dos muestras VCF
ds.export(
regions=["chr21:8220186-8405573"],
samples=["HG00101", "HG00097"],
output_format="v",
output_dir=os.path.expanduser("~"),
)
Capacidades principales
1. Creación de conjuntos de datos e ingesta
Cree conjuntos de datos TileDB-VCF e ingrese incrementalmente datos de variantes de múltiples archivos VCF/BCF. Esto es apropiado para construir bases de datos de genómica poblacional y estudios de cohortes.
Requisitos:
- Solo VCF de muestra única: No se admiten VCF multi-muestra
- Archivos de índice necesarios: Los archivos VCF/BCF deben tener índices (.csi o .tbi)
Operaciones comunes:
- Crear nuevos conjuntos de datos con esquemas de array optimizados
- Ingerir archivos VCF/BCF individuales o múltiples en paralelo
- Agregar nuevas muestras de forma incremental sin reprocesar datos existentes
- Configurar el uso de memoria y la configuración de compresión
- Manejar varios formatos VCF y campos INFO/FORMAT
- Reanudar procesos de ingesta interrumpidos
- Validar la integridad de los datos durante la ingesta
2. Consulta y filtrado eficientes
Consulte datos de variantes con alto rendimiento en regiones genómicas, muestras y atributos de variantes. Esto es apropiado para estudios de asociación, descubrimiento de variantes y análisis poblacional.
Operaciones comunes:
- Consultar regiones genómicas específicas (individuales o múltiples)
- Filtrar por nombres de muestra o grupos de muestras
- Extraer atributos específicos de variantes (posición, alelos, genotipos, calidad)
- Acceder a campos INFO y FORMAT de manera eficiente
- Combinar filtrado espacial y basado en atributos
- Transmitir resultados de consultas grandes
- Realizar agregaciones entre muestras o regiones
3. Exportación de datos e interoperabilidad
Exporte datos en varios formatos para análisis posteriores o integración con otras herramientas genómicas. Esto es apropiado para compartir conjuntos de datos, crear subconjuntos de análisis o alimentar otros pipelines.
Operaciones comunes:
- Exportar a formatos VCF/BCF estándar
- Generar archivos TSV con campos seleccionados
- Crear subconjuntos específicos de muestra/región
- Mantener la procedencia de los datos y metadatos
- Exportación sin pérdidas que preserva todas las anotaciones
- Formatos de salida comprimidos
- Exportaciones en streaming para grandes conjuntos de datos
4. Flujos de trabajo de genómica poblacional
TileDB-VCF sobresale en análisis de genómica poblacional a gran escala que requieren acceso eficiente a datos de variantes en muchas muestras y regiones genómicas.
Flujos de trabajo comunes:
- Preparación de datos para estudios de asociación del genoma completo (GWAS)
- Pruebas de carga de variantes raras
- Análisis de estratificación poblacional
- Cálculos de frecuencias alélicas entre poblaciones
- Control de calidad en cohortes grandes
- Anotación y filtrado de variantes
- Análisis comparativo entre poblaciones
Conceptos clave
Esquema del array y modelo de datos
Modelo de datos de TileDB-VCF:
- Las variantes se almacenan como arrays dispersos con coordenadas genómicas como dimensiones
- Las muestras se almacenan como atributos, lo que permite consultas eficientes específicas de muestras
- Los campos INFO y FORMAT se preservan con los tipos de datos originales
- Compresión y fragmentación automáticas para un almacenamiento óptimo
Configuración del esquema:
# Esquema personalizado con extensiones de mosaico específicas
config = tiledbvcf.ReadConfig(
memory_budget=2048, # MB
region_partition=(0, 3095677412), # Genoma completo
sample_partition=(0, 10000) # Hasta 10k muestras
)
Sistemas de coordenadas y regiones
Crítico: TileDB-VCF utiliza coordenadas genómicas basadas en 1 siguiendo el estándar VCF:
- Las posiciones se basan en 1 (la primera base es la posición 1)
- Los rangos son inclusivos en ambos extremos
- La región "chr1:1000-2000" incluye las posiciones 1000-2000 (1001 bases en total)
Formatos de especificación de región:
# Región única
regions = ["chr1:1000000-2000000"]
# Múltiples regiones
regions = ["chr1:1000000-2000000", "chr2:500000-1500000"]
# Cromosoma completo
regions = ["chr1"]
# Estilo BED (basado en 0, semiabierto convertido internamente)
regions = ["chr1:999999-2000000"] # Equivalente a chr1:1000000-2000000 basado en 1
Gestión de memoria
Consideraciones de rendimiento:
- Establezca un presupuesto de memoria adecuado según la memoria del sistema disponible
- Use consultas de streaming para conjuntos de resultados muy grandes
- Particione ingestas grandes para evitar el agotamiento de la memoria
- Configure la caché de mosaicos para acceder repetidamente a regiones
- Use ingesta paralela para múltiples archivos
- Optimice las consultas de región combinando regiones cercanas
Integración con almacenamiento en la nube
TileDB-VCF funciona perfectamente con almacenamiento en la nube:
# Conjunto de datos 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")
Errores comunes
- Agotamiento de memoria durante la ingesta: Use un presupuesto de memoria adecuado y procesamiento por lotes para archivos VCF grandes
- Consultas de región ineficientes: Combine regiones cercanas en lugar de muchas consultas separadas
- Nombres de muestra faltantes: Asegúrese de que los nombres de muestra en los encabezados VCF coincidan con las especificaciones de muestra de la consulta
- Confusión del sistema de coordenadas: Recuerde que TileDB-VCF utiliza coordenadas basadas en 1 como el estándar VCF
- Conjuntos de resultados grandes: Use streaming o paginación para consultas que devuelven millones de variantes
- Permisos en la nube: Asegure la autenticación adecuada para el acceso al almacenamiento en la nube
- Acceso concurrente: Varios escritores en el mismo conjunto de datos pueden causar corrupción: use bloqueo adecuado
Uso de CLI
TileDB-VCF proporciona una interfaz de línea de comandos con los siguientes subcomandos:
Subcomandos disponibles:
create- Crea un conjunto de datos TileDB-VCF vacíostore- Ingiere muestras en un conjunto de datos TileDB-VCFexport- Exporta datos de un conjunto de datos TileDB-VCFlist- Enumera todos los nombres de muestra presentes en un conjunto de datos TileDB-VCFstat- Imprime estadísticas de alto nivel sobre un conjunto de datos TileDB-VCFutils- Utilidades para trabajar con un conjunto de datos TileDB-VCFversion- Imprime la información de la versión y sale
# Crear conjunto de datos vacío
tiledbvcf create --uri my_dataset
# Ingerir muestras (requiere VCF de muestra única con índices)
tiledbvcf store --uri my_dataset --samples sample1.vcf.gz,sample2.vcf.gz
# Exportar datos
tiledbvcf export --uri my_dataset \
--regions "chr1:1000000-2000000" \
--sample-names "sample1,sample2"
# Enumerar todas las muestras
tiledbvcf list --uri my_dataset
# Mostrar estadísticas del conjunto de datos
tiledbvcf stat --uri my_dataset
Funcionalidades avanzadas
Análisis de frecuencia alélica
# Calcular frecuencias alélicas
af_df = tiledbvcf.read_allele_frequency(
uri="my_dataset",
regions=["chr1:1000000-2000000"],
samples=["sample1", "sample2", "sample3"]
)
Control de calidad de muestras
# Realizar QC de muestras
qc_results = tiledbvcf.sample_qc(
uri="my_dataset",
samples=["sample1", "sample2"]
)
Configuraciones personalizadas
# Configuración avanzada
config = tiledbvcf.ReadConfig(
memory_budget=4096,
tiledb_config={
"sm.tile_cache_size": "1000000000",
"vfs.s3.region": "us-east-1"
}
)
Recursos
Obtener ayuda
Recursos de TileDB-VCF de código abierto
Documentación de código abierto:
- TileDB Academy: https://cloud.tiledb.com/academy/
- Guía de Genómica Poblacional: https://cloud.tiledb.com/academy/structure/life-sciences/population-genomics/
- TileDB-VCF GitHub: https://github.com/TileDB-Inc/TileDB-VCF
Recursos de TileDB-Cloud
Para genómica a gran escala/producción:
- Plataforma TileDB-Cloud: https://cloud.tiledb.com
- TileDB Academy (Toda la documentación): https://cloud.tiledb.com/academy/
Primeros pasos:
- Registro de cuenta gratuita: https://cloud.tiledb.com
- Contacto: [email protected] para necesidades empresariales
Escalado a TileDB-Cloud
Cuando sus cargas de trabajo genómicas superan el procesamiento de un solo nodo, TileDB-Cloud proporciona capacidades de nivel empresarial para pipelines de genómica de producción.
Nota: Esta sección cubre las capacidades de TileDB-Cloud basadas en la documentación disponible. Para obtener detalles completos de la API y la funcionalidad actual, consulte la documentación oficial de TileDB-Cloud y la referencia de la API.
Configuración de TileDB-Cloud
1. Crear cuenta y obtener token API
# Regístrese en https://cloud.tiledb.com
# Genere un token API en la configuración de su cuenta
2. Instalar el cliente Python de TileDB-Cloud
# Instalación base
uv pip install tiledb-cloud
# Con funcionalidad específica de genómica
uv pip install tiledb-cloud[life-sciences]
3. Configurar autenticación
# Establezca la variable de entorno con su token API
export TILEDB_REST_TOKEN="su_token_api"
import tiledb.cloud
# La autenticación es automática mediante TILEDB_REST_TOKEN
# No se requiere inicio de sesión explícito en el código
Migración de código abierto a TileDB-Cloud
Ingesta a gran escala
# TileDB-Cloud: Ingesta distribuida de VCF
import tiledb.cloud.vcf
# Use el módulo de ingesta VCF especializado
# Nota: La API exacta requiere la documentación de TileDB-Cloud
# Esto representa la estructura de funcionalidad disponible
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"}
)
Procesamiento distribuido de consultas
# TileDB-Cloud: Consulta VCF en almacenamiento distribuido
import tiledb.cloud.vcf
import tiledbvcf
# Definir el URI del conjunto de datos
dataset_uri = "tiledb://TileDB-Inc/gvcf-1kg-dragen-v376"
# Obtener todas las muestras del conjunto de datos
ds = tiledbvcf.Dataset(dataset_uri, tiledb_config=cfg)
samples = ds.samples()
# Definir atributos y rangos a consultar
attrs = ["sample_name", "fmt_GT", "fmt_AD", "fmt_DP"]
regions = ["chr13:32396898-32397044", "chr13:32398162-32400268"]
# Realizar la lectura, que se ejecuta de forma distribuida
df = tiledb.cloud.vcf.read(
dataset_uri=dataset_uri,
regions=regions,
samples=samples,
attrs=attrs,
namespace="my-namespace", # especifica qué cuenta cobrar
)
df.to_pandas()
Funcionalidades empresariales
Uso compartido de datos y colaboración
# TileDB-Cloud proporciona capacidades empresariales de uso compartido de datos
# a través de permisos basados en espacios de nombres y gestión de grupos
# Acceder a conjuntos de datos compartidos a través de URI de TileDB-Cloud
dataset_uri = "tiledb://shared-namespace/population-study"
# Colaborar a través de cuadernos y recursos informáticos compartidos
# (La API específica requiere la documentación de TileDB-Cloud)
Optimización de costos
- Cómputo sin servidor: Pague solo por el tiempo de cómputo real
- Escalado automático: Escale automáticamente hacia arriba/abajo según la carga de trabajo
- Instancias spot: Use cómputo optimizado en costos para trabajos por lotes
- Niveles de datos: Gestión automática de almacenamiento en caliente/frío
Seguridad y cumplimiento
- Cifrado de extremo a extremo: Datos cifrados en tránsito y en reposo
- Controles de acceso: Permisos detallados y registros de auditoría
- Cumplimiento HIPAA/SOC2: Estándares de seguridad empresarial
- Soporte VPC: Implementación en entornos de nube privados
Lista de verificación para migrar
✅ Migre a TileDB-Cloud si tiene:
- Conjuntos de datos > 1000 muestras
- Necesita procesar > 100GB de datos VCF
- Requiere cómputo distribuido
- Varios miembros del equipo necesitan acceso
- Necesita seguridad/cumplimiento empresarial
- Desea cómputo sin servidor optimizado en costos
- Requiere tiempo de actividad de producción 24/7
Primeros pasos con TileDB-Cloud
- Comience gratis: TileDB-Cloud ofrece un nivel gratuito para evaluación
- Soporte de migración: El equipo de TileDB brinda asistencia para la migración
- Capacitación: Acceso a tutoriales específicos de genómica