185 lines
7.1 KiB
Markdown
185 lines
7.1 KiB
Markdown
---
|
|
name: scvi-tools
|
|
description: This skill should be used when working with single-cell omics data analysis using scvi-tools, including scRNA-seq, scATAC-seq, CITE-seq, spatial transcriptomics, and other single-cell modalities. Use this skill for probabilistic modeling, batch correction, dimensionality reduction, differential expression, cell type annotation, multimodal integration, and spatial analysis tasks.
|
|
---
|
|
|
|
# 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:
|
|
|
|
```python
|
|
# 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:
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
# 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:
|
|
|
|
```python
|
|
# 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
|
|
|
|
- **Workflows**: `references/workflows.md` contains common workflows, best practices, hyperparameter tuning, and GPU optimization
|
|
- **Model References**: Detailed documentation for each model category in the `references/` directory
|
|
- **Official Documentation**: https://docs.scvi-tools.org/en/stable/
|
|
- **Tutorials**: https://docs.scvi-tools.org/en/stable/tutorials/index.html
|
|
- **API Reference**: https://docs.scvi-tools.org/en/stable/api/index.html
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
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
|