TileDB-VCF
Vue d'ensemble
TileDB-VCF est une bibliothèque C++ haute performance avec des interfaces Python et en ligne de commande pour le stockage et la récupération efficaces de données d'appel de variants génomiques. Bâtie sur la technologie de tableaux creux de TileDB, elle permet l'ingestion évolutive de fichiers VCF/BCF, l'ajout incrémental d'échantillons sans opérations de fusion coûteuses, et des requêtes parallèles efficaces sur des données de variants stockées localement ou dans le cloud.
Quand utiliser cette compétence
Cette compétence doit être utilisée lorsque :
- Vous apprenez les concepts et workflows de TileDB-VCF
- Vous prototypiez des analyses et pipelines génomiques
- Vous travaillez avec des ensembles de données de taille petite à moyenne (< 1000 échantillons)
- Vous avez besoin d'ajouter incrémentalement de nouveaux échantillons à des ensembles de données existants
- Vous avez besoin d'interroger efficacement des régions génomiques spécifiques sur de nombreux échantillons
- Vous travaillez avec des données de variants stockées dans le cloud (S3, Azure, GCS)
- Vous avez besoin d'exporter des sous-ensembles de grands ensembles de données VCF
- Vous construisez des bases de données de variants pour des études de cohorte
- Vous menez des projets éducatifs et du développement de méthodes
- La performance est critique pour les opérations sur les données de variants
Démarrage rapide
Installation
Méthode préférée : Conda/Mamba
# Entrez les deux lignes suivantes si vous êtes sur un Mac M1
CONDA_SUBDIR=osx-64
conda config --env --set subdir osx-64
# Créez l'environnement conda
conda create -n tiledb-vcf "python<3.10"
conda activate tiledb-vcf
# Mamba est une alternative plus rapide et plus fiable à conda
conda install -c conda-forge mamba
# Installez TileDB-Py et TileDB-VCF, en alignement avec d'autres bibliothèques utiles
mamba install -y -c conda-forge -c bioconda -c tiledb tiledb-py tiledbvcf-py pandas pyarrow numpy
Alternative : Images Docker
docker pull tiledb/tiledbvcf-py # Interface Python
docker pull tiledb/tiledbvcf-cli # Interface en ligne de commande
Exemples de base
Créer et remplir un ensemble de données :
import tiledbvcf
# Créez un nouvel ensemble de données
ds = tiledbvcf.Dataset(uri="my_dataset", mode="w",
cfg=tiledbvcf.ReadConfig(memory_budget=1024))
# Ingérez des fichiers VCF (doivent être mono-échantillon avec index)
# Exigences :
# - Les VCF doivent être mono-échantillon (pas multi-échantillons)
# - Doivent avoir des index : .csi (bcftools) ou .tbi (tabix)
ds.ingest_samples(["sample1.vcf.gz", "sample2.vcf.gz"])
Interroger les données de variants :
# Ouvrez un ensemble de données existant en lecture
ds = tiledbvcf.Dataset(uri="my_dataset", mode="r")
# Interrogez des régions et échantillons spécifiques
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())
Exporter vers VCF :
import os
# Exportez deux échantillons VCF
ds.export(
regions=["chr21:8220186-8405573"],
samples=["HG00101", "HG00097"],
output_format="v",
output_dir=os.path.expanduser("~"),
)
Fonctionnalités principales
1. Création et ingestion d'ensembles de données
Créez des ensembles de données TileDB-VCF et ingérez incrémentalement des données de variants à partir de plusieurs fichiers VCF/BCF. Cela est approprié pour la construction de bases de données de génomique des populations et d'études de cohorte.
Exigences :
- VCF mono-échantillon uniquement : Les VCF multi-échantillons ne sont pas pris en charge
- Fichiers d'index requis : Les fichiers VCF/BCF doivent avoir des index (.csi ou .tbi)
Opérations courantes :
- Créez de nouveaux ensembles de données avec des schémas de tableaux optimisés
- Ingérez un ou plusieurs fichiers VCF/BCF en parallèle
- Ajoutez de nouveaux échantillons de manière incrémentielle sans retraiter les données existantes
- Configurez l'utilisation de la mémoire et les paramètres de compression
- Gérez divers formats VCF et champs INFO/FORMAT
- Reprenez les processus d'ingestion interrompus
- Validez l'intégrité des données pendant l'ingestion
2. Interrogation et filtrage efficaces
Interrogez les données de variants avec des performances élevées sur les régions génomiques, les échantillons et les attributs de variants. Cela est approprié pour les études d'association, la découverte de variants et l'analyse de populations.
Opérations courantes :
- Interrogez des régions génomiques spécifiques (une ou plusieurs)
- Filtrez par noms d'échantillons ou groupes d'échantillons
- Extrayez des attributs spécifiques de variants (position, allèles, génotypes, qualité)
- Accédez efficacement aux champs INFO et FORMAT
- Combinez le filtrage spatial et basé sur les attributs
- Diffusez de grands résultats de requêtes
- Effectuez des agrégations sur les échantillons ou les régions
3. Exportation et interopérabilité des données
Exportez les données dans divers formats pour une analyse en aval ou une intégration avec d'autres outils génomiques. Cela est approprié pour le partage d'ensembles de données, la création de sous-ensembles d'analyse ou l'alimentation d'autres pipelines.
Opérations courantes :
- Exportez aux formats VCF/BCF standard
- Générez des fichiers TSV avec des champs sélectionnés
- Créez des sous-ensembles spécifiques aux échantillons/régions
- Maintenez la provenance et les métadonnées des données
- Export sans perte préservant toutes les annotations
- Formats de sortie compressés
- Export en continu pour les grands ensembles de données
4. Workflows de génomique des populations
TileDB-VCF excelle dans les analyses de génomique des populations à grande échelle nécessitant un accès efficace aux données de variants sur de nombreux échantillons et régions génomiques.
Workflows courants :
- Préparation de données pour les études d'association pangénomiques (GWAS)
- Tests de charge de variants rares
- Analyse de stratification des populations
- Calculs de fréquences alléliques entre populations
- Contrôle qualité sur de grandes cohortes
- Annotation et filtrage de variants
- Analyse comparative entre populations
Concepts clés
Schéma de tableau et modèle de données
Modèle de données TileDB-VCF :
- Les variants sont stockés sous forme de tableaux creux avec les coordonnées génomiques comme dimensions
- Les échantillons sont stockés comme attributs permettant des requêtes efficaces spécifiques aux échantillons
- Les champs INFO et FORMAT sont préservés avec les types de données d'origine
- Compression et partitionnement automatiques pour un stockage optimal
Configuration du schéma :
# Schéma personnalisé avec des étendues de tuiles spécifiques
config = tiledbvcf.ReadConfig(
memory_budget=2048, # Mo
region_partition=(0, 3095677412), # Génome complet
sample_partition=(0, 10000) # Jusqu'à 10 000 échantillons
)
Systèmes de coordonnées et régions
Critique : TileDB-VCF utilise des coordonnées génomiques en base 1 selon la norme VCF :
- Les positions sont en base 1 (la première base est la position 1)
- Les plages sont inclusives aux deux extrémités
- La région "chr1:1000-2000" inclut les positions 1000 à 2000 (1001 bases au total)
Formats de spécification de région :
# Région unique
regions = ["chr1:1000000-2000000"]
# Régions multiples
regions = ["chr1:1000000-2000000", "chr2:500000-1500000"]
# Chromosome entier
regions = ["chr1"]
# Style BED (base 0, demi-ouvert converti en interne)
regions = ["chr1:999999-2000000"] # Équivalent à la base 1 chr1:1000000-2000000
Gestion de la mémoire
Considérations sur les performances :
- Définissez un budget mémoire approprié en fonction de la mémoire système disponible
- Utilisez des requêtes en continu pour de très grands ensembles de résultats
- Partitionnez les grandes ingestions pour éviter l'épuisement de la mémoire
- Configurez le cache de tuiles pour un accès répété aux régions
- Utilisez l'ingestion parallèle pour plusieurs fichiers
- Optimisez les requêtes de région en combinant les régions proches
Intégration du stockage cloud
TileDB-VCF fonctionne de manière transparente avec le stockage cloud :
# Ensemble de données 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")
Pièges courants
- Épuisement de la mémoire pendant l'ingestion : Utilisez un budget mémoire approprié et un traitement par lots pour les grands fichiers VCF
- Requêtes de région inefficaces : Combinez les régions proches au lieu de nombreuses requêtes séparées
- Noms d'échantillons manquants : Assurez-vous que les noms d'échantillons dans les en-têtes VCF correspondent aux spécifications de la requête
- Confusion du système de coordonnées : N'oubliez pas que TileDB-VCF utilise des coordonnées en base 1 comme la norme VCF
- Grands ensembles de résultats : Utilisez la diffusion en continu ou la pagination pour les requêtes renvoyant des millions de variants
- Permissions cloud : Assurez une authentification appropriée pour l'accès au stockage cloud
- Accès concurrent : Plusieurs scripteurs sur le même ensemble de données peuvent provoquer une corruption — utilisez un verrouillage approprié
Utilisation en ligne de commande
TileDB-VCF fournit une interface en ligne de commande avec les sous-commandes suivantes :
Sous-commandes disponibles :
create- Crée un ensemble de données TileDB-VCF videstore- Ingère des échantillons dans un ensemble de données TileDB-VCFexport- Exporte des données à partir d'un ensemble de données TileDB-VCFlist- Liste tous les noms d'échantillons présents dans un ensemble de données TileDB-VCFstat- Affiche des statistiques de haut niveau sur un ensemble de données TileDB-VCFutils- Utilitaires pour travailler avec un ensemble de données TileDB-VCFversion- Affiche les informations de version et quitte
# Créez un ensemble de données vide
tiledbvcf create --uri my_dataset
# Ingérez des échantillons (nécessite des VCF mono-échantillon avec index)
tiledbvcf store --uri my_dataset --samples sample1.vcf.gz,sample2.vcf.gz
# Exportez les données
tiledbvcf export --uri my_dataset \
--regions "chr1:1000000-2000000" \
--sample-names "sample1,sample2"
# Listez tous les échantillons
tiledbvcf list --uri my_dataset
# Affichez les statistiques de l'ensemble de données
tiledbvcf stat --uri my_dataset
Fonctionnalités avancées
Analyse de fréquence allélique
# Calculez les fréquences alléliques
af_df = tiledbvcf.read_allele_frequency(
uri="my_dataset",
regions=["chr1:1000000-2000000"],
samples=["sample1", "sample2", "sample3"]
)
Contrôle qualité des échantillons
# Effectuez un contrôle qualité des échantillons
qc_results = tiledbvcf.sample_qc(
uri="my_dataset",
samples=["sample1", "sample2"]
)
Configurations personnalisées
# Configuration avancée
config = tiledbvcf.ReadConfig(
memory_budget=4096,
tiledb_config={
"sm.tile_cache_size": "1000000000",
"vfs.s3.region": "us-east-1"
}
)
Ressources
Obtenir de l'aide
Ressources open source TileDB-VCF
Documentation open source :
- TileDB Academy : https://cloud.tiledb.com/academy/
- Guide de génomique des populations : https://cloud.tiledb.com/academy/structure/life-sciences/population-genomics/
- TileDB-VCF GitHub : https://github.com/TileDB-Inc/TileDB-VCF
Ressources TileDB-Cloud
Pour la génomique à grande échelle/production :
- Plateforme TileDB-Cloud : https://cloud.tiledb.com
- TileDB Academy (toute la documentation) : https://cloud.tiledb.com/academy/
Pour commencer :
- Inscription gratuite : https://cloud.tiledb.com
- Contact : [email protected] pour les besoins d'entreprise
Passage à l'échelle avec TileDB-Cloud
Lorsque vos charges de travail génomiques dépassent le traitement sur un seul nœud, TileDB-Cloud fournit des capacités de niveau entreprise pour les pipelines de génomique en production.
Remarque : Cette section couvre les capacités de TileDB-Cloud sur la base de la documentation disponible. Pour les détails complets de l'API et les fonctionnalités actuelles, consultez la documentation officielle de TileDB-Cloud et la référence de l'API.
Configuration de TileDB-Cloud
1. Créez un compte et obtenez un jeton API
# Inscrivez-vous sur https://cloud.tiledb.com
# Générez un jeton API dans les paramètres de votre compte
2. Installez le client Python TileDB-Cloud
# Installation de base
uv pip install tiledb-cloud
# Avec des fonctionnalités spécifiques à la génomique
uv pip install tiledb-cloud[life-sciences]
3. Configurez l'authentification
# Définissez la variable d'environnement avec votre jeton API
export TILEDB_REST_TOKEN="votre_jeton_api"
import tiledb.cloud
# L'authentification est automatique via TILEDB_REST_TOKEN
# Aucune connexion explicite requise dans le code
Migration de l'open source vers TileDB-Cloud
Ingestion à grande échelle
# TileDB-Cloud : Ingestion VCF distribuée
import tiledb.cloud.vcf
# Utilisez le module d'ingestion VCF spécialisé
# Remarque : L'API exacte nécessite la documentation TileDB-Cloud
# Ceci représente la structure des fonctionnalités disponibles
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"}
)
Traitement distribué des requêtes
# TileDB-Cloud : Interrogation VCF sur stockage distribué
import tiledb.cloud.vcf
import tiledbvcf
# Définissez l'URI de l'ensemble de données
dataset_uri = "tiledb://TileDB-Inc/gvcf-1kg-dragen-v376"
# Obtenez tous les échantillons de l'ensemble de données
ds = tiledbvcf.Dataset(dataset_uri, tiledb_config=cfg)
samples = ds.samples()
# Définissez les attributs et les plages à interroger
attrs = ["sample_name", "fmt_GT", "fmt_AD", "fmt_DP"]
regions = ["chr13:32396898-32397044", "chr13:32398162-32400268"]
# Effectuez la lecture, qui est exécutée de manière distribuée
df = tiledb.cloud.vcf.read(
dataset_uri=dataset_uri,
regions=regions,
samples=samples,
attrs=attrs,
namespace="my-namespace", # spécifie le compte à facturer
)
df.to_pandas()
Fonctionnalités d'entreprise
Partage de données et collaboration
# TileDB-Cloud fournit des capacités de partage de données d'entreprise
# via des permissions basées sur les espaces de noms et la gestion de groupes
# Accédez aux ensembles de données partagés via les URI TileDB-Cloud
dataset_uri = "tiledb://shared-namespace/population-study"
# Collaborez via des notebooks et des ressources de calcul partagés
# (L'API spécifique nécessite la documentation TileDB-Cloud)
Optimisation des coûts
- Calcul sans serveur : Payez uniquement pour le temps de calcul réel
- Mise à l'échelle automatique : Montez/descendez automatiquement en fonction de la charge de travail
- Instances spot : Utilisez du calcul optimisé en coûts pour les tâches batch
- Hiérarchisation des données : Gestion automatique du stockage chaud/froid
Sécurité et conformité
- Chiffrement de bout en bout : Données chiffrées en transit et au repos
- Contrôles d'accès : Permissions granulaires et journaux d'audit
- Conformité HIPAA/SOC2 : Normes de sécurité d'entreprise
- Support VPC : Déploiement dans des environnements cloud privés
Quand migrer - Liste de contrôle
✅ Migrez vers TileDB-Cloud si vous avez :
- Des ensembles de données > 1000 échantillons
- Besoin de traiter > 100 Go de données VCF
- Besoin de calcul distribué
- Plusieurs membres de l'équipe ayant besoin d'accès
- Besoin de sécurité/conformité d'entreprise
- Souhaitez un calcul sans serveur optimisé en coûts
- Nécessitez une disponibilité de production 24h/24 et 7j/7
Pour commencer avec TileDB-Cloud
- Commencez gratuitement : TileDB-Cloud propose un niveau gratuit pour l'évaluation
- Support de migration : L'équipe TileDB fournit une assistance à la migration
- Formation : Accès à des tutoriels spécifiques à la génomique
…
[tronqué pour la traduction]