---

name: scvi-tools description: "Use scvi-tools for probabilistic single-cell omics analysis with AnnData/MuData setup, model selection, training, downstream analysis, save/load, Hub workflows, and advanced extension/autotune tasks." disable-model-invocation: true metadata: disco-role: operating license: BSD 3-Clause

scvi-tools

Use this skill when working with scvi-tools, the PyTorch/AnnData-based package for probabilistic analysis of single-cell RNA, protein, ATAC, spatial, methylation, perturbation, velocity, and related omics data.

Use the bundled sub-skills for workflow depth. Keep the root as a router: read only the sub-skill and references needed for the user request.

First Checks

For a new environment or bug report, verify the install before choosing a workflow:

python - <<'PY'
import scvi, torch, anndata
print('scvi-tools', scvi.__version__)
print('torch', torch.__version__, 'cuda', torch.cuda.is_available())
print('anndata', anndata.__version__)
PY

Or run the bundled diagnostic:

python scripts/check_scvi_environment.py --json

scvi-tools requires Python 3.12+ in this checkout. GPU acceleration is optional for most APIs; CPU works for inspection and small examples, while real training may require CUDA/MPS/accelerator-specific PyTorch installations.

Route by Task

• Preparing input data, AnnData/MuData, layers, .obs, .obsm, .varm, registries, readers, or setup_anndata: use sub-skills/data-setup/.
• Choosing and instantiating built-in models such as SCVI, SCANVI, TOTALVI, PEAKVI, MULTIVI, AUTOZI, LinearSCVI, CondSCVI, DestVI, AmortizedLDA, or mlxSCVI: use sub-skills/core-models/.
• Label transfer, semi-supervised annotation, query/reference mapping, doublet detection, or marker-based assignment with SCANVI, SOLO, or CellAssign: use sub-skills/annotation-and-query/.
• Multimodal, spatial, ATAC, methylation, velocity, perturbation, contrastive, deconvolution, and external specialized model families: use sub-skills/multimodal-and-spatial/.
• Training arguments, Trainer behavior, accelerator/device choices, callbacks, validation splits, dataloaders, custom datamodules, or inference dataloaders: use sub-skills/training-and-inference/.
• Post-training outputs such as latent representations, normalized expression/protein/accessibility, imputation, differential expression/abundance/accessibility/methylation, posterior predictive checks, criticism, or simulation: use sub-skills/downstream-analysis/.
• Saving/loading, model directories, minified data, registry compatibility, version migration, or Hugging Face Hub metadata/publish/load flows: use sub-skills/model-io-and-hub/.
• Hyperparameter tuning, Ray/HyperOpt, MLflow, optional extras, developer extension APIs, custom modules, Pyro/module internals, distributions, or neural-network building blocks: use sub-skills/advanced-operations/.

Common End-to-End Pattern

import scvi

scvi.model.SCVI.setup_anndata(adata, layer='counts', batch_key='batch')
model = scvi.model.SCVI(adata, n_latent=10)
model.train(max_epochs=20, accelerator='auto', devices='auto')
latent = model.get_latent_representation()
model.save('my_scvi_model', overwrite=True)

For this pattern:

1. Use data-setup to make sure adata contains valid counts, batch labels, covariates, modality matrices, and registry fields.
2. Use core-models or a specialized model sub-skill to choose the class and setup keys.
3. Use training-and-inference to tune epochs, batch size, accelerator, callbacks, and dataloaders.
4. Use downstream-analysis for accessors and statistical outputs.
5. Use model-io-and-hub before handing off a saved model or loading one in another environment.

Optional Dependencies

The base package covers common model APIs, but several routes need extras or services:

• autotune: Ray/HyperOpt and tuning helpers.
• hub: Hugging Face Hub and storage metadata workflows.
• dataloaders: LaminDB, CELLxGENE Census, TileDB-SOMA, torchdata, and AnnBatch integrations.
• regseq, file_sharing, parallel, interpretability, diagvi, mlflow, rapids, cuda, tpu, metal: specialized workflows.

Do not install all or broad extras automatically. Install the smallest extra set needed for the requested route, then rerun scripts/check_scvi_environment.py.

Troubleshooting Entry Points

• Cross-cutting install/import/backend/version failures: read references/troubleshooting.md.
• Data-field or registry failures: read sub-skills/data-setup/references/troubleshooting.md.
• Model-family or modality mismatch: read the nearest model sub-skill troubleshooting reference.
• Training failures: read sub-skills/training-and-inference/references/troubleshooting.md.
• Save/load or Hub failures: read sub-skills/model-io-and-hub/references/troubleshooting.md.

Provenance

This generated skill is aligned to the source snapshot in references/repo-provenance.md. Refresh the skill if the repository version, public model APIs, optional extras, setup signatures, or save/load/hub behavior changes.