scvi-tools

Vue d'ensemble

scvi-tools est un framework Python complet pour les modèles probabilistes en génomique unicellulaire. Construit sur PyTorch et PyTorch Lightning, il fournit des modèles génératifs profonds utilisant l'inférence variationnelle pour analyser diverses modalités de données unicellulaires.

Quand utiliser cette compétence

Utilisez cette compétence quand :

Analyser des données de RNA-seq unicellulaire (réduction de dimensionnalité, correction de batch, intégration)
Travailler avec des données ATAC-seq unicellulaire ou d'accessibilité chromatinienne
Intégrer des données multimodales (CITE-seq, multiome, datasets appariés/non appariés)
Analyser des données de transcriptomique spatiale (déconvolution, cartographie spatiale)
Effectuer une analyse d'expression différentielle sur des données unicellulaires
Réaliser des tâches d'annotation de type cellulaire ou de transfer learning
Travailler avec des modalités unicellulaires spécialisées (méthylation, cytométrie, RNA velocity)
Construire des modèles probabilistes personnalisés pour l'analyse unicellulaire

Capacités fondamentales

scvi-tools fournit des modèles organisés par modalité de données :

1. Analyse RNA-seq unicellulaire

Modèles fondamentaux pour l'analyse d'expression, la correction de batch et l'intégration. Voir references/models-scrna-seq.md pour :

scVI : Réduction de dimensionnalité non supervisée et correction de batch
scANVI : Annotation de type cellulaire semi-supervisée et intégration
AUTOZI : Détection et modélisation de l'inflation zéro
VeloVI : Analyse de RNA velocity
contrastiveVI : Isolation d'effets de perturbation

2. Accessibilité chromatinienne (ATAC-seq)

Modèles pour analyser les données chromatiniennes unicellulaires. Voir references/models-atac-seq.md pour :

PeakVI : Analyse et intégration ATAC-seq basées sur les pics
PoissonVI : Modélisation quantitative du décompte de fragments
scBasset : Approche deep learning avec analyse de motifs

3. Intégration multimodale et multi-omiques

Analyse conjointe de plusieurs types de données. Voir references/models-multimodal.md pour :

totalVI : Modélisation conjointe de protéines et RNA CITE-seq
MultiVI : Intégration multi-omique appariée et non appariée
MrVI : Analyse multi-résolution entre échantillons

4. Transcriptomique spatiale

Analyse de transcriptomique spatialement résolue. Voir references/models-spatial.md pour :

DestVI : Déconvolution spatiale multi-résolution
Stereoscope : Déconvolution de type cellulaire
Tangram : Cartographie et intégration spatiales
scVIVA : Analyse de la relation cellule-environnement

5. Modalités spécialisées

Outils d'analyse spécialisés supplémentaires. Voir references/models-specialized.md pour :

MethylVI/MethylANVI : Analyse de méthylation unicellulaire
CytoVI : Correction de batch en cytométrie en flux/masse
Solo : Détection de doublets
CellAssign : Annotation de type cellulaire basée sur des marqueurs

Workflow typique

Tous les modèles scvi-tools suivent un pattern API cohérent :

# 1. Charger et prétraiter les données (format AnnData)
import scvi
import scanpy as sc

adata = scvi.data.heart_cell_atlas_subsampled()
sc.pp.filter_genes(adata, min_counts=3)
sc.pp.highly_variable_genes(adata, n_top_genes=1200)

# 2. Enregistrer les données avec le modèle (spécifier les couches, covariables)
scvi.model.SCVI.setup_anndata(
    adata,
    layer="counts",  # Utiliser les décomptes bruts, pas normalisés en log
    batch_key="batch",
    categorical_covariate_keys=["donor"],
    continuous_covariate_keys=["percent_mito"]
)

# 3. Créer et entraîner le modèle
model = scvi.model.SCVI(adata)
model.train()

# 4. Extraire les représentations latentes et les valeurs normalisées
latent = model.get_latent_representation()
normalized = model.get_normalized_expression(library_size=1e4)

# 5. Stocker dans AnnData pour l'analyse en aval
adata.obsm["X_scVI"] = latent
adata.layers["scvi_normalized"] = normalized

# 6. Analyse en aval avec scanpy
sc.pp.neighbors(adata, use_rep="X_scVI")
sc.tl.umap(adata)
sc.tl.leiden(adata)

Principes de conception clés :

Décomptes bruts requis : Les modèles s'attendent à des données de décompte non normalisées pour des performances optimales
API unifiée : Interface cohérente entre tous les modèles (setup → train → extract)
Centré sur AnnData : Intégration transparente avec l'écosystème scanpy
Accélération GPU : Utilisation automatique des GPUs disponibles
Correction de batch : Gérer la variation technique par l'enregistrement de covariables

Tâches d'analyse courantes

Expression différentielle

Analyse probabiliste DE utilisant les modèles génératifs appris :

de_results = model.differential_expression(
    groupby="cell_type",
    group1="TypeA",
    group2="TypeB",
    mode="change",  # Utiliser le test d'hypothèse composite
    delta=0.25      # Seuil d'effet minimum
)

Voir references/differential-expression.md pour la méthodologie détaillée et l'interprétation.

Persistance du modèle

Sauvegarder et charger les modèles entraînés :

# Sauvegarder le modèle
model.save("./model_directory", overwrite=True)

# Charger le modèle
model = scvi.model.SCVI.load("./model_directory", adata=adata)

Correction de batch et intégration

Intégrer des datasets entre batches ou études :

# Enregistrer les informations de batch
scvi.model.SCVI.setup_anndata(adata, batch_key="study")

# Le modèle apprend automatiquement les représentations corrigées de batch
model = scvi.model.SCVI(adata)
model.train()
latent = model.get_latent_representation()  # Corrigé de batch

Fondations théoriques

scvi-tools est construit sur :

Inférence variationnelle : Distributions postérieures approximées pour l'inférence bayésienne scalable
Modèles génératifs profonds : Architectures VAE qui apprennent des distributions de données complexes
Inférence amortie : Réseaux de neurones partagés pour l'apprentissage efficace entre cellules
Modélisation probabiliste : Quantification d'incertitude principiée et tests statistiques

Voir references/theoretical-foundations.md pour le contexte détaillé du cadre mathématique.

Ressources supplémentaires

Workflows : references/workflows.md contient des workflows courants, les meilleures pratiques, le réglage des hyperparamètres et l'optimisation GPU
Références des modèles : Documentation détaillée pour chaque catégorie de modèle dans le répertoire references/
Documentation officielle : https://docs.scvi-tools.org/en/stable/
Tutoriels : https://docs.scvi-tools.org/en/stable/tutorials/index.html
Référence API : https://docs.scvi-tools.org/en/stable/api/index.html

Installation

uv pip install scvi-tools
# Pour la prise en charge GPU
uv pip install scvi-tools[cuda]

Meilleures pratiques

Utiliser les décomptes bruts : Toujours fournir aux modèles des données de décompte non normalisées
Filtrer les gènes : Supprimer les gènes à faible décompte avant l'analyse (p. ex., min_counts=3)
Enregistrer les covariables : Inclure les facteurs techniques connus (batch, donor, etc.) dans setup_anndata
Sélection de features : Utiliser les gènes hautement variables pour améliorer les performances
Sauvegarde du modèle : Toujours sauvegarder les modèles entraînés pour éviter le réentraînement
Utilisation du GPU : Activer l'accélération GPU pour les datasets volumineux (accelerator="gpu")
Intégration Scanpy : Stocker les résultats dans des objets AnnData pour l'analyse en aval