Deep generative models for single-cell omics. Use when you need probabilistic batch correction (scVI), transfer learning, differential expression with uncertainty, or multi-modal integration (TOTALVI, MultiVI). Best for advanced modeling, batch effects, multimodal data. For standard analysis pipelines use scanpy.
SKILL.md
scvi-tools
Overview
scvi-tools is a comprehensive Python framework for probabilistic models in single-cell genomics. Built on PyTorch and PyTorch Lightning, it provides deep generative models using variational inference for analyzing diverse single-cell data modalities. Current stable release: scvi-tools 1.4.3 (May 2026).
Model namespaces matter: core models (scVI, scANVI, totalVI, MultiVI, PeakVI, AUTOZI, CondSCVI, DestVI, LinearSCVI, AmortizedLDA, JaxSCVI) live under scvi.model. Most other models (VeloVI, contrastiveVI, CellAssign, PoissonVI, scBasset, MrVI, MethylVI/MethylANVI, CytoVI, SysVI, Decipher, gimVI, scVIVA, ResolVI, Stereoscope, Solo, totalANVI, DIAGVI) live under scvi.external. The reference files specify the correct namespace per model.
When to Use This Skill
Use this skill when:
Analyzing single-cell RNA-seq data (dimensionality reduction, batch correction, integration)
Working with single-cell ATAC-seq or chromatin accessibility data
Integrating multimodal data (CITE-seq, multiome, paired/unpaired datasets)
Analyzing spatial transcriptomics data (deconvolution, spatial mapping)
Performing differential expression analysis on single-cell data
Conducting cell type annotation or transfer learning tasks
Working with specialized single-cell modalities (methylation, cytometry, RNA velocity)
Building custom probabilistic models for single-cell analysis
Core Capabilities
scvi-tools provides models organized by data modality:
1. Single-Cell RNA-seq Analysis
Core models for expression analysis, batch correction, and integration. See references/models-scrna-seq.md for:
scVI: Unsupervised dimensionality reduction and batch correction
scANVI: Semi-supervised cell type annotation and integration
AUTOZI: Zero-inflation detection and modeling
VeloVI: RNA velocity analysis
contrastiveVI: Perturbation effect isolation
2. Chromatin Accessibility (ATAC-seq)
Models for analyzing single-cell chromatin data. See references/models-atac-seq.md for:
PeakVI: Peak-based ATAC-seq analysis and integration
PoissonVI: Quantitative fragment count modeling
scBasset: Deep learning approach with motif analysis
3. Multimodal & Multi-omics Integration
Joint analysis of multiple data types. See references/models-multimodal.md for:
totalVI: CITE-seq protein and RNA joint modeling
totalANVI: Semi-supervised CITE-seq (totalVI with cell-type labels)
MultiVI: Paired and unpaired multi-omic integration (MuData-based)
MrVI: Multi-resolution cross-sample analysis
DIAGVI: Diagonal integration of unpaired single-cell datasets (added in 1.4.3)
4. Spatial Transcriptomics
Spatially-resolved transcriptomics analysis. See references/models-spatial.md for:
DestVI: Multi-resolution spatial deconvolution
Stereoscope: Cell type deconvolution
Tangram: Spatial mapping and integration
scVIVA: Cell-environment relationship analysis
5. Specialized Modalities
Additional specialized analysis tools. See references/models-specialized.md for:
uv pip install scvi-tools
# For GPU support
uv pip install "scvi-tools[cuda]"
For reproducible environments, pin a version: uv pip install scvi-tools==1.4.3.
Compute backends: training defaults to PyTorch (CPU/GPU/TPU). A JAX backend
(scvi.model.JaxSCVI) and an experimental MLX backend for Apple silicon
(scvi.model.mlxSCVI) are available for select models.
Best Practices
Use raw counts: Always provide unnormalized count data to models
Filter genes: Remove low-count genes before analysis (e.g., min_counts=3)
Register covariates: Include known technical factors (batch, donor, etc.) in setup_anndata
Feature selection: Use highly variable genes for improved performance
Model saving: Always save trained models to avoid retraining
GPU usage: Enable GPU acceleration for large datasets (accelerator="gpu")
Scanpy integration: Store outputs in AnnData objects for downstream analysis
