scvi-tools

scvi-tools

概述

scvi-tools 是一个用于单细胞基因组学概率模型的综合 Python 框架。它基于 PyTorch 和 PyTorch Lightning 构建，使用变分推断提供深度生成模型，用于分析多种单细胞数据模态。当前稳定版本：scvi-tools 1.4.3（2026 年 5 月）。

**模型命名空间很重要：**核心模型（scVI、scANVI、totalVI、MultiVI、PeakVI、AUTOZI、CondSCVI、DestVI、LinearSCVI、AmortizedLDA、JaxSCVI）位于 scvi.model 下。大多数其他模型（VeloVI、contrastiveVI、CellAssign、PoissonVI、scBasset、MrVI、MethylVI/MethylANVI、CytoVI、SysVI、Decipher、gimVI、scVIVA、ResolVI、Stereoscope、Solo、totalANVI、DIAGVI）位于 scvi.external 下。参考文件会为每个模型指定正确的命名空间。

何时使用此技能

在以下情况下使用此技能：

• 分析单细胞 RNA-seq 数据（降维、批次校正、整合）
• 处理单细胞 ATAC-seq 或染色质可及性数据
• 整合多模态数据（CITE-seq、多组学、配对/非配对数据集）
• 分析空间转录组数据（反卷积、空间映射）
• 对单细胞数据进行差异表达分析
• 执行细胞类型注释或迁移学习任务
• 处理专用单细胞模态（甲基化、流式细胞术、RNA 速度）
• 为单细胞分析构建自定义概率模型

核心功能

scvi-tools 提供按数据模态组织的模型：

1. 单细胞 RNA-seq 分析

用于表达分析、批次校正和整合的核心模型。参见 references/models-scrna-seq.md：

• scVI：无监督降维和批次校正
• scANVI：半监督细胞类型注释与整合
• AUTOZI：零膨胀检测与建模
• VeloVI：RNA 速度分析
• contrastiveVI：分离扰动效应

2. 染色质可及性（ATAC-seq）

用于分析单细胞染色质数据的模型。参见 references/models-atac-seq.md：

• PeakVI：基于峰的 ATAC-seq 分析与整合
• PoissonVI：定量片段计数建模
• scBasset：结合基序分析的深度学习方法

3. 多模态与多组学整合

对多种数据类型进行联合分析。参见 references/models-multimodal.md：

• totalVI：联合建模 CITE-seq 蛋白质与 RNA
• totalANVI：半监督 CITE-seq（带细胞类型标签的 totalVI）
• MultiVI：配对和非配对多组学整合（基于 MuData）
• MrVI：多分辨率跨样本分析
• DIAGVI：非配对单细胞数据集的对角线整合（在 1.4.3 中新增）

4. 空间转录组

空间分辨转录组分析。参见 references/models-spatial.md：

• DestVI：多分辨率空间反卷积
• Stereoscope：细胞类型反卷积
• Tangram：空间映射与整合
• scVIVA：细胞与环境关系分析

5. 专用模态

其他专用分析工具。参见 references/models-specialized.md：

• MethylVI/MethylANVI：单细胞甲基化分析
• CytoVI：流式/质谱细胞术批次校正
• Solo：双细胞检测
• CellAssign：基于标记的细胞类型注释

典型工作流

所有 scvi-tools 模型都遵循一致的 API 模式：

# 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)

关键设计原则：

• 需要原始计数：为获得最佳性能，模型需要未归一化的计数数据
• 统一 API：所有模型采用一致的接口（设置 → 训练 → 提取）
• 以 AnnData 为中心：与 scanpy 生态系统无缝集成
• GPU 加速：自动使用可用的 GPU
• 批次校正：通过协变量注册处理技术变异

常见分析任务

差异表达

使用学习到的生成模型进行概率差异表达分析：

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
)

详细的方法和解读请参阅 references/differential-expression.md。

模型持久化

保存和加载训练好的模型：

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

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

批次校正与整合

整合跨批次或跨研究的数据集：

# 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

理论基础

scvi-tools 基于以下内容构建：

• 变分推断：近似后验分布，以实现可扩展的贝叶斯推断
• 深度生成模型：通过 VAE 架构学习复杂的数据分布
• 摊销推断：通过共享神经网络，高效地学习不同细胞的数据
• 概率建模：以可靠的方式量化不确定性并进行统计检验

数学框架的详细背景请参阅 references/theoretical-foundations.md。

其他资源

• 工作流：references/workflows.md 包含常见工作流、最佳实践、超参数调优和 GPU 优化
• 模型参考：references/ 目录中包含各模型类别的详细文档
• 官方文档：https://docs.scvi-tools.org/en/stable/
• 教程：https://docs.scvi-tools.org/en/stable/tutorials/index.html
• API 参考：https://docs.scvi-tools.org/en/stable/api/index.html

安装

需要 Python 3.12+（scvi-tools 1.4 已不再支持更早的版本）。

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

为确保环境可复现，请固定版本：uv pip install scvi-tools==1.4.3。

**计算后端：**训练默认使用 PyTorch（CPU/GPU/TPU）。部分模型还可使用 JAX 后端 （scvi.model.JaxSCVI）以及适用于 Apple silicon 的实验性 MLX 后端 （scvi.model.mlxSCVI）。

最佳实践

1. 使用原始计数：始终向模型提供未归一化的计数数据
2. 筛选基因：分析前移除低计数基因（例如，min_counts=3）
3. 注册协变量：在 setup_anndata 中包含已知的技术因素（批次、供体等）
4. 特征选择：使用高变基因以提升性能
5. 保存模型：始终保存训练好的模型，避免重新训练
6. 使用 GPU：为大型数据集启用 GPU 加速（accelerator="gpu"）
7. 集成 Scanpy：将输出存储在 AnnData 对象中，以便进行下游分析

Agent 操作流程

1. 检查环境。 确认工具版本、参考基因组/注释版本和输入格式（FASTQ、BAM、VCF、h5ad）。
2. 明确输入。 根据数据或用户说明确认格式、标识符和参数。对于任何会影响结果的值，应询问，而不是猜测。
3. 先运行小规模版本。 先在小规模子集上运行流程（一个样本、一条染色体、几千个细胞）。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 在解读结果前，检查 QC 指标、样本身份、基因组版本一致性和批次效应。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及仍有哪些不确定之处。

如果出现这种情况	请这样做
输入之间的基因组版本或标识符不匹配	停止并统一（liftover、ID 映射）后再继续。
这些说明中提到的函数、标志或端点在已安装版本中不存在	查阅已安装版本自己的文档（help()、--help、官方文档），调整做法并告知用户。切勿编造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所作假设。

完整性规则

• 切勿伪造结果、参数、标识符、引用或统计数据。如果无法运行或验证某项内容，请如实说明。
• 不要解读超出统计结果支持范围的生物学意义；报告多重检验校正。
• 此处的版本特定细节可能已过时：请对照已安装版本的官方文档加以确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，须事先征求同意。

相关技能

• scanpy：标准的单细胞 RNA-seq 分析流程。
• anndata：用于单细胞分析中带注释矩阵的数据结构。
• cellxgene-census：通过编程方式查询 CZ CELLxGENE Census，获取带版本信息的公共单细胞和空间转录组数据。