用途
scvi-tools 用于为单细胞组学数据拟合概率模型，覆盖 RNA 整合与注释、多模态整合、表观可及性、甲基化、流式细胞术、跨系统效应和 RNA 速率等任务。目标版本为 scvi-tools 1.5.1，发布于 2026 年 9 月 10 日，资料中的 API 已对照带标签源码与官方文档检查。
主要模型与输入要求
资料按任务列出模型类与必需输入：
- RNA 整合：scvi.model.SCVI，需要未归一化的 RNA 计数。
- RNA 注释：scvi.model.SCANVI，需要计数与部分标签。
- CITE-seq：scvi.model.TOTALVI，需要 RNA 与蛋白计数、细胞对齐。
- RNA + ATAC 整合：scvi.model.MULTIVI，需要已注册、模态表示对齐的 MuData。
- ATAC 可及性：scvi.model.PEAKVI，输入为细胞×峰值，二值或计数型可及性。
- 定量 ATAC：scvi.external.POISSONVI，输入为区域级片段计数。
- 甲基化：scvi.external.METHYLVI、METHYLANVI，需要包含甲基化与总覆盖计数的 MuData。
- 流式细胞术：scvi.external.CYTOVI，输入为变换后的蛋白强度。
- 大规模跨系统效应：scvi.external.SysVI，输入为归一化、对数变换后的表达。
- RNA 速率：scvi.external.VELOVI，输入为预处理后的 spliced/unspliced 丰度。
资料强调计数规则因模型而异：不要把原始 RNA 计数喂给 SysVI，也不要用比值替代甲基化覆盖度；同样不要通过对数归一化数据取指数来重建计数，应保留实测计数与预处理来源。其他参考模型分组包括 RNA 模型（AUTOZI、VELOVI、ContrastiveVI、CellAssign、SOLO、LinearSCVI、AmortizedLDA）、ATAC 模型（PEAKVI、POISSONVI、SCBASSET）、多模态模型（TOTALVI、TOTALANVI、MULTIVI、MRVI、DIAGVI）、空间模型（CondSCVI/DestVI、Stereoscope、Tangram、GIMVI、SCVIVA、RESOLVI）以及甲基化、流式、SysVI、Decipher 等专用模型。
版本边界方面：JAX 支持（包括 JaxSCVI）已在 1.5 中移除；scvi.model.mlxSCVI 仍是独立的可选 Apple Silicon 实现，PyTorch MPS 与 MLX 属于不同后端；空间模型与 DIAGVI 在 1.5.1 中仍可导入，但上游将后续维护指向 scVIVA-tools。
使用方式
资料给出的流程为：
- 确认模态、原始数据来源、唯一细胞/特征 ID、特征顺序、批次或样本元数据，以及预期的生物学比较。
- 在模型注册之前完成 QC 与特征选择。对计数层使用计数感知的 HVG 选择，并为后续分析保留全基因计数对象。
- 用对应模型的 setup_anndata 或 setup_mudata 注册确切的数据对象，然后创建并训练模型。Setup 是注册，不是归一化。
- 检查验证历史、留出拟合、种子稳定性、批次混合与已知生物学信号的保留。仅凭混合良好的 UMAP 不能验证整合效果。
- 提取表示或模型特定的归一化输出；保存模型、数据、所选特征顺序、软件版本、种子和训练参数。
示例 RNA 工作流假设 rna_counts.h5ad 的 .X 中为实测、未归一化计数，且 obs['batch'] 无缺失，代码包含计数有效性断言、保存 counts 层、过滤基因、选择高度可变基因、setup_anndata、训练 SCVI、提取潜表示、构建邻居图与 UMAP、Leiden 聚类以及模型保存。资料提示 seurat_v3 需要 scikit-misc，flavor='igraph' 的 Leiden 需要 igraph；极小或退化数据集可能使 HVG 局部回归失败，此时应降低特征选择目标并检查数据质量，而不是通过改动计数层来掩盖失败。
计数有效性不代表计数来源可靠。如果过滤后某个细胞所有表达被移除，应删除该细胞或在 setup 前修改特征选择。不要自动把 condition、tissue 或 donor 作为干扰协变量，因为它们可能编码正在研究的生物信号，混杂问题无法仅靠注册修复。注册与特征顺序、层和类别编码绑定；过滤必须在 setup 前完成。若训练对象改变，需要重新注册并初始化新模型；对已训练参考应使用专门的查询映射方法，不要就地修改其注册表。
输出与差异表达
资料展示了 get_normalized_expression（可能得到稠密的细胞×基因矩阵）与 differential_expression 的用法，后者需要先存在 cell_type 分组。资料说明 DE 分数是后验模型量，不是 p 值；细胞级 DE 不同于生物学重复的伪批量 DE。持久化、参考映射、压缩、学习率、指标方向、自定义加载器和硬件相关内容可查阅 workflows，理论参考解释了解读不确定性、零膨胀和反事实解码所需的假设。
安装与验证
资料建议使用独立环境，避免与约束不兼容的包混装，示例命令使用 uv 创建 Python 3.13 环境并安装 scvi-tools==1.5.1、scanpy==1.12.4 与 igraph；Windows 下使用 .venv-scvi/Scripts/python.exe。GPU 工作前应先选择适合硬件的 PyTorch 构建；cuda/cuda13 额外项安装额外 CUDA 依赖，CPU 或 Apple MPS 不需要，且不保证驱动可用。专用额外项包括 regseq、diagvi、interpretability、dataloaders 与 metal，不建议默认安装全部额外项。长训练前应在实际环境中检查小规模 CPU 拟合与有限输出；简短合成拟合验证的是机制，而非收敛或生物学有效性。可选数据集加载器和基因组/模体辅助工具可能下载数据。该本地工作流不包含托管推理端点、认证或分页。
限制
资料明确说明，长时间训练、硬件特定路径和其他专用工作流仍属示例性质，相关检查不能确立收敛性或生物学有效性。除已列出的模型、输入规则、流程和安装方式外，其他功能、收费、价格、平台与效果资料暂未提供。