Skip to content
Research Agent Skillsby Kalaris Labs
Install
Life Sciencesv1.2AdaptedBSD-3-Clause license

scvi-tools

Trains and applies scvi-tools probabilistic deep generative models (scVI, scANVI, totalVI, MultiVI, PeakVI, DestVI, Solo, CellAssign, MrVI and others) on AnnData or MuData single-cell data using PyTorch. Covers batch correction, integration, cell type annotation, probabilistic differential expression, and scRNA-seq, ATAC-seq, CITE-seq, spatial and methylation data. Use when integrating batches or datasets with scVI, annotating cells with scANVI, jointly modeling RNA and protein or ATAC, deconvolving spatial spots, or testing differential expression with uncertainty. For standard preprocessing and clustering pipelines, use scanpy instead.

Install this skill

Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and 70+ other harnesses.

skills.sh CLI (Recommended)
npx skills add KalarisLabs/research-agent-skills --skill scvi-tools
uvx (Python tool runner)
uvx research-agent-skills install scvi-tools

Documentation & Instructions

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:

  • MethylVI/MethylANVI: Single-cell methylation analysis
  • CytoVI: Flow/mass cytometry batch correction
  • Solo: Doublet detection
  • CellAssign: Marker-based cell type annotation

Typical Workflow

All scvi-tools models follow a consistent API pattern:

# 1. Load and preprocess data (AnnData format)
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. Register data with model (specify layers, covariates)
scvi.model.SCVI.setup_anndata(
    adata,
    layer="counts",  # Use raw counts, not log-normalized
    batch_key="batch",
    categorical_covariate_keys=["donor"],
    continuous_covariate_keys=["percent_mito"]
)

# 3. Create and train model
model = scvi.model.SCVI(adata)
model.train()

# 4. Extract latent representations and normalized values
latent = model.get_latent_representation()
normalized = model.get_normalized_expression(library_size=1e4)

# 5. Store in AnnData for downstream analysis
adata.obsm["X_scVI"] = latent
adata.layers["scvi_normalized"] = normalized

# 6. Downstream analysis with scanpy
sc.pp.neighbors(adata, use_rep="X_scVI")
sc.tl.umap(adata)
sc.tl.leiden(adata)

Key Design Principles:

  • Raw counts required: Models expect unnormalized count data for optimal performance
  • Unified API: Consistent interface across all models (setup → train → extract)
  • AnnData-centric: Seamless integration with the scanpy ecosystem
  • GPU acceleration: Automatic utilization of available GPUs
  • Batch correction: Handle technical variation through covariate registration

Common Analysis Tasks

Differential Expression

Probabilistic DE analysis using the learned generative models:

de_results = model.differential_expression(
    groupby="cell_type",
    group1="TypeA",
    group2="TypeB",
    mode="change",  # Use composite hypothesis testing
    delta=0.25      # Minimum effect size threshold
)

See references/differential-expression.md for detailed methodology and interpretation.

Model Persistence

Save and load trained models:

# Save model
model.save("./model_directory", overwrite=True)

# Load model
model = scvi.model.SCVI.load("./model_directory", adata=adata)

Batch Correction and Integration

Integrate datasets across batches or studies:

# Register batch information
scvi.model.SCVI.setup_anndata(adata, batch_key="study")

# Model automatically learns batch-corrected representations
model = scvi.model.SCVI(adata)
model.train()
latent = model.get_latent_representation()  # Batch-corrected

Theoretical Foundations

scvi-tools is built on:

  • Variational inference: Approximate posterior distributions for scalable Bayesian inference
  • Deep generative models: VAE architectures that learn complex data distributions
  • Amortized inference: Shared neural networks for efficient learning across cells
  • Probabilistic modeling: Principled uncertainty quantification and statistical testing

See references/theoretical-foundations.md for detailed background on the mathematical framework.

Additional Resources

Installation

Requires Python 3.12+ (scvi-tools 1.4 dropped older versions).

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

  1. Use raw counts: Always provide unnormalized count data to models
  2. Filter genes: Remove low-count genes before analysis (e.g., min_counts=3)
  3. Register covariates: Include known technical factors (batch, donor, etc.) in setup_anndata
  4. Feature selection: Use highly variable genes for improved performance
  5. Model saving: Always save trained models to avoid retraining
  6. GPU usage: Enable GPU acceleration for large datasets (accelerator="gpu")
  7. Scanpy integration: Store outputs in AnnData objects for downstream analysis

Agent operating procedure

  1. Check the environment. Confirm tool versions, the reference genome/annotation build and the input formats (FASTQ, BAM, VCF, h5ad).
  2. Pin down the inputs. Confirm formats, identifiers and parameters from the data or the user. Ask rather than guess any value that changes the result.
  3. Run a small version first. Run the pipeline on a small subset (one sample, one chromosome, a few thousand cells) first.
  4. Execute the full task using the instructions and references above.
  5. Validate the result. Check QC metrics, sample identities, genome build consistency and batch effects before interpreting results.
  6. Report. State what was run (versions, commands, parameters), what was checked, and what is still uncertain.
If this happens Do this
Genome builds or identifiers do not match between inputs Stop and harmonize (liftover, ID mapping) before continuing.
A function, flag or endpoint in these instructions is missing in the installed version Check the installed version's own documentation (help(), --help, official docs), adapt, and tell the user. Never invent an API.
A required input, identifier or parameter is ambiguous Ask the user, or state the assumption explicitly before running.

Integrity rules

  • Never fabricate results, parameters, identifiers, citations or statistics. If something cannot be run or verified, say so plainly.
  • Do not interpret biological significance beyond what the statistics support; report multiple-testing correction.
  • Treat version-specific details here as possibly outdated: confirm them against the official documentation for the installed version.
  • Ask before actions that cost money, consume shared GPUs or cloud quota, touch personal or patient data, or cannot be undone.

Related skills

  • scanpy: Standard single-cell RNA-seq analysis pipeline.
  • anndata: Data structure for annotated matrices in single-cell analysis.
  • cellxgene-census: Query the CZ CELLxGENE Census programmatically for versioned public single-cell and spatial transcriptomics data.

Trigger Prompts & Evaluation Corpus

These evaluation prompts test that the agent correctly selects scvi-tools for relevant tasks and leaves it out for near misses.

Should trigger (3)

  • should trigger

    “How do I fix batch effects across 4 donors using scVI?”

    expects Gives the scVI workflow: keep raw counts (e.g. in a layer), select HVGs, call SCVI.setup_anndata with batch_key='donor', train, then take get_latent_representation for neighbors/UMAP. Notes that raw counts are required and that integration should be validated (e.g. batch mixing against bio conservation).

  • should trigger

    “I have pbmc_cite.h5mu with RNA and a 'protein_expression' layer from 3 10x CITE-seq lanes. I ran TOTALVI.setup_mudata and then model.train() and got a NaN loss after a few epochs. The protein counts include some isotype controls. What should I check, and how do I get a joint latent space and denoised protein values afterward?”

    expects Uses totalVI (scvi.model.TOTALVI) with MuData setup. Suggests debugging steps: confirm raw integer counts in both modalities, filter genes/proteins, set batch_key, and try a lower learning rate or smaller batch/early stopping. Then explains get_latent_representation and get_normalized_expression with protein output. Doesn't invent API details and says to check the installed version's docs.

  • should trigger

    “I have a reference scRNA-seq atlas with cell type labels and a new unlabeled query dataset from a different lab. I want to transfer the labels onto the query cells and get a confidence for each assignment, without retraining everything from scratch if possible.”

    expects Recommends a semi-supervised label-transfer approach: scANVI built from a pretrained scVI reference, with query mapping via load_query_data and fine-tuning (scArches). Uses labels_key and unlabeled_category, predicts labels and probabilities with soft=True, and notes checking low-confidence cells and gene overlap between reference and query.

Near misses (2)

  • near miss

    “I have an h5ad of 20k cells. Please normalize, log-transform, find the top 2000 HVGs, run PCA, build a neighbor graph, cluster with Leiden, and make a UMAP colored by cluster.”

    expects Should use the scanpy skill for the standard preprocessing and clustering pipeline. It should not train a deep generative model such as scVI.

  • near miss

    “I have bulk RNA-seq counts from 6 treated and 6 control mouse liver samples. Run differential expression with a design formula and BH-adjusted p-values.”

    expects Should use PyDESeq2 for bulk count differential expression with a design formula and Benjamini-Hochberg correction. It should not use scvi-tools, which is for single-cell data.