Skip to content

nota-america/forgecat-agent-profiles / profiles/anthropics/knowledge-work-plugins/anthropics_knowledge-work-plugins_bio-research/for-claude/.claude/skills/scvi-tools

scvi-tools

Verified

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.

FileKindSize
LICENSE.txtmarkdown10.0 KB
SKILL.mdskill md7.3 KB
references/atac_peakvi.mdmarkdown9.3 KB
references/batch_correction_sysvi.mdmarkdown10.2 KB
references/citeseq_totalvi.mdmarkdown10.1 KB
references/data_preparation.mdmarkdown6.2 KB
references/environment_setup.mdmarkdown6.3 KB
references/label_transfer.mdmarkdown10.2 KB
references/multiome_multivi.mdmarkdown8.9 KB
references/rna_velocity_velovi.mdmarkdown8.6 KB
references/scarches_mapping.mdmarkdown10.8 KB
references/scrna_integration.mdmarkdown9.6 KB
references/spatial_deconvolution.mdmarkdown11.2 KB
references/troubleshooting.mdmarkdown10.8 KB
scripts/cluster_embed.pyexecutablescript6.3 KB
scripts/differential_expression.pyexecutablescript6.7 KB
scripts/integrate_datasets.pyexecutablescript6.9 KB
scripts/model_utils.pyexecutablescript17.0 KB
scripts/prepare_data.pyexecutablescript5.1 KB
scripts/train_model.pyexecutablescript11.3 KB
scripts/transfer_labels.pyexecutablescript7.2 KB
scripts/validate_adata.pyexecutablescript11.9 KB

references/environment_setup.md

View on GitHub
# Environment Setup for scvi-tools

This reference covers installation and environment configuration for scvi-tools.

## Installation Options

### Option 1: Conda Environment (Recommended)

```bash
# Create environment with GPU support
conda create -n scvi-env python=3.10
conda activate scvi-env

# Install scvi-tools
pip install scvi-tools

# For GPU acceleration (recommended for large datasets)
pip install torch --index-url https://download.pytorch.org/whl/cu118

# Common dependencies
pip install scanpy leidenalg
```

### Option 2: Pip Only

```bash
# Create virtual environment
python -m venv scvi-env
source scvi-env/bin/activate  # Linux/Mac
# scvi-env\Scripts\activate   # Windows

# Install
pip install scvi-tools scanpy
```

### Option 3: With Spatial Analysis Support

```bash
conda create -n scvi-spatial python=3.10
conda activate scvi-spatial

pip install scvi-tools scanpy squidpy
```

### Option 4: With MuData Support (Multiome)

```bash
pip install scvi-tools mudata muon
```

## Verify Installation

```python
import scvi
import torch
import scanpy as sc

print(f"scvi-tools version: {scvi.__version__}")
print(f"scanpy version: {sc.__version__}")
print(f"PyTorch version: {torch.__version__}")
print(f"GPU available: {torch.cuda.is_available()}")

if torch.cuda.is_available():
    print(f"GPU device: {torch.cuda.get_device_name(0)}")
    print(f"GPU memory: {torch.cuda.get_device_properties(0).total_memory / 1e9:.1f} GB")
```

## GPU Configuration

### Check CUDA Version

```bash
nvidia-smi
nvcc --version
```

### PyTorch CUDA Versions

| CUDA Version | PyTorch Install Command |
|--------------|------------------------|
| CUDA 11.8 | `pip install torch --index-url https://download.pytorch.org/whl/cu118` |
| CUDA 12.1 | `pip install torch --index-url https://download.pytorch.org/whl/cu121` |
| CPU only | `pip install torch --index-url https://download.pytorch.org/whl/cpu` |

### Memory Management

```python
import torch

# Clear GPU cache between models
torch.cuda.empty_cache()

# Monitor memory usage
print(f"Allocated: {torch.cuda.memory_allocated() / 1e9:.2f} GB")
print(f"Cached: {torch.cuda.memory_reserved() / 1e9:.2f} GB")
```

## Common Issues

| Issue | Cause | Solution |
|-------|-------|----------|
| `CUDA out of memory` | GPU memory exhausted | Reduce batch_size, use smaller model |
| `No GPU detected` | CUDA not installed | Install CUDA toolkit matching PyTorch |
| `Version mismatch` | PyTorch/CUDA incompatibility | Reinstall PyTorch with correct CUDA version |
| `Import error scvi` | Missing dependencies | `pip install scvi-tools[all]` |

## Jupyter Setup

```bash
# Install Jupyter kernel
pip install ipykernel
python -m ipykernel install --user --name scvi-env --display-name "scvi-tools"

# For interactive plots
pip install matplotlib seaborn
```

## Recommended Package Versions

For reproducibility, pin versions:

```bash
pip install \
    scvi-tools>=1.0.0 \
    scanpy>=1.9.0 \
    anndata>=0.9.0 \
    torch>=2.0.0
```

## Version Compatibility Guide

### scvi-tools 1.x vs 0.x API Changes

The 1.x release introduced breaking changes. Key differences:

| Operation | 0.x API (deprecated) | 1.x API (current) |
|-----------|---------------------|-------------------|
| Setup data | `scvi.data.setup_anndata(adata, ...)` | `scvi.model.SCVI.setup_anndata(adata, ...)` |
| Register data | `scvi.data.register_tensor_from_anndata(...)` | Built into `setup_anndata` |
| View setup | `scvi.data.view_anndata_setup(adata)` | `scvi.model.SCVI.view_anndata_setup(adata)` |

### Migration from 0.x to 1.x

```python
# OLD (0.x) - DEPRECATED
import scvi
scvi.data.setup_anndata(adata, layer="counts", batch_key="batch")
model = scvi.model.SCVI(adata)

# NEW (1.x) - CURRENT
import scvi
scvi.model.SCVI.setup_anndata(adata, layer="counts", batch_key="batch")
model = scvi.model.SCVI(adata)
```

### Model-Specific Setup (1.x)

Each model has its own setup method:

```python
# scVI
scvi.model.SCVI.setup_anndata(adata, layer="counts", batch_key="batch")

# scANVI
scvi.model.SCANVI.setup_anndata(adata, layer="counts", batch_key="batch", labels_key="cell_type")

# totalVI
scvi.model.TOTALVI.setup_anndata(adata, layer="counts", protein_expression_obsm_key="protein")

# MultiVI (uses MuData)
scvi.model.MULTIVI.setup_mudata(mdata, rna_layer="counts", atac_layer="counts")

# PeakVI
scvi.model.PEAKVI.setup_anndata(adata, batch_key="batch")

# veloVI
scvi.external.VELOVI.setup_anndata(adata, spliced_layer="spliced", unspliced_layer="unspliced")
```

### Minimum Version Requirements

| Package | Minimum Version | Notes |
|---------|-----------------|-------|
| scvi-tools | 1.0.0 | Required for current API |
| scanpy | 1.9.0 | HVG selection improvements |
| anndata | 0.9.0 | Improved MuData support |
| torch | 2.0.0 | Performance improvements |
| mudata | 0.2.0 | Required for MultiVI |
| scvelo | 0.2.5 | Required for veloVI |

### Check Your Versions

```python
import scvi
import scanpy as sc
import anndata
import torch

print(f"scvi-tools: {scvi.__version__}")
print(f"scanpy: {sc.__version__}")
print(f"anndata: {anndata.__version__}")
print(f"torch: {torch.__version__}")

# Check if using 1.x API
if hasattr(scvi.model.SCVI, 'setup_anndata'):
    print("Using scvi-tools 1.x API")
else:
    print("WARNING: Using deprecated 0.x API - please upgrade")
```

### Known Compatibility Issues

| Issue | Affected Versions | Solution |
|-------|-------------------|----------|
| `setup_anndata` not found | scvi-tools < 1.0 | Upgrade to 1.0+ |
| MuData errors | mudata < 0.2 | `pip install mudata>=0.2.0` |
| CUDA version mismatch | Any | Reinstall PyTorch for your CUDA |
| numpy 2.0 issues | Early 2024 builds | `pip install numpy<2.0` |

### Upgrading scvi-tools

```bash
# Upgrade to latest
pip install --upgrade scvi-tools

# Upgrade all dependencies
pip install --upgrade scvi-tools scanpy anndata torch

# If you have issues, clean install
pip uninstall scvi-tools
pip cache purge
pip install scvi-tools
```

## Testing Installation

```python
# Quick test with sample data
import scvi
import scanpy as sc

# Load test dataset
adata = scvi.data.heart_cell_atlas_subsampled()
print(f"Loaded test data: {adata.shape}")

# Setup and create model (quick test)
scvi.model.SCVI.setup_anndata(adata, layer="counts", batch_key="cell_source")
model = scvi.model.SCVI(adata, n_latent=10)
print("Model created successfully")

# Quick training test (1 epoch)
model.train(max_epochs=1)
print("Training works!")
```
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall