单细胞组学分析救星来了！scvi-tools批量校正+降维一套搞定，生信人后悔没早用🔥-Skill优仓

scvi-tools是什么？

做单细胞数据的同学应该都懂那种痛——批次效应、多模态整合、差异表达分析，每一步都能让人头秃。scvi-tools是一个基于PyTorch构建的Python框架，专门为单细胞基因组学设计的概率模型工具集，把变分推断和深度生成模型打包进来，覆盖scRNA-seq、scATAC-seq、CITE-seq、空间转录组等几乎所有主流单细胞数据类型。

核心功能

scvi-tools按数据模态把模型分得很清楚，用哪个场景找哪个模型，不用乱猜。

单细胞RNA-seq：scVI做无监督降维和批次校正，scANVI做半监督细胞类型注释，VeloVI分析RNA速率，contrastiveVI隔离扰动效应。
染色质可及性（ATAC-seq）：PeakVI做peak级别的整合分析，scBasset引入深度学习做motif分析。
多模态整合：totalVI联合建模CITE-seq的蛋白和RNA，MultiVI处理配对或非配对多组学数据，MrVI做跨样本多分辨率分析。
空间转录组：DestVI和Stereoscope做细胞类型反卷积，Tangram做空间映射，scVIVA分析细胞与微环境的关系。
特殊模态：MethylVI处理甲基化数据，CytoVI校正流式/质谱细胞仪批次效应，Solo检测双细胞，CellAssign做基于marker的细胞类型注释。

所有模型遵循统一的API设计：setup_anndata → train → extract，上手一个，其他的基本无缝切换。

适用平台

scvi-tools这个Skill完美适配当下主流AI编程助手。无论你用的是Cursor、GitHub Copilot、Claude Code、OpenAI Codex，还是Gemini Code Assist、文心快码、腾讯云CodeBuddy、华为云CodeArts，加载这个Skill之后，AI对scvi-tools的API调用方式、参数含义、模型选择逻辑的理解会直接上一个台阶。写单细胞分析代码时，补全更准，报错提示更到位，相当于给AI装了一个生信专项外挂。

实操代码示例

下面是一个完整的scVI工作流，从数据加载到下游聚类，核心步骤一目了然：

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)

# 注册数据，指定批次和协变量
scvi.model.SCVI.setup_anndata(
    adata,
    layer='counts',
    batch_key='batch',
    categorical_covariate_keys=['donor'],
    continuous_covariate_keys=['percent_mito']
)

# 训练模型
model = scvi.model.SCVI(adata)
model.train()

# 提取潜在表示
latent = model.get_latent_representation()
adata.obsm['X_scVI'] = latent

# 下游分析
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
)

优势分析

跟传统的Seurat或者手写批次校正流程比，scvi-tools的优势很实在。

概率建模：不是简单的线性校正，而是用变分自编码器学数据的真实分布，不确定性有量化依据。
统一接口：十几个模型共用一套API，换模型不用重学用法。
AnnData生态无缝衔接：输出直接存进AnnData，接scanpy的后续分析零摩擦。
GPU加速：大数据集自动调用GPU，训练速度比CPU快一个数量级。
多模态原生支持：不是靠外部拼接，而是模型层面的联合建模，整合效果更可靠。

应用场景

几个真实会遇到的场景：

多个测序批次的样本需要整合做联合分析，批次效应严重影响聚类结果，用scVI注册batch_key直接在潜在空间里校正。
有部分细胞有已知标注，想把标注迁移到未标注细胞，scANVI的半监督设计正好对口。
CITE-seq数据同时有RNA和蛋白表达，totalVI联合建模，两种模态互相增强，比单独分析信息量大得多。
空间转录组切片里想知道每个spot的细胞类型组成，DestVI做多分辨率反卷积，比简单的相关性方法靠谱。
数据集里怀疑有双细胞污染，Solo专门做这个，检测准确率在同类工具里属于第一梯队。

最佳实践

用scvi-tools踩过坑的人都知道，有几个点必须注意。

一定要用原始counts：模型内部有负二项分布的似然函数，输入log标准化数据会破坏统计假设，结果会很奇怪。
先过滤低质量基因：min_counts=3是个合理起点，噪声基因留着只会拖慢训练、干扰表示学习。
把已知技术因素都注册进去：donor、测序平台、线粒体比例这些，能加就加，模型会自动学着把它们从生物信号里剥离。
训练完立刻保存模型：model.save('./model_dir', overwrite=True)，单细胞数据集动辄几十万细胞，重新训练代价很高。
大数据集开GPU：训练时传入accelerator='gpu'，十万级细胞的数据集CPU训练可能要几个小时，GPU通常十几分钟搞定。
高变基因筛选：用n_top_genes=1200~3000范围内的高变基因训练，既保留信息又控制计算量，全基因训练在大多数场景下收益有限。