nota-america/forgecat-agent-profiles / profiles/anthropics/knowledge-work-plugins/anthropics_knowledge-work-plugins_bio-research/for-forgecat/skills/scvi-tools
scvi-tools
VerifiedDeep 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.
| File | Kind | Size |
|---|---|---|
| LICENSE.txt | markdown | 10.0 KB |
| SKILL.md | skill md | 7.2 KB |
| references/atac_peakvi.md | markdown | 9.3 KB |
| references/batch_correction_sysvi.md | markdown | 10.2 KB |
| references/citeseq_totalvi.md | markdown | 10.1 KB |
| references/data_preparation.md | markdown | 6.2 KB |
| references/environment_setup.md | markdown | 6.3 KB |
| references/label_transfer.md | markdown | 10.2 KB |
| references/multiome_multivi.md | markdown | 8.9 KB |
| references/rna_velocity_velovi.md | markdown | 8.6 KB |
| references/scarches_mapping.md | markdown | 10.8 KB |
| references/scrna_integration.md | markdown | 9.6 KB |
| references/spatial_deconvolution.md | markdown | 11.2 KB |
| references/troubleshooting.md | markdown | 10.8 KB |
| scripts/cluster_embed.py | script | 6.3 KB |
| scripts/differential_expression.py | script | 6.7 KB |
| scripts/integrate_datasets.py | script | 6.9 KB |
| scripts/model_utils.py | script | 17.0 KB |
| scripts/prepare_data.py | script | 5.1 KB |
| scripts/train_model.py | script | 11.3 KB |
| scripts/transfer_labels.py | script | 7.2 KB |
| scripts/validate_adata.py | script | 11.9 KB |
references/multiome_multivi.md
View on GitHub# 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
```python
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)
```python
# 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
```python
# 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
```python
# 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
```python
# 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
```python
# 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
```python
# 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
```python
# 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
```python
# 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
```python
# 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
```python
# 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:
```python
# 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
```python
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
```python
# 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"
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |