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

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: SCVI, SCANVI, AUTOZI, VELOVI, ContrastiveVI, CellAssign, SOLO, LinearSCVI, AmortizedLDA.
• ATAC models: PEAKVI, POISSONVI, SCBASSET.
• Multimodal models: TOTALVI, TOTALANVI, MULTIVI, MRVI, DIAGVI.
• Spatial models: CondSCVI/DestVI, Stereoscope, Tangram, GIMVI, SCVIVA, RESOLVI.
• Specialized models: 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. 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()

…