{"id":10216,"library":"scvi-tools","title":"scvi-tools","description":"scvi-tools provides a suite of deep learning models for the deep probabilistic analysis of single-cell omics data. It is built on PyTorch and AnnData, offering robust methods for tasks like dimensionality reduction, batch correction, and differential expression. The library is actively developed, releasing frequent minor versions and occasional major updates.","status":"active","version":"1.4.2","language":"en","source_language":"en","source_url":"https://github.com/scverse/scvi-tools","tags":["single-cell","biology","omics","deep-learning","bioinformatics","pytorch"],"install":[{"cmd":"pip install scvi-tools","lang":"bash","label":"Basic PyPI install"},{"cmd":"pip install 'scvi-tools[gpu]' --extra-index-url https://download.pytorch.org/whl/cu118","lang":"bash","label":"PyPI install with GPU support (CUDA 11.8 example)"},{"cmd":"conda install -c pytorch -c conda-forge -c bioconda scvi-tools","lang":"bash","label":"Conda install (recommended for managing dependencies)"}],"dependencies":[{"reason":"Primary data structure for single-cell data.","package":"anndata","optional":false},{"reason":"Commonly used for preprocessing and visualization in the single-cell ecosystem.","package":"scanpy","optional":true},{"reason":"Deep learning backend for all models.","package":"pytorch","optional":false}],"imports":[{"symbol":"scvi","correct":"import scvi"},{"note":"Models were moved to submodules (e.g., `scvi.model`) in version 1.0.0.","wrong":"from scvi import SCVI","symbol":"SCVI","correct":"from scvi.model import SCVI"},{"note":"While `scvi.data.setup_anndata` works, importing directly can make code cleaner. More importantly, pre-1.0.0 versions didn't explicitly require this step, leading to common errors.","wrong":"scvi.data.setup_anndata(adata, ...)","symbol":"setup_anndata","correct":"from scvi.data import setup_anndata"}],"quickstart":{"code":"import scvi\nimport scanpy as sc\nimport numpy as np\n\n# For reproducibility\nscvi.settings.seed = 0\n\n# Load a dataset\n# In a real scenario, you'd load your own AnnData object\n# For this example, we'll use a built-in dataset\nadata = scvi.data.pbmc_dataset()\n\n# Required step: set up AnnData for scvi-tools models\n# This registers the data with scvi-tools, specifying layers, batch keys, etc.\nscvi.data.setup_anndata(adata, layer=\"counts\", batch_key=\"batch\")\n\n# Initialize the SCVI model\nmodel = scvi.model.SCVI(adata, n_latent=30, n_layers=2)\n\n# Train the model\n# This can take several minutes depending on hardware and dataset size\nmodel.train()\n\n# Get latent representation and store it in adata.obsm\nadata.obsm[\"X_scVI\"] = model.get_latent_representation()\n\n# Get normalized expression and store it in adata.layers\nadata.layers[\"scvi_normalized\"] = model.get_normalized_expression(transform_batch=\"_scvi_batch_0\")\n\nprint(f\"Latent representation shape: {adata.obsm['X_scVI'].shape}\")\nprint(f\"Normalized expression layer shape: {adata.layers['scvi_normalized'].shape}\")\n\n# Further analysis could involve using scanpy on the latent space\n# sc.pp.neighbors(adata, use_rep=\"X_scVI\")\n# sc.tl.umap(adata)\n# sc.pl.umap(adata, color=[\"cell_type\", \"batch\"])","lang":"python","description":"This quickstart demonstrates the core workflow: loading an AnnData object, preparing it with `scvi.data.setup_anndata`, initializing and training an `SCVI` model, and then extracting the latent representation and normalized expression. The setup_anndata step is crucial for all scvi-tools models."},"warnings":[{"fix":"Migrate code to use `AnnData` objects. All models now require `scvi.data.setup_anndata` to be called on the AnnData object before instantiation. Model classes were moved, e.g., `scvi.SCVI` became `scvi.model.SCVI`.","message":"scvi-tools 1.0.0 introduced a major API overhaul, transitioning from a custom `Vaedata` object to `AnnData` as the primary data structure. This required significant code changes for users migrating from pre-1.0.0 versions.","severity":"breaking","affected_versions":"<1.0.0 to 1.0.0+"},{"fix":"Follow the official installation instructions carefully, especially for GPU. Consider using Conda for better dependency management (`conda install -c pytorch -c conda-forge -c bioconda scvi-tools` will typically resolve PyTorch and CUDA dependencies correctly).","message":"GPU support requires careful installation of `pytorch` with the correct CUDA version. Mismatched CUDA versions between your system, `pytorch` wheel, and potentially `cudatoolkit` in a Conda environment can lead to `RuntimeError: CUDA error` or models running slowly on CPU.","severity":"gotcha","affected_versions":"All"},{"fix":"Always call `scvi.data.setup_anndata(adata, layer=\"counts\", batch_key=\"batch\")` (adjusting `layer` and `batch_key` as needed) on your `AnnData` object before passing it to `scvi.model.SCVI` or other model constructors.","message":"Forgetting to call `scvi.data.setup_anndata` before initializing any model is a common mistake for users familiar with older versions or other single-cell libraries. This step is mandatory for all models since 1.0.0.","severity":"gotcha","affected_versions":"1.0.0+"},{"fix":"Remove the `transform_batch` argument from `model.get_normalized_expression()`. If you need batch-specific normalization, consider handling it downstream or using other model features.","message":"The `transform_batch` argument in `model.get_normalized_expression()` was deprecated and then removed in version 1.4.0. Using it will raise an error.","severity":"deprecated","affected_versions":"1.4.0+"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Call `scvi.data.setup_anndata(adata, layer=\"counts\", batch_key=\"batch\")` before initializing your model.","cause":"Attempting to initialize an scvi-tools model on an AnnData object that has not been prepared with `scvi.data.setup_anndata`.","error":"AttributeError: 'AnnData' object has no attribute '_scvi_data_registry'"},{"fix":"Model classes are now in submodules. For example, `SCVI` is imported via `from scvi.model import SCVI`.","cause":"Trying to import a model class directly from the top-level `scvi` module, a pattern common in pre-1.0.0 versions.","error":"ImportError: cannot import name 'SCVI' from 'scvi'"},{"fix":"Verify your PyTorch and CUDA installation. Use `torch.cuda.is_available()` and `torch.cuda.get_device_name(0)`. If using Conda, reinstall `scvi-tools` with `conda install -c pytorch -c conda-forge -c bioconda scvi-tools`. For 'out of memory', try reducing `batch_size` during training.","cause":"This usually indicates an issue with the GPU setup, such as mismatched CUDA versions between PyTorch and your system, or running out of GPU memory.","error":"RuntimeError: CUDA error: device-side assert triggered"},{"fix":"Ensure you are accessing AnnData attributes correctly (e.g., `adata.X`, `adata.layers['counts']`, `adata.obs['cell_type']`) and not trying to call them like functions. Verify the data type of the attribute you're accessing.","cause":"This can occur if you mistakenly try to call an `AnnData` layer or observation field (e.g., `adata.X`) as a function, often after a data transformation.","error":"TypeError: 'numpy.ndarray' object is not callable"}]}