scvi-tools 单细胞组学框架

要解决什么问题

单细胞实验往往带来批次效应、多模态数据不对齐（配对/非配对 CITE-seq、多组学）以及计数稀疏与零膨胀等问题；空间转录组还需要在组织切片上做解卷积或空间映射。传统流程里，降维、整合、差异表达和注释常常拆成多套启发式工具，难以在同一套概率框架下量化不确定性。

技能如何工作

scvi-tools 是基于 PyTorch / PyTorch Lightning 的 Python 框架，用变分推理和深度生成模型（VAE 类）对单细胞数据建模。模型按模态组织，但 API 模式一致：setup → train → 从训练结果中提取表征或统计量。

• scRNA-seq：scVI 无监督降维与批次校正；scANVI 半监督注释与整合；AUTOZI 处理零膨胀；VeloVI、contrastiveVI 等覆盖速度与扰动分析
• ATAC / 染色质：PeakVI、PoissonVI、scBasset 等（多数在 scvi.external）
• 多模态：totalVI / totalANVI（CITE-seq）、MultiVI（MuData 多组学）、DIAGVI（非配对对角整合，1.4.3）
• 空间：DestVI、Stereoscope、Tangram、scVIVA 等

与 scanpy 生态以 AnnData 为中心衔接：在 setup_anndata 中注册批次、供体等协变量；差异表达可走生成模型下的概率 DE（见技能内 references/differential-expression.md）。命名空间需区分：scvi.model（如 scVI、totalVI、MultiVI）与 scvi.external（如 VeloVI、Stereoscope、Solo）。

适用边界与注意点

• 模型期望原始计数，不要用归一化后的矩阵作为主输入；分析前通常需过滤低表达基因并选用高变基因
• 稳定版资料指向 scvi-tools 1.4.3，且要求 Python 3.12+（1.4 不再支持更旧 Python）
• 大矩阵训练应优先考虑 GPU；训练完成后应持久化模型，避免重复拟合
• 部分模型提供 JAX（如 JaxSCVI）或实验性 MLX 后端，与默认 PyTorch 路径在选型上需单独确认