Scvi Tools

AnthropicOfficialPublished by Anthropic

Skill
Tool integration
Data and AI
Apache-2.0
Low risk
Has scripts

From the author

Deep learning for single-cell analysis using scvi-tools. This skill should be used when users need (1) data integration and batch correction with scVI/scANVI, (2) ATAC-seq analysis with PeakVI, (3) CITE-seq multi-modal analysis with totalVI, (4) multiome RNA+ATAC analysis with MultiVI, (5) spatial transcriptomics deconvolution with DestVI, (6) label transfer and reference mapping with scANVI/scArches, (7) RNA velocity with veloVI, or (8) any deep learning-based single-cell method. Triggers include mentions of scVI, scANVI, totalVI, PeakVI, MultiVI, DestVI, veloVI, sysVI, scArches, variational autoencoder, VAE, batch correction, data integration, multi-modal, CITE-seq, multiome, reference mapping, latent space.

— the description by Anthropic

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/download

Unzip 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 code
For installation or GPU issues, consult references/environment_setup.md
For 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 leiden

Python 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/multiome_multivi.md

Multiome Analysis with MultiVI

This reference covers joint RNA and ATAC-seq analysis from multiome experiments using MultiVI.

Overview

MultiVI is a deep generative model for analyzing multiome data (simultaneous RNA-seq and ATAC-seq from the same cells). It:

Learns a joint latent representation across modalities
Handles missing modalities (RNA-only or ATAC-only cells)
Enables batch correction across experiments
Supports imputation of missing modalities

Prerequisites

import scvi
import scanpy as sc
import mudata as md
import numpy as np

print(f"scvi-tools version: {scvi.__version__}")

Data Formats

Option 1: MuData (Recommended)

# Load multiome data as MuData
mdata = md.read("multiome.h5mu")

# Structure:
# mdata.mod['rna']  - AnnData with RNA counts
# mdata.mod['atac'] - AnnData with ATAC counts

print(f"RNA: {mdata.mod['rna'].shape}")
print(f"ATAC: {mdata.mod['atac'].shape}")

Option 2: Separate AnnData Objects

# Load separately
adata_rna = sc.read_h5ad("rna.h5ad")
adata_atac = sc.read_h5ad("atac.h5ad")

# Ensure same cells in same order
common_cells = adata_rna.obs_names.intersection(adata_atac.obs_names)
adata_rna = adata_rna[common_cells].copy()
adata_atac = adata_atac[common_cells].copy()

Step 1: Prepare RNA Data

# RNA preprocessing (standard scvi-tools pipeline)
adata_rna = mdata.mod['rna'].copy()

# Filter
sc.pp.filter_cells(adata_rna, min_genes=200)
sc.pp.filter_genes(adata_rna, min_cells=3)

# Store counts
adata_rna.layers["counts"] = adata_rna.X.copy()

# HVG selection
sc.pp.highly_variable_genes(
    adata_rna,
    n_top_genes=4000,
    flavor="seurat_v3",
    layer="counts",
    batch_key="batch"  # If multiple batches
)

# Subset to HVGs
adata_rna = adata_rna[:, adata_rna.var['highly_variable']].copy()

Step 2: Prepare ATAC Data

# ATAC preprocessing
adata_atac = mdata.mod['atac'].copy()

# Filter peaks
sc.pp.filter_genes(adata_atac, min_cells=10)

# Binarize accessibility
adata_atac.X = (adata_atac.X > 0).astype(np.float32)

# Select top accessible peaks (if too many)
if adata_atac.n_vars > 50000:
    peak_accessibility = np.array(adata_atac.X.sum(axis=0)).flatten()
    top_peaks = np.argsort(peak_accessibility)[-50000:]
    adata_atac = adata_atac[:, top_peaks].copy()

# Store in layer
adata_atac.layers["counts"] = adata_atac.X.copy()

Step 3: Create Combined MuData

# Ensure matching cells
common_cells = adata_rna.obs_names.intersection(adata_atac.obs_names)
adata_rna = adata_rna[common_cells].copy()
adata_atac = adata_atac[common_cells].copy()

# Create MuData
mdata = md.MuData({
    "rna": adata_rna,
    "atac": adata_atac
})

print(f"Combined multiome: {mdata.n_obs} cells")
print(f"RNA features: {mdata.mod['rna'].n_vars}")
print(f"ATAC features: {mdata.mod['atac'].n_vars}")

Step 4: Setup MultiVI

# Setup MuData for MultiVI
scvi.model.MULTIVI.setup_mudata(
    mdata,
    rna_layer="counts",
    atac_layer="counts",
    batch_key="batch",  # Optional
    modalities={
        "rna_layer": "rna",
        "batch_key": "rna",
        "atac_layer": "atac"
    }
)

Step 5: Train MultiVI

# Create model
model = scvi.model.MULTIVI(
    mdata,
    n_latent=20,
    n_layers_encoder=2,
    n_layers_decoder=2
)

# Train
model.train(
    max_epochs=300,
    early_stopping=True,
    early_stopping_patience=10,
    batch_size=128
)

# Check training
model.history['elbo_train'].plot()

Step 6: Get Joint Representation

# Latent representation
latent = model.get_latent_representation()

# Add to MuData
mdata.obsm["X_MultiVI"] = latent

# Clustering on joint space
sc.pp.neighbors(mdata, use_rep="X_MultiVI")
sc.tl.umap(mdata)
sc.tl.leiden(mdata, resolution=1.0)

# Visualize
sc.pl.umap(mdata, color=['leiden', 'batch'], ncols=2)

Step 7: Modality-Specific Analysis

Impute Missing Modality

# Impute RNA expression for ATAC-only cells
# (Useful when integrating with ATAC-only datasets)
imputed_rna = model.get_normalized_expression(
    modality="rna"
)

# Impute accessibility for RNA-only cells
imputed_atac = model.get_accessibility_estimates()

Differential Analysis

# Differential expression (RNA)
de_results = model.differential_expression(
    groupby="leiden",
    group1="0",
    group2="1"
)

# Differential accessibility (ATAC)
da_results = model.differential_accessibility(
    groupby="leiden",
    group1="0",
    group2="1"
)

Handling Partial Data

MultiVI can integrate datasets with only one modality:

# Dataset 1: Full multiome
# Dataset 2: RNA only
# Dataset 3: ATAC only

# Mark missing modalities
mdata.obs['modality'] = 'paired'  # For cells with both
# For RNA-only cells, ATAC data should be missing/NaN
# For ATAC-only cells, RNA data should be missing/NaN

# MultiVI handles this automatically during training

Complete Pipeline

def analyze_multiome(
    adata_rna,
    adata_atac,
    batch_key=None,
    n_top_genes=4000,
    n_top_peaks=50000,
    n_latent=20,
    max_epochs=300
):
    """
    Complete multiome analysis with MultiVI.

    Parameters
    ----------
    adata_rna : AnnData
        RNA count data
    adata_atac : AnnData
        ATAC peak data
    batch_key : str, optional
        Batch column name
    n_top_genes : int
        Number of HVGs for RNA
    n_top_peaks : int
        Number of top peaks for ATAC
    n_latent : int
        Latent dimensions
    max_epochs : int
        Maximum training epochs

    Returns
    -------
    MuData with joint representation
    """
    import scvi
    import scanpy as sc
    import mudata as md
    import numpy as np

    # Get common cells
    common_cells = adata_rna.obs_names.intersection(adata_atac.obs_names)
    adata_rna = adata_rna[common_cells].copy()
    adata_atac = adata_atac[common_cells].copy()

    # RNA preprocessing
    sc.pp.filter_genes(adata_rna, min_cells=3)
    adata_rna.layers["counts"] = adata_rna.X.copy()

    if batch_key:
        sc.pp.highly_variable_genes(
            adata_rna, n_top_genes=n_top_genes,
            flavor="seurat_v3", layer="counts", batch_key=batch_key
        )
    else:
        sc.pp.normalize_total(adata_rna, target_sum=1e4)
        sc.pp.log1p(adata_rna)
        sc.pp.highly_variable_genes(adata_rna, n_top_genes=n_top_genes)
        adata_rna.X = adata_rna.layers["counts"].copy()

    adata_rna = adata_rna[:, adata_rna.var['highly_variable']].copy()

    # ATAC preprocessing
    sc.pp.filter_genes(adata_atac, min_cells=10)
    adata_atac.X = (adata_atac.X > 0).astype(np.float32)

    if adata_atac.n_vars > n_top_peaks:
        peak_acc = np.array(adata_atac.X.sum(axis=0)).flatten()
        top_idx = np.argsort(peak_acc)[-n_top_peaks:]
        adata_atac = adata_atac[:, top_idx].copy()

    adata_atac.layers["counts"] = adata_atac.X.copy()

    # Create MuData
    mdata = md.MuData({"rna": adata_rna, "atac": adata_atac})

    # Setup and train
    scvi.model.MULTIVI.setup_mudata(
        mdata,
        rna_layer="counts",
        atac_layer="counts",
        batch_key=batch_key,
        modalities={"rna_layer": "rna", "batch_key": "rna", "atac_layer": "atac"}
    )

    model = scvi.model.MULTIVI(mdata, n_latent=n_latent)
    model.train(max_epochs=max_epochs, early_stopping=True)

    # Add representation
    mdata.obsm["X_MultiVI"] = model.get_latent_representation()

    # Cluster
    sc.pp.neighbors(mdata, use_rep="X_MultiVI")
    sc.tl.umap(mdata)
    sc.tl.leiden(mdata)

    return mdata, model


# Usage
mdata, model = analyze_multiome(
    adata_rna,
    adata_atac,
    batch_key="sample"
)

sc.pl.umap(mdata, color=['leiden', 'sample'])

Peak-to-Gene Linking

# Link ATAC peaks to genes based on correlation in latent space
# This identifies regulatory relationships

def link_peaks_to_genes(model, mdata, distance_threshold=100000):
    """
    Link peaks to nearby genes based on correlation.

    Parameters
    ----------
    model : MULTIVI
        Trained model
    mdata : MuData
        Multiome data
    distance_threshold : int
        Maximum distance (bp) to link peak to gene

    Returns
    -------
    DataFrame of peak-gene links
    """
    # Get imputed values
    rna_imputed = model.get_normalized_expression()
    atac_imputed = model.get_accessibility_estimates()

    # Correlate peak accessibility with gene expression
    # for peaks near gene promoters
    # ... (requires genomic coordinates)

    return peak_gene_links

Troubleshooting

Issue	Cause	Solution
Different cell counts	Cells missing in one modality	Use common cells only
Training instability	Imbalanced modalities	Normalize feature counts
Poor clustering	Too few features	Increase n_top_genes/peaks
Memory error	Large ATAC matrix	Reduce peak count, use sparse
Batch dominates	Strong technical effects	Ensure batch_key is set

Key References

Ashuach et al. (2023) "MultiVI: deep generative model for the integration of multimodal data"

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

2026-11-08

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