/scvi-tools-single-cell

name: "scvi-tools-single-cell"
description: "Deep generative models for single-cell omics: probabilistic batch correction (scVI), semi-supervised annotation (scANVI), CITE-seq RNA+protein (totalVI), transfer learning (scARCHES), and DE with uncertainty. Unified setup→train→extract API on AnnData. Use harmony-batch-correction for fast linear correction without deep learning; muon for multi-modal MuData workflows."
license: "BSD-3-Clause"

scvi-tools — Single-Cell Deep Generative Models

Overview

scvi-tools is a probabilistic modeling framework for single-cell genomics built on PyTorch. It implements variational autoencoders (VAEs) that learn low-dimensional latent representations of cells while explicitly modeling batch effects, count noise distributions, and multi-modal data. All models share a unified API: `setup_anndata()` to register data, instantiate the model, `train()`, then extract latent representations, normalized expression, or differential expression results. Models operate on raw count data in AnnData format and return statistically grounded outputs with uncertainty estimates.

When to Use

• Integrating multiple scRNA-seq batches or studies with probabilistic batch correction that preserves biological variation
• Performing differential expression with uncertainty quantification and composite hypotheses (not just fold-change thresholding)
• Annotating cell types via semi-supervised transfer learning from a partially-labeled reference (scANVI)
• Jointly modeling CITE-seq protein and RNA data to obtain denoised protein estimates and joint embeddings (totalVI)
• Adapting a pretrained model to a new query dataset without full retraining (scARCHES transfer learning)
• Deconvolving spatial transcriptomics spots into cell type proportions using a matched scRNA-seq reference (DestVI)
• Detecting doublets in scRNA-seq data as a QC preprocessing step (Solo)
• Use **harmony-batch-correction** instead when you need fast linear batch correction (seconds vs minutes) without deep learning overhead
• For **multi-modal MuData workflows** (joint RNA+ATAC Multiome, combined modality objects), use **muon** instead
• For **standard clustering and visualization** without batch effects or probabilistic DE, use **scanpy-scrna-seq**

Prerequisites

• **Python packages**: `scvi-tools>=1.1`, `scanpy`, `anndata`
• **Data requirements**: AnnData (`.h5ad`) with **raw counts** — not log-normalized. Store counts in `adata.layers["counts"]` if `adata.X` has been normalized.
• **Hardware**: CPU works for <50k cells; GPU (8GB+ VRAM) recommended for larger datasets. Training time: 5–30 minutes on GPU for 100k cells.

pip install scvi-tools scanpy
# GPU acceleration (recommended for >50k cells)
pip install "scvi-tools[cuda12]"   # or scvi-tools[cuda11]

Pre-flight Interview

Settle these with the user before writing any analysis code.

decisions:
  - id: D1
    param: modelChoice
    kind: required
    source: user
    ask: "What should the model do - integrate and denoise unlabelled cells, transfer labels from a reference, or jointly model protein and RNA?"
    default: null

  - id: D2
    param: batchKey
    kind: required
    source: data
    ask: "Which variable separates samples that were processed apart, so the model can hold it out of the latent space?"
    default: null

  - id: D3
    param: rawCountsLayer
    kind: required
    source: data
    ask: "Which layer holds raw integer counts? These models require counts, not normalized values."
    default: null

  - id: D4
    param: latentDimensions
    kind: required
    source: user
    ask: "How many latent dimensions should the cell state be compressed into?"
    default: 10

  - id: D5
    param: geneLikelihood
    kind: optional
    source: data
    ask: "Which count distribution fits this assay - zero-inflated, plain negative binomial, or Poisson?"
    default: "zero-inflated negative binomial"

  - id: D6
    param: trainingSchedule
    kind: optional_conditional
    source: data
    ask: "How long should training run, and should it stop early when validation loss plateaus?"
    default: "400 epochs, no early stopping"

  - id: D7
    param: deEffectSizeThreshold
    kind: optional
    source: user
    ask: "What fold change should the differential expression test treat as the null it must beat?"
    default: 0.25

  - id: D8
    param: networkArchitecture
    kind: never_ask
    source: user
    reason: "Layer count and hidden width are capacity settings whose defaults are validated across datasets; changing them is a methods decision the user has not raised"
    default: "1 layer, 128 hidden units"

D3 is the failure that looks like success: handing log-normalized values to a count model trains it on the wrong noise structure, and it still returns a latent space, a UMAP and a cluster set. D2 decides what the latent space is allowed to forget, so a batch variable confounded with the condition removes the effect being studied.

Quick Start

Minimal scVI batch integration on a built-in example dataset:

import scvi
import scanpy as sc

# Load example data with batch labels
adata = scvi.data.heart_cell_atlas_subsampled()

# Preprocessing: filter genes, select HVGs (subset to save training time)
sc.pp.filter_genes(adata, min_counts=3)
adata.layers["counts"] = adata.X.copy()  # preserve raw counts
sc.pp.normalize_total(adata, target_sum=1e4)
sc.pp.log1p(adata)
sc.pp.highly_variable_genes(adata, n_top_genes=2000, batch_key="cell_source", subset=True)

# Register data, train, extract
scvi.model.SCVI.setup_anndata(adata, layer="counts", batch_key="cell_source")
model = scvi.model.SCVI(adata, n_latent=30)
model.train(max_epochs=200, early_stopping=True)

adata.obsm["X_scVI"] = model.get_latent_representation()
sc.pp.neighbors(adata, use_rep="X_scVI")
sc.tl.umap(adata)
sc.tl.leiden(adata, resolution=0.5)
sc.pl.umap(adata, color=["cell_source", "leiden"])
print(f"Latent shape: {adata.obsm['X_scVI