/scvi-tools

name: scvi-tools
description: Fits probabilistic models for single-cell omics, including scVI batch integration, scANVI annotation, totalVI CITE-seq, MultiVI RNA/ATAC integration, and posterior differential expression. Use for generative modeling, reference mapping, multimodal analysis, or model-based uncertainty; use scanpy for standard preprocessing and exploratory analysis.
license: BSD-3-Clause license
compatibility: Requires Python 3.12+ and scvi-tools with model-specific dependencies. CPU supported; accelerator requirements depend on PyTorch and hardware. Network access is needed for installation or optional dataset/genome downloads, not local model fitting.
metadata:
  version: "1.4"
  skill-author: K-Dense Inc.
  last-reviewed: "2026-10-01"
  upstream-version: "1.5.1"

scvi-tools

Targets **scvi-tools 1.5.1**, released September 10, 2026. APIs below were checked against the tagged source and official documentation. The examples are illustrative: the repository tests exercise short CPU synthetic fits for SCVI, SCANVI, TOTALVI, MULTIVI, METHYLVI, PEAKVI and POISSONVI, plus count-preserving preprocessing, DE output contracts, save/load and minification. The tested stack is Python 3.13, Scanpy 1.12.4, AnnData 0.13.4, MuData 0.4.1, PyTorch 2.14.1 and Lightning 2.6.6. Long training, hardware-specific paths and other specialized workflows remain illustrative; these checks do not establish convergence or biological validity.

Choose the model and its input contract

| Task | Class | Required input | | --- | --- | --- | | RNA integration | `scvi.model.SCVI` | Unnormalized RNA counts | | RNA annotation | `scvi.model.SCANVI` | Counts and partial labels | | CITE-seq | `scvi.model.TOTALVI` | RNA and protein counts, aligned cells | | RNA + ATAC integration | `scvi.model.MULTIVI` | Registered MuData with aligned modality representation | | ATAC accessibility | `scvi.model.PEAKVI` | Cells by peaks, binary/count accessibility | | Quantitative ATAC | `scvi.external.POISSONVI` | Region-level fragment counts | | Methylation | `scvi.external.METHYLVI`, `METHYLANVI` | MuData with methylated and total coverage counts | | Cytometry | `scvi.external.CYTOVI` | Transformed protein intensities | | Large cross-system effects | `scvi.external.SysVI` | Normalized, log-transformed expression | | RNA velocity | `scvi.external.VELOVI` | Preprocessed spliced/unspliced abundances |

The count rule is model-specific: do not feed raw RNA counts to SysVI or replace methylation coverage with ratios. Likewise, never reconstruct counts by exponentiating log-normalized data. Preserve measured counts and preprocessing provenance.

Read the corresponding references before using a specialized model:

• [RNA models](references/models-scrna-seq.md): SCVI, SCANVI, AUTOZI, VELOVI,

ContrastiveVI, CellAssign, SOLO, LinearSCVI, AmortizedLDA.

• [ATAC models](references/models-atac-seq.md): PEAKVI, POISSONVI, SCBASSET.
• [Multimodal models](references/models-multimodal.md): TOTALVI, TOTALANVI,

MULTIVI, MRVI, DIAGVI.

• [Spatial models](references/models-spatial.md): CondSCVI/DestVI, Stereoscope,

Tangram, GIMVI, SCVIVA, RESOLVI.

• [Specialized models](references/models-specialized.md): methylation,

cytometry, SysVI, Decipher.

**Release boundaries:** JAX support, including `JaxSCVI`, was removed in 1.5. `scvi.model.mlxSCVI` remains a separate optional Apple-silicon implementation; PyTorch MPS and MLX are different backends. Spatial models and DIAGVI remain importable in 1.5.1, but upstream directs their ongoing maintenance to [scVIVA-tools](https://scviva-tools.readthedocs.io/en/latest/). Use the pinned compatibility examples here only for existing scvi-tools workflows.

Workflow

1. Confirm modality, raw-data provenance, unique cell/feature IDs, feature order, batch/sample metadata, and the intended biological comparison. 2. Perform QC and feature selection before model registration. Use count-aware HVG selection for count layers, and preserve a full-gene count object for later analyses outside the selected feature set. 3. Register the exact data object with that model's `setup_anndata` or `setup_mudata`; create and train the model. Setup is registration, not normalization. 4. Inspect validation history, held-out fit, seed stability, batch mixing **and** retention of known biology. A well-mixed UMAP alone does not validate integration. 5. Extract representations or model-specific normalized outputs; save the model, data, selected feature order, software versions, seed and training parameters.

Illustrative RNA workflow

Assumes `rna_counts.h5ad` contains measured, unnormalized counts in `.X`, with nonmissing `obs['batch']`. Choose QC thresholds for the experiment before this block.

import numpy as np
import scanpy as sc
import scvi
from scipy import sparse

scvi.settings.seed = 0
adata = sc.read_h5ad("rna_counts.h5ad")
assert adata.obs_names.is_unique and adata.var_names.is_unique
assert adata.obs["batch"].notna().all()
x = adata.X
values = x.data if sparse.issparse(x) else np.asarray(x)
assert np.isfinite(values).all() and (values >= 0).all()
assert np.allclose(values, np.rint(values))
assert (np.asarray(x.sum(axis=1)).ravel() > 0).all()
adata.layers["counts"] = x.copy()
sc.pp.filter_genes(adata, min_cells=3)
sc.pp.highly_variable_genes(
    adata, layer="counts", flavor="seurat_v3", batch_key="batch",
    n_top_genes=min(2000, adata.n_vars), subset=True,
)
adata = adata.copy()
assert (np.asarray(adata.layers["counts"].sum(axis=1)).ravel() > 0).all()
scvi.model.SCVI.setup_anndata(adata, layer="counts", batch_key="batch")
model = scvi.model.SCVI(adata, n_latent=20, gene_likelihood="nb")
model.train(max_epochs=400, 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, flavor="igraph", n_iterations=2, directed=False)
model.save("scvi_model", save_anndata=True)

`seurat_v3` ne