scvi-tools

用途

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

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

主要能力

模型按数据模态组织：

单细胞 RNA-seq 分析：scVI（无监督降维与批次校正）、scANVI（半监督细胞类型注释与整合）、AUTOZI（零膨胀检测与建模）、VeloVI（RNA 速率分析）、contrastiveVI（扰动效应分离）。
染色质可及性（ATAC-seq）：PeakVI（基于峰值的 ATAC-seq 分析与整合）、PoissonVI（定量片段计数建模）、scBasset（带基序分析的深度学习方法）。
多模态与多组学整合：totalVI（CITE-seq 蛋白与 RNA 联合建模）、totalANVI（半监督 CITE-seq，即带细胞类型标签的 totalVI）、MultiVI（基于 MuData 的配对与非配对多组学整合）、MrVI（多分辨率跨样本分析）、DIAGVI（非配对单细胞数据集的对角整合，1.4.3 新增）。
空间转录组：DestVI（多分辨率空间去卷积）、Stereoscope（细胞类型去卷积）、Tangram（空间映射与整合）、scVIVA（细胞-环境关系分析）。
专门模态：MethylVI/MethylANVI（单细胞甲基化分析）、CytoVI（流式/质谱流式批次校正）、Solo（双细胞检测）、CellAssign（基于标记的细胞类型注释）。

命名空间说明：核心模型（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 下。

使用方式

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

# 1. 加载并预处理数据（AnnData 格式）
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. 向模型注册数据（指定层、协变量）
scvi.model.SCVI.setup_anndata(
    adata,
    layer="counts",  # 使用原始计数，而非对数归一化
    batch_key="batch",
    categorical_covariate_keys=["donor"],
    continuous_covariate_keys=["percent_mito"]
)

# 3. 创建并训练模型
model = scvi.model.SCVI(adata)
model.train()

# 4. 提取潜在表示与归一化值
latent = model.get_latent_representation()
normalized = model.get_normalized_expression(library_size=1e4)

# 5. 存入 AnnData 供下游分析
adata.obsm["X_scVI"] = latent
adata.layers["scvi_normalized"] = normalized

# 6. 使用 scanpy 进行下游分析
sc.pp.neighbors(adata, use_rep="X_scVI")
sc.tl.umap(adata)
sc.tl.leiden(adata)

差异表达分析示例：

de_results = model.differential_expression(
    groupby="cell_type",
    group1="TypeA",
    group2="TypeB",
    mode="change",  # 使用复合假设检验
    delta=0.25      # 最小效应量阈值
)

模型保存与加载：

# 保存模型
model.save("./model_directory", overwrite=True)

# 加载模型
model = scvi.model.SCVI.load("./model_directory", adata=adata)

批次校正与整合：

# 注册批次信息
scvi.model.SCVI.setup_anndata(adata, batch_key="study")

# 模型自动学习批次校正后的表示
model = scvi.model.SCVI(adata)
model.train()
latent = model.get_latent_representation()  # 已批次校正

关键设计原则

需要原始计数：模型期望未归一化的计数数据以获得最佳性能
统一 API：所有模型接口一致（setup → train → extract）
以 AnnData 为中心：与 scanpy 生态无缝集成
GPU 加速：自动利用可用 GPU
批次校正：通过协变量注册处理技术变异

理论基础

scvi-tools 构建于：变分推断（为可扩展贝叶斯推断提供近似后验分布）、深度生成模型（学习复杂数据分布的 VAE 架构）、摊销推断（跨细胞高效学习的共享神经网络）、概率建模（有原则的不确定性量化与统计检验）。

安装

需要 Python 3.12+（scvi-tools 1.4 已放弃更早版本）。

uv pip install scvi-tools
# GPU 支持
uv pip install "scvi-tools[cuda]"

如需可复现环境，可固定版本：uv pip install scvi-tools==1.4.3。

计算后端：训练默认使用 PyTorch（CPU/GPU/TPU）。部分模型提供 JAX 后端（scvi.model.JaxSCVI）和面向 Apple 芯片的实验性 MLX 后端（scvi.model.mlxSCVI）。

最佳实践

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

适用场景与限制

适用场景：单细胞 RNA-seq、ATAC-seq、多模态/多组学、空间转录组、甲基化、流式细胞术、RNA 速率等分析，以及差异表达、细胞类型注释、批次校正与整合、自定义概率模型构建。

限制与注意事项：模型需要原始计数数据；需注意基因组构建与标识符一致性；版本特定细节可能过时，应以所安装版本的官方文档为准；不得编造结果、参数、标识符、引用或统计量；不应超出统计支持范围解释生物学意义，并需报告多重检验校正；涉及花费金钱、占用共享 GPU 或云配额、触及个人或患者数据、或不可撤销的操作前应先询问。

附加资源

官方文档：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

技能介绍

用途