agentleFS
nisarthnisarth/claude-skills-store/skills/bio-research/scvi-tools/SKILL.md

scvi-tools

Skill1 starsChanged 7 months agoMITView on GitHub

Deep learning for single-cell analysis using scvi-tools. Use this skill when users need data integration and batch correction with scVI/scANVI, ATAC-seq analysis with PeakVI, CITE-seq multi-modal analysis with totalVI, multi-sample differential expression, or latent space exploration. Trigger with "scVI", "batch correction", "PeakVI", "totalVI", "CITE-seq analysis", "scvi-tools", or "deep learning single-cell".

17 other projects use a version of this.

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

4 rules. 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 13 edited versions we read keep these.

  • 3

    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. Distinctive:

    Ensure the data is properly formatted for scvi-tools:

    line 59
  2. Distinctive:

    Always use raw integer counts as input.

    line 208
  3. Very specific:

    Use early_stopping=True to prevent overfitting.

    line 211
  4. Distinctive:

    When comparing multiple integration methods, use scib-metrics for standardized benchmarking rather than relying on visual UMAP inspection …

    line 214

“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: Deep Learning for Single-Cell Analysis

Configure and run scvi-tools models for single-cell data integration, batch correction, differential expression, and multi-modal analysis. Generate reproducible Python code with proper model training, evaluation, and visualization.

Workflow

Step 1: Assess the Data and Select a Model

Inspect the input data to determine the appropriate model:

import scanpy as sc
import scvi

adata = sc.read_h5ad("input.h5ad")
print(adata)  # Check shape, layers, obs, var
print(adata.obs.columns.tolist())  # Available metadata
print(adata.layers.keys())  # Available count layers

Model selection guide:

  • scVI: Standard RNA integration and batch correction. Use when you have scRNA-seq counts from multiple batches/donors/experiments.
  • scANVI: Semi-supervised variant of scVI. Use when you have partial cell-type labels and want to transfer them to unlabeled cells.
  • totalVI: Joint RNA + protein analysis. Use for CITE-seq data with both gene expression and ADT (antibody-derived tag) counts.
  • PeakVI: Chromatin accessibility analysis. Use for scATAC-seq peak-by-cell matrices.
  • MULTIVI: Joint RNA + ATAC analysis. Use for multiome (10x Multiome) data or unpaired RNA + ATAC integration.
  • SOLO: Doublet detection. Use as a preprocessing step before integration.
  • DestVI: Spatial transcriptomics deconvolution. Use to map cell types onto spatial spots.

Step 2: Prepare the Data

Ensure the data is properly formatted for scvi-tools:

# Ensure raw counts are available
# scvi-tools requires raw integer counts, NOT normalized/log-transformed data
if "counts" in adata.layers:
    adata.layers["counts"] = adata.layers["counts"].copy()
else:
    # If adata.X contains raw counts:
    adata.layers["counts"] = adata.X.copy()

# Filter genes (standard scvi-tools preprocessing)
sc.pp.filter_genes(adata, min_counts=3)

# Select highly variable genes for model training
sc.pp.highly_variable_genes(
    adata,
    n_top_genes=4000,
    subset=False,
    layer="counts",
    flavor="seurat_v3",
    batch_key="batch"  # Account for batch when selecting HVGs
)

# Register the AnnData object with scvi-tools
scvi.model.SCVI.setup_anndata(
    adata,
    layer="counts",
    batch_key="batch",
    categorical_covariate_keys=["donor"],  # Optional additional covariates
    continuous_covariate_keys=["percent_mito"]  # Optional continuous covariates
)

Step 3: Train the Model

Configure training hyperparameters based on dataset size and complexity:

model = scvi.model.SCVI(
    adata,
    n_latent=30,         # Latent space dimensions (10-50, higher for complex data)
    n_layers=2,          # Neural network depth (1-3)
    gene_likelihood="zinb"  # Zero-inflated negative binomial (default, best for UMI data)
)

model.train(
    max_epochs=400,          # More epochs for larger datasets
    early_stopping=True,     # Stop when validation loss plateaus
    early_stopping_patience=20,
    train_size=0.9,          # 90% train, 10% validation
    batch_size=128           # Increase for large datasets (256, 512)
)

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

Training guidelines by dataset size:

  • <10K cells: 400 epochs, n_latent=10, batch_size=128
  • 10K-100K cells: 200 epochs, n_latent=30, batch_size=256
  • 100K-1M cells: 100 epochs, n_latent=50, batch_size=512

Step 4: Extract Results and Evaluate

# Get the latent representation for downstream analysis
adata.obsm["X_scVI"] = model.get_latent_representation()

# Compute neighbors and UMAP on the latent space
sc.pp.neighbors(adata, use_rep="X_scVI")
sc.tl.umap(adata)

# Visualize integration quality
sc.pl.umap(adata, color=["batch", "cell_type"], frameon=False)

# Quantitative integration metrics
from scib_metrics.benchmark import Benchmarker
# Use scib to compute batch correction (kBET, graph connectivity) and
# bio-conservation (NMI, ARI, ASW) metrics

For differential expression with scVI:

# Compare cell types across conditions using the model's posterior
de_results = model.differential_expression(
    groupby="condition",
    group1="treatment",
    group2="control",
)
# Filter significant DE genes
de_filtered = de_results[
    (de_results["is_de_fdr_0.05"] == True) &
    (de_results["lfc_mean"].abs() > 0.5)
]

Step 5: Save and Report

# Save the trained model for reproducibility
model.save("scvi_model/")

# Save the updated AnnData with latent representations
adata.write_h5ad("integrated_output.h5ad")

Output Format

## scvi-tools Analysis Report

**Model**: <scVI|scANVI|totalVI|PeakVI>
**Input**: <n_cells> cells x <n_genes> genes, <n_batches> batches
**Training**: <epochs> epochs, converged: <yes/no>

### Model Configuration
| Parameter          | Value    |
|--------------------|----------|
| n_latent           | 30       |
| n_layers           | 2        |
| gene_likelihood    | zinb     |
| batch_key          | batch    |

### Integration Quality
| Metric              | Score   |
|----------------------|---------|
| Batch mixing (kBET)  | <value> |
| Bio conservation (NMI)| <value>|

### Key Outputs
- Integrated embedding: `adata.obsm["X_scVI"]`
- Trained model: `scvi_model/`
- DE results: <n_significant> DE genes (FDR < 0.05, |LFC| > 0.5)

Examples

User: "I have 6 scRNA-seq samples from different donors with batch effects, integrate them" Action: Load h5ad, setup scVI with donor as batch_key, train with appropriate hyperparameters, evaluate integration with UMAP and scib metrics.

User: "Analyze my CITE-seq data with both RNA and protein" Action: Setup totalVI with RNA counts and protein counts, train joint model, extract protein-denoised values, compute protein-based differential expression.

User: "I have scATAC-seq peak matrix, find differentially accessible regions" Action: Setup PeakVI, train on the peak-by-cell matrix, extract latent space, perform differential accessibility between cell types.

Best Practices

  • Always use raw integer counts as input. If only normalized data is available, check whether a "counts" layer exists in the AnnData object.
  • Train on highly variable genes (2000-5000) for computational efficiency, but store the full gene set for downstream DE analysis.
  • Monitor the ELBO training curve. A noisy or non-converging curve suggests the learning rate or batch size needs adjustment.
  • Use early_stopping=True to prevent overfitting. The default patience of 20 epochs works for most datasets.
  • For datasets with strong biological covariates that should NOT be removed (e.g., sex, age), include them as categorical_covariate_keys rather than batch_key.
  • Save trained models with model.save() for reproducibility. Models can be loaded with scvi.model.SCVI.load().
  • When comparing multiple integration methods, use scib-metrics for standardized benchmarking rather than relying on visual UMAP inspection alone.

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.