Scvi Tools
AnthropicOfficialPublished by Anthropic
- Skill
- Tool integration
- Data and AI
- Apache-2.0
- Low risk
- Has scripts
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
scvi-tools provides a suite of probabilistic models designed for the analysis of single-cell data, including scRNA-seq, scATAC-seq, and multi-modal datasets. It leverages variational autoencoders to handle batch correction, data integration, label transfer, and dimensionality reduction. This skill serves as a guide for utilizing specific models like scVI, scANVI, totalVI, PeakVI, MultiVI, DestVI, and veloVI, offering standardized workflows, CLI scripts for pipeline automation, and best practices for data preparation and model training.
What it does
- Performs batch correction and data integration across different experimental conditions.
- Supports multi-modal analysis for CITE-seq and multiome (RNA+ATAC) data.
- Enables label transfer and reference mapping between query and reference datasets.
- Facilitates spatial transcriptomics deconvolution and RNA velocity estimation.
- Provides modular Python scripts for common analysis pipelines.
- Offers guidance on model selection based on specific data types and research goals.
When to use it
- When integrating multiple single-cell datasets with significant batch effects.
- When analyzing multi-modal data such as CITE-seq or joint RNA+ATAC profiles.
- When performing reference-based label transfer or query-to-reference mapping.
- When conducting deep learning-based dimensionality reduction for clustering and visualization.
- When working with spatial transcriptomics or RNA velocity data.
Advantages
- Standardized approach to complex single-cell deep learning workflows.
- Modular scripts allow for reproducible and scalable analysis pipelines.
- Comprehensive model selection guide for diverse genomic data types.
- Built-in support for advanced tasks like batch correction and multi-modal integration.
- Clear documentation on data preparation requirements for probabilistic models.
Usage examples
- “How do I integrate two scRNA-seq datasets using scVI?”
- The agent provides the workflow for preparing the AnnData objects, selecting highly variable genes, setting up the model with batch keys, and training the scVI model.
- “I have CITE-seq data, which model should I use?”
- The agent identifies totalVI as the appropriate model and directs the user to the corresponding reference file for multi-modal integration.
- “How can I map my new scRNA-seq query data to an existing reference?”
- The agent explains the use of scArches for query-to-reference mapping and provides the necessary steps to configure the model.
- “What are the requirements for input data before training a model?”
- The agent outlines the necessity of raw integer count data, the importance of highly variable gene selection, and how to correctly set up the AnnData object.
Install
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/anthropics/scvi-tools/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip scvi-tools.zip -d .agents/skills
Documentation by Anthropic
scvi-tools Deep Learning Skill
This skill provides guidance for deep learning-based single-cell analysis using scvi-tools, the leading framework for probabilistic models in single-cell genomics.
How to Use This Skill
Identify the appropriate workflow from the model/workflow tables below
Read the corresponding reference file for detailed steps and code
Use scripts in
scripts/to avoid rewriting common codeFor installation or GPU issues, consult
references/environment_setup.mdFor debugging, consult
references/troubleshooting.md
When to Use This Skill
When scvi-tools, scVI, scANVI, or related models are mentioned
When deep learning-based batch correction or integration is needed
When working with multi-modal data (CITE-seq, multiome)
When reference mapping or label transfer is required
When analyzing ATAC-seq or spatial transcriptomics data
When learning latent representations of single-cell data
Model Selection Guide
| Data Type | Model | Primary Use Case |
|---|---|---|
| scRNA-seq | scVI | Unsupervised integration, DE, imputation |
| scRNA-seq + labels | scANVI | Label transfer, semi-supervised integration |
| CITE-seq (RNA+protein) | totalVI | Multi-modal integration, protein denoising |
| scATAC-seq | PeakVI | Chromatin accessibility analysis |
| Multiome (RNA+ATAC) | MultiVI | Joint modality analysis |
| Spatial + scRNA reference | DestVI | Cell type deconvolution |
| RNA velocity | veloVI | Transcriptional dynamics |
| Cross-technology | sysVI | System-level batch correction |
Workflow Reference Files
| Workflow | Reference File | Description |
|---|---|---|
| Environment Setup | references/environment_setup.md | Installation, GPU, version info |
| Data Preparation | references/data_preparation.md | Formatting data for any model |
| scRNA Integration | references/scrna_integration.md | scVI/scANVI batch correction |
| ATAC-seq Analysis | references/atac_peakvi.md | PeakVI for accessibility |
| CITE-seq Analysis | references/citeseq_totalvi.md | totalVI for protein+RNA |
| Multiome Analysis | references/multiome_multivi.md | MultiVI for RNA+ATAC |
| Spatial Deconvolution | references/spatial_deconvolution.md | DestVI spatial analysis |
| Label Transfer | references/label_transfer.md | scANVI reference mapping |
| scArches Mapping | references/scarches_mapping.md | Query-to-reference mapping |
| Batch Correction | references/batch_correction_sysvi.md | Advanced batch methods |
| RNA Velocity | references/rna_velocity_velovi.md | veloVI dynamics |
| Troubleshooting | references/troubleshooting.md | Common issues and solutions |
CLI Scripts
Modular scripts for common workflows. Chain together or modify as needed.
Pipeline Scripts
| Script | Purpose | Usage |
|---|---|---|
prepare_data.py | QC, filter, HVG selection | python scripts/prepare_data.py raw.h5ad prepared.h5ad --batch-key batch |
train_model.py | Train any scvi-tools model | python scripts/train_model.py prepared.h5ad results/ --model scvi |
cluster_embed.py | Neighbors, UMAP, Leiden | python scripts/cluster_embed.py adata.h5ad results/ |
differential_expression.py | DE analysis | python scripts/differential_expression.py model/ adata.h5ad de.csv --groupby leiden |
transfer_labels.py | Label transfer with scANVI | python scripts/transfer_labels.py ref_model/ query.h5ad results/ |
integrate_datasets.py | Multi-dataset integration | python scripts/integrate_datasets.py results/ data1.h5ad data2.h5ad |
validate_adata.py | Check data compatibility | python scripts/validate_adata.py data.h5ad --batch-key batch |
Example Workflow
# 1. Validate input data
python scripts/validate_adata.py raw.h5ad --batch-key batch --suggest
# 2. Prepare data (QC, HVG selection)
python scripts/prepare_data.py raw.h5ad prepared.h5ad --batch-key batch --n-hvgs 2000
# 3. Train model
python scripts/train_model.py prepared.h5ad results/ --model scvi --batch-key batch
# 4. Cluster and visualize
python scripts/cluster_embed.py results/adata_trained.h5ad results/ --resolution 0.8
# 5. Differential expression
python scripts/differential_expression.py results/model results/adata_clustered.h5ad results/de.csv --groupby leidenPython Utilities
The scripts/model_utils.py provides importable functions for custom workflows:
| Function | Purpose |
|---|---|
prepare_adata() | Data preparation (QC, HVG, layer setup) |
train_scvi() | Train scVI or scANVI |
evaluate_integration() | Compute integration metrics |
get_marker_genes() | Extract DE markers |
save_results() | Save model, data, plots |
auto_select_model() | Suggest best model |
quick_clustering() | Neighbors + UMAP + Leiden |
Critical Requirements
Raw counts required: scvi-tools models require integer count data
adata.layers["counts"] = adata.X.copy() # Before normalization scvi.model.SCVI.setup_anndata(adata, layer="counts")HVG selection: Use 2000-4000 highly variable genes
sc.pp.highly_variable_genes(adata, n_top_genes=2000, batch_key="batch", layer="counts", flavor="seurat_v3") adata = adata[:, adata.var['highly_variable']].copy()Batch information: Specify batch_key for integration
scvi.model.SCVI.setup_anndata(adata, layer="counts", batch_key="batch")
Quick Decision Tree
Need to integrate scRNA-seq data?
├── Have cell type labels? → scANVI (references/label_transfer.md)
└── No labels? → scVI (references/scrna_integration.md)
Have multi-modal data?
├── CITE-seq (RNA + protein)? → totalVI (references/citeseq_totalvi.md)
├── Multiome (RNA + ATAC)? → MultiVI (references/multiome_multivi.md)
└── scATAC-seq only? → PeakVI (references/atac_peakvi.md)
Have spatial data?
└── Need cell type deconvolution? → DestVI (references/spatial_deconvolution.md)
Have pre-trained reference model?
└── Map query to reference? → scArches (references/scarches_mapping.md)
Need RNA velocity?
└── veloVI (references/rna_velocity_velovi.md)
Strong cross-technology batch effects?
└── sysVI (references/batch_correction_sysvi.md)Key Resources
Files
- ATTRIBUTION.mdAdded by AutoGineer932 B
- LICENSE.txt10.0 KiB
- SKILL.md7.2 KiB
- references/atac_peakvi.md9.3 KiB
- references/batch_correction_sysvi.md10.2 KiB
- references/citeseq_totalvi.md10.1 KiB
- references/data_preparation.md6.2 KiB
- references/environment_setup.md6.3 KiB
- references/label_transfer.md10.2 KiB
- references/multiome_multivi.md8.9 KiB
- references/rna_velocity_velovi.md8.6 KiB
- references/scarches_mapping.md10.8 KiB
- references/scrna_integration.md9.6 KiB
- references/spatial_deconvolution.md11.2 KiB
- references/troubleshooting.md10.8 KiB
- scripts/cluster_embed.pyScript6.3 KiB
- scripts/differential_expression.pyScript6.7 KiB
- scripts/integrate_datasets.pyScript6.9 KiB
- scripts/model_utils.pyScript17.0 KiB
- scripts/prepare_data.pyScript5.1 KiB
- scripts/train_model.pyScript11.3 KiB
- scripts/transfer_labels.pyScript7.2 KiB
- scripts/validate_adata.pyScript11.9 KiB
references/environment_setup.md
Environment Setup for scvi-tools
This reference covers installation and environment configuration for scvi-tools.
Installation Options
Option 1: Conda Environment (Recommended)
# Create environment with GPU support
conda create -n scvi-env python=3.10
conda activate scvi-env
# Install scvi-tools
pip install scvi-tools
# For GPU acceleration (recommended for large datasets)
pip install torch --index-url https://download.pytorch.org/whl/cu118
# Common dependencies
pip install scanpy leidenalgOption 2: Pip Only
# Create virtual environment
python -m venv scvi-env
source scvi-env/bin/activate # Linux/Mac
# scvi-env\Scripts\activate # Windows
# Install
pip install scvi-tools scanpyOption 3: With Spatial Analysis Support
conda create -n scvi-spatial python=3.10
conda activate scvi-spatial
pip install scvi-tools scanpy squidpyOption 4: With MuData Support (Multiome)
pip install scvi-tools mudata muonVerify Installation
import scvi
import torch
import scanpy as sc
print(f"scvi-tools version: {scvi.__version__}")
print(f"scanpy version: {sc.__version__}")
print(f"PyTorch version: {torch.__version__}")
print(f"GPU available: {torch.cuda.is_available()}")
if torch.cuda.is_available():
print(f"GPU device: {torch.cuda.get_device_name(0)}")
print(f"GPU memory: {torch.cuda.get_device_properties(0).total_memory / 1e9:.1f} GB")GPU Configuration
Check CUDA Version
nvidia-smi
nvcc --versionPyTorch CUDA Versions
| CUDA Version | PyTorch Install Command |
|---|---|
| CUDA 11.8 | pip install torch --index-url https://download.pytorch.org/whl/cu118 |
| CUDA 12.1 | pip install torch --index-url https://download.pytorch.org/whl/cu121 |
| CPU only | pip install torch --index-url https://download.pytorch.org/whl/cpu |
Memory Management
import torch
# Clear GPU cache between models
torch.cuda.empty_cache()
# Monitor memory usage
print(f"Allocated: {torch.cuda.memory_allocated() / 1e9:.2f} GB")
print(f"Cached: {torch.cuda.memory_reserved() / 1e9:.2f} GB")Common Issues
| Issue | Cause | Solution |
|---|---|---|
CUDA out of memory | GPU memory exhausted | Reduce batch_size, use smaller model |
No GPU detected | CUDA not installed | Install CUDA toolkit matching PyTorch |
Version mismatch | PyTorch/CUDA incompatibility | Reinstall PyTorch with correct CUDA version |
Import error scvi | Missing dependencies | pip install scvi-tools[all] |
Jupyter Setup
# Install Jupyter kernel
pip install ipykernel
python -m ipykernel install --user --name scvi-env --display-name "scvi-tools"
# For interactive plots
pip install matplotlib seabornRecommended Package Versions
For reproducibility, pin versions:
pip install \
scvi-tools>=1.0.0 \
scanpy>=1.9.0 \
anndata>=0.9.0 \
torch>=2.0.0Version Compatibility Guide
scvi-tools 1.x vs 0.x API Changes
The 1.x release introduced breaking changes. Key differences:
| Operation | 0.x API (deprecated) | 1.x API (current) |
|---|---|---|
| Setup data | scvi.data.setup_anndata(adata, ...) | scvi.model.SCVI.setup_anndata(adata, ...) |
| Register data | scvi.data.register_tensor_from_anndata(...) | Built into setup_anndata |
| View setup | scvi.data.view_anndata_setup(adata) | scvi.model.SCVI.view_anndata_setup(adata) |
Migration from 0.x to 1.x
# OLD (0.x) - DEPRECATED
import scvi
scvi.data.setup_anndata(adata, layer="counts", batch_key="batch")
model = scvi.model.SCVI(adata)
# NEW (1.x) - CURRENT
import scvi
scvi.model.SCVI.setup_anndata(adata, layer="counts", batch_key="batch")
model = scvi.model.SCVI(adata)Model-Specific Setup (1.x)
Each model has its own setup method:
# scVI
scvi.model.SCVI.setup_anndata(adata, layer="counts", batch_key="batch")
# scANVI
scvi.model.SCANVI.setup_anndata(adata, layer="counts", batch_key="batch", labels_key="cell_type")
# totalVI
scvi.model.TOTALVI.setup_anndata(adata, layer="counts", protein_expression_obsm_key="protein")
# MultiVI (uses MuData)
scvi.model.MULTIVI.setup_mudata(mdata, rna_layer="counts", atac_layer="counts")
# PeakVI
scvi.model.PEAKVI.setup_anndata(adata, batch_key="batch")
# veloVI
scvi.external.VELOVI.setup_anndata(adata, spliced_layer="spliced", unspliced_layer="unspliced")Minimum Version Requirements
| Package | Minimum Version | Notes |
|---|---|---|
| scvi-tools | 1.0.0 | Required for current API |
| scanpy | 1.9.0 | HVG selection improvements |
| anndata | 0.9.0 | Improved MuData support |
| torch | 2.0.0 | Performance improvements |
| mudata | 0.2.0 | Required for MultiVI |
| scvelo | 0.2.5 | Required for veloVI |
Check Your Versions
import scvi
import scanpy as sc
import anndata
import torch
print(f"scvi-tools: {scvi.__version__}")
print(f"scanpy: {sc.__version__}")
print(f"anndata: {anndata.__version__}")
print(f"torch: {torch.__version__}")
# Check if using 1.x API
if hasattr(scvi.model.SCVI, 'setup_anndata'):
print("Using scvi-tools 1.x API")
else:
print("WARNING: Using deprecated 0.x API - please upgrade")Known Compatibility Issues
| Issue | Affected Versions | Solution |
|---|---|---|
setup_anndata not found | scvi-tools < 1.0 | Upgrade to 1.0+ |
| MuData errors | mudata < 0.2 | pip install mudata>=0.2.0 |
| CUDA version mismatch | Any | Reinstall PyTorch for your CUDA |
| numpy 2.0 issues | Early 2024 builds | pip install numpy<2.0 |
Upgrading scvi-tools
# Upgrade to latest
pip install --upgrade scvi-tools
# Upgrade all dependencies
pip install --upgrade scvi-tools scanpy anndata torch
# If you have issues, clean install
pip uninstall scvi-tools
pip cache purge
pip install scvi-toolsTesting Installation
# Quick test with sample data
import scvi
import scanpy as sc
# Load test dataset
adata = scvi.data.heart_cell_atlas_subsampled()
print(f"Loaded test data: {adata.shape}")
# Setup and create model (quick test)
scvi.model.SCVI.setup_anndata(adata, layer="counts", batch_key="cell_source")
model = scvi.model.SCVI(adata, n_latent=10)
print("Model created successfully")
# Quick training test (1 epoch)
model.train(max_epochs=1)
print("Training works!")Requirements and compatibility
Written for: Claude Code, Claude apps
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Needs: Needs Python
Security
What our scanner noticed· Low risk
- Instructions that use the network
- Scripts that your agent may run
This skill includes scripts that your agent may run. Read them before you use it.
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Published by
- Anthropic
- Publisher
- Anthropic (Official)
- Source
- anthropics/knowledge-work-plugins · bio-research/skills/scvi-tools · commit e050c2e
- Licence
- Apache License 2.0 (redistribution allowed)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by Anthropic.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download scvi-tools.zip