agentleFS
qinyan-aiqinyan-ai/qinyan-academic-skills/skills/05-生物信息与基因组学/scvi-tools/SKILL.md

scvi-tools

Skill80 starsChanged 8 months agoMITView on GitHub

Deep generative models for single-cell omics. Use when you need probabilistic batch correction (scVI), transfer learning, differential expression with uncertainty, or multi-modal integration (TOTALVI, MultiVI). Best for advanced modeling, batch effects, multimodal data. For standard analysis pipelines use scanpy.

  • Installs packages

18 other projects use a version of this, 8 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use esmfold2, fair-esm2 and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • JimLiuSkill

    esmfold2

    Biohub ESMFold2 / ESMFold2-Fast all-atom co-folding (Candido et al. 2026, github.com/Biohub/esm). Single-sequence and MSA modes; protein, DNA, RNA, ligand (CCD/SMILES), modified residues. FoldBench Ab-Ag 50-55%, PPI 70-77% DockQ-pass. Also covers the ESMC-{300M,600M,6B} protein language models from the same release: masked-LM logits, hidden states, mutation scoring, contact prediction, and the SAE interpretability head. MIT-licensed weights on HuggingFace org `biohub`. Use this skill when: (1) Predicting complex structures with single-sequence input, (2) Validating designed binders with ESMFold2-Fast, (3) Running ESMFold2 with MSA input, (4) Getting ESMC embeddings or per-residue mutation scores, (5) Choosing kernel backend and sampling-step settings for paper-faithful throughput.

    Also in 3 projects that use this

  • JimLiuSkill

    fair-esm2

    Embed proteins with Meta AI's ESM-2 (`fair-esm` package). Use this skill when: (1) Extracting per-residue or per-sequence embeddings for downstream ML, (2) Masked-LM likelihood / mutation effect scoring, (3) Contact prediction from a sequence.

    Also in 3 projects that use this

  • naitySkill

    chai1

    Skill for biomolecular structure prediction with Chai-1 from Chai Discovery. Use this skill when a user wants to predict protein structures, protein-ligand complexes, protein-nucleic acid complexes, or multi-chain biomolecular assemblies. Also trigger when the user mentions Chai-1, chai-lab, or wants an AlphaFold3/Boltz-2 alternative that supports proteins, small molecules, RNA, and DNA. Chai-1 is Apache 2.0 licensed (commercial use allowed).

    Also in 3 projects that use this

  • naitySkill

    evo2

    Skill for genomic sequence modeling and design with Evo2 from Arc Institute. Use this skill when a user wants to model or generate DNA sequences, score variant effects at single-nucleotide resolution, extract genomic embeddings, analyze mutations in non-coding or coding regions, design synthetic genomic elements, compute positional entropy across a sequence, or work with genome-scale context (up to 1M base pairs). Also trigger when the user mentions Evo2, Evo 2, Arc Institute DNA model, genomic language models, DNA variant scoring, or genome-scale foundation models. NOTE: Evo2 is a DNA model — it is NOT a protein language model. For protein embeddings or protein variant scoring use ESM2, ESM-C, or ProtT5 instead.

    Also in 3 projects that use this

  • +8 more from JimLiu

The file

We split this skill into the rules it gives an agent

6 rules. 5 are common, 0 are distinctive, and 1 is very specific to this project.

  • 5

    Common

    Most of the 13 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Common:

    Use this skill when:

    line 17
  2. Common:

    All scvi-tools models follow a consistent API pattern:

    line 67
  3. Common:

    Use raw counts: Always provide unnormalized count data to models

    line 181
  4. Very specific:

    Filter genes: Remove low-count genes before analysis (e.g., min_counts=3)

    line 182
  5. Common:

    Feature selection: Use highly variable genes for improved performance

    line 184
  6. Common:

    Model saving: Always save trained models to avoid retraining

    line 185

“Common” is measured: kept by at least 6 in 10 of the 13 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

scvi-tools

Overview

scvi-tools is a comprehensive Python framework for probabilistic models in single-cell genomics. Built on PyTorch and PyTorch Lightning, it provides deep generative models using variational inference for analyzing diverse single-cell data modalities.

When to Use This Skill

Use this skill when:

  • Analyzing single-cell RNA-seq data (dimensionality reduction, batch correction, integration)
  • Working with single-cell ATAC-seq or chromatin accessibility data
  • Integrating multimodal data (CITE-seq, multiome, paired/unpaired datasets)
  • Analyzing spatial transcriptomics data (deconvolution, spatial mapping)
  • Performing differential expression analysis on single-cell data
  • Conducting cell type annotation or transfer learning tasks
  • Working with specialized single-cell modalities (methylation, cytometry, RNA velocity)
  • Building custom probabilistic models for single-cell analysis

Core Capabilities

scvi-tools provides models organized by data modality:

1. Single-Cell RNA-seq Analysis

Core models for expression analysis, batch correction, and integration. See references/models-scrna-seq.md for:

  • scVI: Unsupervised dimensionality reduction and batch correction
  • scANVI: Semi-supervised cell type annotation and integration
  • AUTOZI: Zero-inflation detection and modeling
  • VeloVI: RNA velocity analysis
  • contrastiveVI: Perturbation effect isolation

2. Chromatin Accessibility (ATAC-seq)

Models for analyzing single-cell chromatin data. See references/models-atac-seq.md for:

  • PeakVI: Peak-based ATAC-seq analysis and integration
  • PoissonVI: Quantitative fragment count modeling
  • scBasset: Deep learning approach with motif analysis

3. Multimodal & Multi-omics Integration

Joint analysis of multiple data types. See references/models-multimodal.md for:

  • totalVI: CITE-seq protein and RNA joint modeling
  • MultiVI: Paired and unpaired multi-omic integration
  • MrVI: Multi-resolution cross-sample analysis

4. Spatial Transcriptomics

Spatially-resolved transcriptomics analysis. See references/models-spatial.md for:

  • DestVI: Multi-resolution spatial deconvolution
  • Stereoscope: Cell type deconvolution
  • Tangram: Spatial mapping and integration
  • scVIVA: Cell-environment relationship analysis

5. Specialized Modalities

Additional specialized analysis tools. See references/models-specialized.md for:

  • MethylVI/MethylANVI: Single-cell methylation analysis
  • CytoVI: Flow/mass cytometry batch correction
  • Solo: Doublet detection
  • CellAssign: Marker-based cell type annotation

Typical Workflow

All scvi-tools models follow a consistent API pattern:

# 1. Load and preprocess data (AnnData format)
import scvi
import scanpy as sc

adata = scvi.data.heart_cell_atlas_subsampled()
sc.pp.filter_genes(adata, min_counts=3)
sc.pp.highly_variable_genes(adata, n_top_genes=1200)

# 2. Register data with model (specify layers, covariates)
scvi.model.SCVI.setup_anndata(
    adata,
    layer="counts",  # Use raw counts, not log-normalized
    batch_key="batch",
    categorical_covariate_keys=["donor"],
    continuous_covariate_keys=["percent_mito"]
)

# 3. Create and train model
model = scvi.model.SCVI(adata)
model.train()

# 4. Extract latent representations and normalized values
latent = model.get_latent_representation()
normalized = model.get_normalized_expression(library_size=1e4)

# 5. Store in AnnData for downstream analysis
adata.obsm["X_scVI"] = latent
adata.layers["scvi_normalized"] = normalized

# 6. Downstream analysis with scanpy
sc.pp.neighbors(adata, use_rep="X_scVI")
sc.tl.umap(adata)
sc.tl.leiden(adata)

Key Design Principles:

  • Raw counts required: Models expect unnormalized count data for optimal performance
  • Unified API: Consistent interface across all models (setup → train → extract)
  • AnnData-centric: Seamless integration with the scanpy ecosystem
  • GPU acceleration: Automatic utilization of available GPUs
  • Batch correction: Handle technical variation through covariate registration

Common Analysis Tasks

Differential Expression

Probabilistic DE analysis using the learned generative models:

de_results = model.differential_expression(
    groupby="cell_type",
    group1="TypeA",
    group2="TypeB",
    mode="change",  # Use composite hypothesis testing
    delta=0.25      # Minimum effect size threshold
)

See references/differential-expression.md for detailed methodology and interpretation.

Model Persistence

Save and load trained models:

# Save model
model.save("./model_directory", overwrite=True)

# Load model
model = scvi.model.SCVI.load("./model_directory", adata=adata)

Batch Correction and Integration

Integrate datasets across batches or studies:

# Register batch information
scvi.model.SCVI.setup_anndata(adata, batch_key="study")

# Model automatically learns batch-corrected representations
model = scvi.model.SCVI(adata)
model.train()
latent = model.get_latent_representation()  # Batch-corrected

Theoretical Foundations

scvi-tools is built on:

  • Variational inference: Approximate posterior distributions for scalable Bayesian inference
  • Deep generative models: VAE architectures that learn complex data distributions
  • Amortized inference: Shared neural networks for efficient learning across cells
  • Probabilistic modeling: Principled uncertainty quantification and statistical testing

See references/theoretical-foundations.md for detailed background on the mathematical framework.

Additional Resources

Installation

uv pip install scvi-tools
# For GPU support
uv pip install scvi-tools[cuda]

Best Practices

  1. Use raw counts: Always provide unnormalized count data to models
  2. Filter genes: Remove low-count genes before analysis (e.g., min_counts=3)
  3. Register covariates: Include known technical factors (batch, donor, etc.) in setup_anndata
  4. Feature selection: Use highly variable genes for improved performance
  5. Model saving: Always save trained models to avoid retraining
  6. GPU usage: Enable GPU acceleration for large datasets (accelerator="gpu")
  7. Scanpy integration: Store outputs in AnnData objects for downstream analysis

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.