scvi-tools 单细胞深度学习技能指南模型选型、数据准备与端到端分析流水线【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins导读本文基于 knowledge-work-plugins 仓库中 bio-research/skills/scvi-tools/SKILL.md 技能文档系统讲解 scvi-tools 在单细胞组学分析中的完整实战方案从 scVI/scANVI 批次效应校正与数据整合、totalVI/PeakVI/MultiVI 多模态分析到 DestVI 空间去卷积、veloVI RNA 速率与 scArches 参考图谱映射。读完本文你将掌握如何根据数据类型快速选择合适的概率模型、如何正确准备 raw counts 数据、如何使用仓库提供的 7 个 CLI 脚本与model_utils.py工具函数搭建端到端流水线以及常见训练与数据格式问题的排查思路。模型选择指南八种模型覆盖单细胞分析全景scvi-tools 是一套面向单细胞基因组学的概率模型probabilistic model深度学习框架其核心思想是用变分自编码器VAE学习去除批次效应的共享隐空间。SKILL.md 提供了清晰的模型选型表涵盖从经典 scRNA-seq 到多模态与空间转录组的主流场景数据类型模型核心用途scRNA-seqscVI无监督整合、差异表达、数据填补scRNA-seq 标签scANVI标签迁移、半监督整合CITE-seqRNA蛋白totalVI多模态整合、蛋白信号去噪scATAC-seqPeakVI染色质开放性分析MultiomeRNAATACMultiVI联合模态分析空间 scRNA 参考DestVI细胞类型去卷积RNA velocityveloVI转录动力学分析跨技术平台sysVI系统级批次校正选型经验无标签的探索性整合优先选 scVI存在部分或完整细胞类型标签时选 scANVI半监督方式能更好地保留生物学变异CITE-seq 数据在adata.obsm中存在蛋白表达矩阵时选 totalVIscATAC-seq 由于特征数量大峰数量动辄超过 10 万且为二值开放状态选 PeakVI 更合适。使用技能文档的标准化流程SKILL.md 将使用流程总结为五步根据上面的模型/工作流表格确定要使用的模型阅读对应的 reference 文件获取详细步骤与代码例如 scrna_integration.md直接复用scripts/目录下的脚本避免重复编写常见代码遇到安装或 GPU 问题查阅 environment_setup.md遇到调试问题查阅 troubleshooting.md。技能触发条件包括用户提到 scVI、scANVI、totalVI、PeakVI、MultiVI、DestVI、veloVI、sysVI、scArches、变分自编码器VAE、批次校正、数据整合、多模态、CITE-seq、multiome、参考图谱映射reference mapping、隐空间等关键词。SKILL.md 的完整技能描述位于文件头部 YAML frontmatterbio-research/skills/scvi-tools/SKILL.mdAgent 可通过 description 字段自动识别何时调用本技能。工作流参考文件地图SKILL.md 为每个分析方向都配了独立的参考文档形成完整的知识体系工作流参考文件说明环境搭建environment_setup.md安装、GPU、版本信息数据准备data_preparation.md为任意模型格式化数据scRNA 整合scrna_integration.mdscVI/scANVI 批次校正ATAC-seq 分析atac_peakvi.mdPeakVI 染色质开放性CITE-seq 分析citeseq_totalvi.mdtotalVI 蛋白RNAMultiome 分析multiome_multivi.mdMultiVI RNAATAC空间去卷积spatial_deconvolution.mdDestVI 空间分析标签迁移label_transfer.mdscANVI 参考图谱映射scArches 映射scarches_mapping.md查询集到参考集映射批次校正batch_correction_sysvi.md高级批次方法RNA 速率rna_velocity_velovi.mdveloVI 动力学故障排查troubleshooting.md常见问题与解法关键要求scvi-tools 输入数据的三个铁律SKILL.md 明确了使用任何 scvi-tools 模型前必须满足的三条硬性要求这也是新手最容易踩坑的地方1. 必须使用原始整数 countsscvi-tools 的概率模型基于原始计数分布负二项等建模绝不接受归一化或 log 变换后的数据。标准做法是在任何归一化之前把原始计数存入 layeradata.layers[counts] adata.X.copy() # Before normalization scvi.model.SCVI.setup_anndata(adata, layercounts)2. 选择 2000~4000 个高变基因HVGHVG 选择既能过滤噪声基因、提升生物学信号也能大幅降低训练开销。多批次数据必须使用 batch-aware 的seurat_v3flavorsc.pp.highly_variable_genes(adata, n_top_genes2000, batch_keybatch, layercounts, flavorseurat_v3) adata adata[:, adata.var[highly_variable]].copy()3. 通过 batch_key 声明批次信息批次信息是 scVI 类模型校正混淆因素的先验必须通过setup_anndata注册scvi.model.SCVI.setup_anndata(adata, layercounts, batch_keybatch)深入setup_anndata 的完整参数谱系仓库的 data_preparation.md 进一步扩展了setup_anndata的用法——除layer与batch_key外还可以注册scANVI 标签labels_keycell_type可含 Unknown 表示未标注细胞半监督连续协变量continuous_covariate_keys[percent_mito, n_genes]用于回归掉线粒体比例等连续混杂分类协变量categorical_covariate_keys[donor, technology]用于整合供体、测序技术等分类混杂totalVI 蛋白数据protein_expression_obsm_keyprotein_expression蛋白计数矩阵存于adata.obsmMultiVI 多模态使用scvi.model.MULTIVI.setup_mudata(mdata, rna_layercounts, batch_keybatch, modalities{rna: rna, accessibility: atac})要求 MuData 格式。注意1.x API 中setup_anndata是模型类的方法scvi.model.SCVI.setup_anndata(...)而 0.x 旧 API 是scvi.data.setup_anndata(...)已废弃详情见 environment_setup.md。CLI 脚本七个开箱即用的流水线组件SKILL.md 提供了 7 个模块化 CLI 脚本可串联使用也可独立修改。它们位于 bio-research/skills/scvi-tools/scripts脚本用途示例用法prepare_data.pyQC、过滤、HVG 选择python scripts/prepare_data.py raw.h5ad prepared.h5ad --batch-key batchtrain_model.py训练任意 scvi-tools 模型python scripts/train_model.py prepared.h5ad results/ --model scvicluster_embed.pyNeighbors、UMAP、Leidenpython scripts/cluster_embed.py adata.h5ad results/differential_expression.py差异表达分析python scripts/differential_expression.py model/ adata.h5ad de.csv --groupby leidentransfer_labels.pyscANVI 标签迁移python scripts/transfer_labels.py ref_model/ query.h5ad results/integrate_datasets.py多数据集整合python scripts/integrate_datasets.py results/ data1.h5ad data2.h5advalidate_adata.py检查数据兼容性python scripts/validate_adata.py data.h5ad --batch-key batch端到端示例工作流SKILL.md 给出了从校验到差异表达的完整命令链也是实际项目中最常用的起点# 1. Validate input data校验输入数据 python scripts/validate_adata.py raw.h5ad --batch-key batch --suggest # 2. Prepare data (QC, HVG selection)准备数据QC、HVG 选择 python scripts/prepare_data.py raw.h5ad prepared.h5ad --batch-key batch --n-hvgs 2000 # 3. Train model训练模型 python scripts/train_model.py prepared.h5ad results/ --model scvi --batch-key batch # 4. Cluster and visualize聚类与可视化 python scripts/cluster_embed.py results/adata_trained.h5ad results/ --resolution 0.8 # 5. Differential expression差异表达 python scripts/differential_expression.py results/model results/adata_clustered.h5ad results/de.csv --groupby leiden脚本源码级解析validate_adata.py训练前的体检报告。该脚本validate_adata.py的核心是validate_for_scvi()函数通过ValidationResult数据结构输出 PASSED/FAILED 状态、错误、警告与建议四类信息。检查项包括数据是否含整数raw counts 判定np.allclose(X_check, X_check.astype(int))、是否存在负值/NaN/Inf、数据取值范围最大值小于 10 提示可能已被 log 或归一化、稀疏度、batch 列是否存在及批次细胞数是否过少50 提示合并、标签列是否存在及稀有类型30 细胞提示可能学不好、HVG 数量是否落在 2000~4000 最佳区间等。--suggest参数还会结合数据特征自动推荐模型。prepare_data.py标准化数据准备。该脚本prepare_data.py支持的参数包括--batch-keybatch-aware HVG 选择、--n-hvgs默认 2000、--min-genes每细胞最少基因数默认 200、--max-genes每细胞最多基因数默认 5000、--max-mito线粒体比例上限默认 20%、--min-cells每基因最少细胞数默认 3、--no-filter跳过 QC 过滤适用于已质检数据。内部先做细胞/基因过滤再把原始计数存入layers[counts]最后执行 HVG 选择并子集化。线粒体基因检测复用model_utils.get_mito_genes()同时兼容人类MT-前缀与小鼠mt-/Mt-前缀命名。train_model.py六大模型一键训练。该脚本train_model.py通过MODELS字典注册了scvi、scanvi、totalvi、peakvi、velovi、multivi六种模型统一参数包括--model、--batch-key、--labels-keyscANVI 必需、--protein-keytotalVI 蛋白 obsm 键默认protein_expression、--n-latent默认 30、--n-layers默认 2、--max-epochs默认 200。几个实现细节值得注意scANVI 采用两阶段训练train_scanvi先完整训练 scVI再用SCANVI.from_scvi_model(scvi_model, labels_key..., unlabeled_categoryUnknown)初始化并微调max_epochs // 4个 epoch比从头训练收敛更快PeakVI 自动二值化若adata.X.max() 1脚本会把数据转换为 0/1 的开放/关闭状态(adata.X 0).astype(np.float32)veloVI 自动预处理若缺少Ms/Mu层脚本会调用 scvelo 的filter_and_normalize与moments生成 spliced/unspliced 平滑层veloVI 位于scvi.external.VELOVI而非scvi.model输出X_veloVI隐表示、velocity层与latent_time_meanMultiVI 要求 MuData.h5mu文件需mudata包且须包含rna与atac两个模态。cluster_embed.py隐空间的下游分析。该脚本cluster_embed.py自动按优先级X_scANVI → X_scVI → X_totalVI → X_PeakVI → X_MultiVI探测隐表示找不到时回退到 PCA。参数--n-neighbors默认 15、--resolutionLeiden 分辨率默认 1.0、--min-distUMAP 最小距离默认 0.3。输出adata_clustered.h5ad、umap_clusters.png最多 6 个子图自动识别 batch/labels/predicted 列与cluster_counts.csv。differential_expression.py生成模型驱动的 DE。该脚本differential_expression.py调用模型的differential_expression()方法天然校正批次效应。支持单组对比--group1/--group2缺省时 group2 为其余所有细胞或一键对全部分组做 one-vs-rest 分析--n-genes可按lfc_mean取每组前 N 个基因--plot生成火山图红色标记is_de_fdr_0.05显著基因纵轴优先用 Bayes Factor。其底层在 model_utils.get_marker_genes() 中有对应实现筛选阈值为 FDR0.05 且lfc_mean 0.5。transfer_labels.py参考图谱映射与标签迁移。该脚本transfer_labels.py实现了 scArches 工作流的核心三要素先做参考基因与查询基因的交集检查重叠 50% 时告警再用SCANVI.prepare_query_anndata()对齐基因空间最后SCANVI.load_query_data()加载查询模型并微调。输出predicted_cell_type、prediction_confidencesoft 预测最大值与confident_prediction置信度 ≥--confidence阈值默认 0.5并生成predictions.png、predictions.csv与query_annotated.h5ad。Python 工具库model_utils.py 的九大函数SKILL.md 列出了 model_utils.py 中可直接 import 复用的函数适合在 Jupyter 或自定义脚本中构建更灵活的工作流函数用途prepare_adata()数据准备QC、HVG、layer 设置参数含batch_key、n_top_genes、min_genes、max_genes、max_mito_pct、min_cells、copytrain_scvi()训练 scVI 或 scANVI提供labels_key时自动走 scANVI 两阶段路线evaluate_integration()计算整合指标细胞类型 silhouette、批次 silhouette、批次混合度get_marker_genes()用 scVI 差异表达提取标记基因save_results()保存模型、数据、UMAP 图auto_select_model()根据数据特征推荐最优模型quick_clustering()Neighbors UMAP Leiden 一站式聚类compare_integrations()用标准指标比较多个整合嵌入plot_training_history()可视化训练收敛曲线ELBO 与重建损失整合质量评估的实现细节evaluate_integration()model_utils.py给出了一套不依赖额外包即可计算的量化指标silhouette_label基于细胞类型标签的轮廓系数越高说明细胞类型分离越好生物学保守性silhouette_batch基于批次标签的轮廓系数越低说明批次混合越好batch_mixing对每个细胞统计其 50 个最近邻中覆盖的独特批次占所有批次的比例并取平均衡量局部混合程度。compare_integrations()在此基础上还计算integration_score silhouette_label - silhouette_batch可横向比较 PCA、scVI、scANVI 等不同嵌入的整合质量更严谨的评估则可参考 scrna_integration.md 中基于scib-metrics的Benchmarker基准测试。快速决策树按需直达正确模型SKILL.md 提供了可落地的决策树是模型选型的核心工具完整逻辑如下Need to integrate scRNA-seq data?需要整合 scRNA-seq 数据 ├── Have cell type labels? → scANVI (references/label_transfer.md) └── No labels? → scVI (references/scrna_integration.md) Have multi-modal data?有多模态数据 ├── CITE-seq (RNA protein)? → totalVI (references/citeseq_totalvi.md) ├── Multiome (RNA ATAC)? → MultiVI (references/multiome_multivi.md) └── scATAC-seq only? → PeakVI (references/atac_peakvi.md) Have spatial data?有空间数据 └── Need cell type deconvolution? → DestVI (references/spatial_deconvolution.md) Have pre-trained reference model?有预训练参考模型 └── Map query to reference? → scArches (references/scarches_mapping.md) Need RNA velocity?需要 RNA 速率 └── veloVI (references/rna_velocity_velovi.md) Strong cross-technology batch effects?跨技术批次效应强 └── sysVI (references/batch_correction_sysvi.md)这条决策树与auto_select_model()的启发式逻辑相互印证后者会检查obsm中是否存在protein_expression→ totalVI、layers 中是否存在spliced/unspliced→ veloVI、特征数是否超 10 万→ 疑似 ATAC 峰PeakVI、以及obs中是否含 cell/type/label 类列与 batch/sample 类列→ 决定 scANVI 还是 scVI见 model_utils.py。环境安装与版本要求完整的安装指导见 environment_setup.md核心要点# 推荐方式Conda 环境 GPU 支持 conda create -n scvi-env python3.10 conda activate scvi-env pip install scvi-tools # GPU 加速需按 CUDA 版本选择如 CUDA 11.8 pip install torch --index-url https://download.pytorch.org/whl/cu118 # 常用依赖 pip install scanpy leidenalg按分析类型可选择附加组件空间分析加squidpyMultiome 加mudata muon。推荐版本底线为scvi-tools1.0.0、scanpy1.9.0、anndata0.9.0、torch2.0.0MultiVI 需mudata0.2.0veloVI 需scvelo0.2.5。1.x 与 0.x 的核心 API 差异在于setup_anndata/view_anndata_setup均从scvi.data迁移到了模型类方法。安装后可用scvi.data.heart_cell_atlas_subsampled()加载测试数据、以 1 个 epoch 快速验证训练链路是否通畅。常见问题速查与排查策略仓库的 troubleshooting.md 汇总了跨模型的高频问题此处提炼最核心的对照表症状可能原因快速修复X should contain integersX 中是归一化数据setup_anndata中指定layercounts或从adata.raw恢复原始计数CUDA out of memoryGPU 显存不足调小batch_size如 64、减小模型、先子集到 HVG、torch.cuda.empty_cache()训练 loss 为 NaN数据或学习率问题检查/过滤全零细胞与基因开启早停批次混合不佳共享特征过少增加 HVG 数量如 4000、检查基因重叠、延长训练、增大n_latent过度校正整合过于激进改用带标签的 scANVI或将batch_key换成categorical_covariate_keys[batch]CITE-seq 蛋白信号差蛋白数据被 CLR 归一化从 Seurat 导出 raw countsGetAssayData(assayADT, slotcounts)用get_normalized_expression(return_meanTrue)取去噪值导入错误依赖缺失pip install scvi-tools[all]训练调参经验来自 scrna_integration.md大数据集10 万细胞max_epochs100、batch_size256、train_size0.9小数据集1 万细胞n_latent10、n_layers1、dropout_rate0.2、max_epochs400、batch_size64始终监控model.history[elbo_train]与elbo_validation曲线判断收敛与过拟合可借助plot_training_history()一键绘图。完整性补充本文聚焦 scVI/scANVI 整合工作流其他模型的逐行代码实现分别见 atac_peakvi.md、citeseq_totalvi.md、multiome_multivi.md、spatial_deconvolution.md、label_transfer.md、scarches_mapping.md、batch_correction_sysvi.md 与 rna_velocity_velovi.md。所有脚本与工具函数的完整实现均可直接查阅 bio-research/skills/scvi-tools/scripts 目录按需链式组合即可搭建从原始 h5ad 到整合、聚类、差异表达与标签注释的完整单细胞分析流水线。【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/12 16:52:57 · 阅读 1.2k scvi-tools 单细胞深度学习技能指南：模型选型、数据准备与端到端分析流水线
scvi-tools 单细胞深度学习技能指南模型选型、数据准备与端到端分析流水线【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins导读本文基于 knowledge-work-plugins 仓库中 bio-research/skills/scvi-tools/SKILL.md 技能文档系统讲解 scvi-tools 在单细胞组学分析中的完整实战方案从 scVI/scANVI 批次效应校正与数据整合、totalVI/PeakVI/MultiVI 多模态分析到 DestVI 空间去卷积、veloVI RNA 速率与 scArches 参考图谱映射。读完本文你将掌握如何根据数据类型快速选择合适的概率模型、如何正确准备 raw counts 数据、如何使用仓库提供的 7 个 CLI 脚本与model_utils.py工具函数搭建端到端流水线以及常见训练与数据格式问题的排查思路。模型选择指南八种模型覆盖单细胞分析全景scvi-tools 是一套面向单细胞基因组学的概率模型probabilistic model深度学习框架其核心思想是用变分自编码器VAE学习去除批次效应的共享隐空间。SKILL.md 提供了清晰的模型选型表涵盖从经典 scRNA-seq 到多模态与空间转录组的主流场景数据类型模型核心用途scRNA-seqscVI无监督整合、差异表达、数据填补scRNA-seq 标签scANVI标签迁移、半监督整合CITE-seqRNA蛋白totalVI多模态整合、蛋白信号去噪scATAC-seqPeakVI染色质开放性分析MultiomeRNAATACMultiVI联合模态分析空间 scRNA 参考DestVI细胞类型去卷积RNA velocityveloVI转录动力学分析跨技术平台sysVI系统级批次校正选型经验无标签的探索性整合优先选 scVI存在部分或完整细胞类型标签时选 scANVI半监督方式能更好地保留生物学变异CITE-seq 数据在adata.obsm中存在蛋白表达矩阵时选 totalVIscATAC-seq 由于特征数量大峰数量动辄超过 10 万且为二值开放状态选 PeakVI 更合适。使用技能文档的标准化流程SKILL.md 将使用流程总结为五步根据上面的模型/工作流表格确定要使用的模型阅读对应的 reference 文件获取详细步骤与代码例如 scrna_integration.md直接复用scripts/目录下的脚本避免重复编写常见代码遇到安装或 GPU 问题查阅 environment_setup.md遇到调试问题查阅 troubleshooting.md。技能触发条件包括用户提到 scVI、scANVI、totalVI、PeakVI、MultiVI、DestVI、veloVI、sysVI、scArches、变分自编码器VAE、批次校正、数据整合、多模态、CITE-seq、multiome、参考图谱映射reference mapping、隐空间等关键词。SKILL.md 的完整技能描述位于文件头部 YAML frontmatterbio-research/skills/scvi-tools/SKILL.mdAgent 可通过 description 字段自动识别何时调用本技能。工作流参考文件地图SKILL.md 为每个分析方向都配了独立的参考文档形成完整的知识体系工作流参考文件说明环境搭建environment_setup.md安装、GPU、版本信息数据准备data_preparation.md为任意模型格式化数据scRNA 整合scrna_integration.mdscVI/scANVI 批次校正ATAC-seq 分析atac_peakvi.mdPeakVI 染色质开放性CITE-seq 分析citeseq_totalvi.mdtotalVI 蛋白RNAMultiome 分析multiome_multivi.mdMultiVI RNAATAC空间去卷积spatial_deconvolution.mdDestVI 空间分析标签迁移label_transfer.mdscANVI 参考图谱映射scArches 映射scarches_mapping.md查询集到参考集映射批次校正batch_correction_sysvi.md高级批次方法RNA 速率rna_velocity_velovi.mdveloVI 动力学故障排查troubleshooting.md常见问题与解法关键要求scvi-tools 输入数据的三个铁律SKILL.md 明确了使用任何 scvi-tools 模型前必须满足的三条硬性要求这也是新手最容易踩坑的地方1. 必须使用原始整数 countsscvi-tools 的概率模型基于原始计数分布负二项等建模绝不接受归一化或 log 变换后的数据。标准做法是在任何归一化之前把原始计数存入 layeradata.layers[counts] adata.X.copy() # Before normalization scvi.model.SCVI.setup_anndata(adata, layercounts)2. 选择 2000~4000 个高变基因HVGHVG 选择既能过滤噪声基因、提升生物学信号也能大幅降低训练开销。多批次数据必须使用 batch-aware 的seurat_v3flavorsc.pp.highly_variable_genes(adata, n_top_genes2000, batch_keybatch, layercounts, flavorseurat_v3) adata adata[:, adata.var[highly_variable]].copy()3. 通过 batch_key 声明批次信息批次信息是 scVI 类模型校正混淆因素的先验必须通过setup_anndata注册scvi.model.SCVI.setup_anndata(adata, layercounts, batch_keybatch)深入setup_anndata 的完整参数谱系仓库的 data_preparation.md 进一步扩展了setup_anndata的用法——除layer与batch_key外还可以注册scANVI 标签labels_keycell_type可含 Unknown 表示未标注细胞半监督连续协变量continuous_covariate_keys[percent_mito, n_genes]用于回归掉线粒体比例等连续混杂分类协变量categorical_covariate_keys[donor, technology]用于整合供体、测序技术等分类混杂totalVI 蛋白数据protein_expression_obsm_keyprotein_expression蛋白计数矩阵存于adata.obsmMultiVI 多模态使用scvi.model.MULTIVI.setup_mudata(mdata, rna_layercounts, batch_keybatch, modalities{rna: rna, accessibility: atac})要求 MuData 格式。注意1.x API 中setup_anndata是模型类的方法scvi.model.SCVI.setup_anndata(...)而 0.x 旧 API 是scvi.data.setup_anndata(...)已废弃详情见 environment_setup.md。CLI 脚本七个开箱即用的流水线组件SKILL.md 提供了 7 个模块化 CLI 脚本可串联使用也可独立修改。它们位于 bio-research/skills/scvi-tools/scripts脚本用途示例用法prepare_data.pyQC、过滤、HVG 选择python scripts/prepare_data.py raw.h5ad prepared.h5ad --batch-key batchtrain_model.py训练任意 scvi-tools 模型python scripts/train_model.py prepared.h5ad results/ --model scvicluster_embed.pyNeighbors、UMAP、Leidenpython scripts/cluster_embed.py adata.h5ad results/differential_expression.py差异表达分析python scripts/differential_expression.py model/ adata.h5ad de.csv --groupby leidentransfer_labels.pyscANVI 标签迁移python scripts/transfer_labels.py ref_model/ query.h5ad results/integrate_datasets.py多数据集整合python scripts/integrate_datasets.py results/ data1.h5ad data2.h5advalidate_adata.py检查数据兼容性python scripts/validate_adata.py data.h5ad --batch-key batch端到端示例工作流SKILL.md 给出了从校验到差异表达的完整命令链也是实际项目中最常用的起点# 1. Validate input data校验输入数据 python scripts/validate_adata.py raw.h5ad --batch-key batch --suggest # 2. Prepare data (QC, HVG selection)准备数据QC、HVG 选择 python scripts/prepare_data.py raw.h5ad prepared.h5ad --batch-key batch --n-hvgs 2000 # 3. Train model训练模型 python scripts/train_model.py prepared.h5ad results/ --model scvi --batch-key batch # 4. Cluster and visualize聚类与可视化 python scripts/cluster_embed.py results/adata_trained.h5ad results/ --resolution 0.8 # 5. Differential expression差异表达 python scripts/differential_expression.py results/model results/adata_clustered.h5ad results/de.csv --groupby leiden脚本源码级解析validate_adata.py训练前的体检报告。该脚本validate_adata.py的核心是validate_for_scvi()函数通过ValidationResult数据结构输出 PASSED/FAILED 状态、错误、警告与建议四类信息。检查项包括数据是否含整数raw counts 判定np.allclose(X_check, X_check.astype(int))、是否存在负值/NaN/Inf、数据取值范围最大值小于 10 提示可能已被 log 或归一化、稀疏度、batch 列是否存在及批次细胞数是否过少50 提示合并、标签列是否存在及稀有类型30 细胞提示可能学不好、HVG 数量是否落在 2000~4000 最佳区间等。--suggest参数还会结合数据特征自动推荐模型。prepare_data.py标准化数据准备。该脚本prepare_data.py支持的参数包括--batch-keybatch-aware HVG 选择、--n-hvgs默认 2000、--min-genes每细胞最少基因数默认 200、--max-genes每细胞最多基因数默认 5000、--max-mito线粒体比例上限默认 20%、--min-cells每基因最少细胞数默认 3、--no-filter跳过 QC 过滤适用于已质检数据。内部先做细胞/基因过滤再把原始计数存入layers[counts]最后执行 HVG 选择并子集化。线粒体基因检测复用model_utils.get_mito_genes()同时兼容人类MT-前缀与小鼠mt-/Mt-前缀命名。train_model.py六大模型一键训练。该脚本train_model.py通过MODELS字典注册了scvi、scanvi、totalvi、peakvi、velovi、multivi六种模型统一参数包括--model、--batch-key、--labels-keyscANVI 必需、--protein-keytotalVI 蛋白 obsm 键默认protein_expression、--n-latent默认 30、--n-layers默认 2、--max-epochs默认 200。几个实现细节值得注意scANVI 采用两阶段训练train_scanvi先完整训练 scVI再用SCANVI.from_scvi_model(scvi_model, labels_key..., unlabeled_categoryUnknown)初始化并微调max_epochs // 4个 epoch比从头训练收敛更快PeakVI 自动二值化若adata.X.max() 1脚本会把数据转换为 0/1 的开放/关闭状态(adata.X 0).astype(np.float32)veloVI 自动预处理若缺少Ms/Mu层脚本会调用 scvelo 的filter_and_normalize与moments生成 spliced/unspliced 平滑层veloVI 位于scvi.external.VELOVI而非scvi.model输出X_veloVI隐表示、velocity层与latent_time_meanMultiVI 要求 MuData.h5mu文件需mudata包且须包含rna与atac两个模态。cluster_embed.py隐空间的下游分析。该脚本cluster_embed.py自动按优先级X_scANVI → X_scVI → X_totalVI → X_PeakVI → X_MultiVI探测隐表示找不到时回退到 PCA。参数--n-neighbors默认 15、--resolutionLeiden 分辨率默认 1.0、--min-distUMAP 最小距离默认 0.3。输出adata_clustered.h5ad、umap_clusters.png最多 6 个子图自动识别 batch/labels/predicted 列与cluster_counts.csv。differential_expression.py生成模型驱动的 DE。该脚本differential_expression.py调用模型的differential_expression()方法天然校正批次效应。支持单组对比--group1/--group2缺省时 group2 为其余所有细胞或一键对全部分组做 one-vs-rest 分析--n-genes可按lfc_mean取每组前 N 个基因--plot生成火山图红色标记is_de_fdr_0.05显著基因纵轴优先用 Bayes Factor。其底层在 model_utils.get_marker_genes() 中有对应实现筛选阈值为 FDR0.05 且lfc_mean 0.5。transfer_labels.py参考图谱映射与标签迁移。该脚本transfer_labels.py实现了 scArches 工作流的核心三要素先做参考基因与查询基因的交集检查重叠 50% 时告警再用SCANVI.prepare_query_anndata()对齐基因空间最后SCANVI.load_query_data()加载查询模型并微调。输出predicted_cell_type、prediction_confidencesoft 预测最大值与confident_prediction置信度 ≥--confidence阈值默认 0.5并生成predictions.png、predictions.csv与query_annotated.h5ad。Python 工具库model_utils.py 的九大函数SKILL.md 列出了 model_utils.py 中可直接 import 复用的函数适合在 Jupyter 或自定义脚本中构建更灵活的工作流函数用途prepare_adata()数据准备QC、HVG、layer 设置参数含batch_key、n_top_genes、min_genes、max_genes、max_mito_pct、min_cells、copytrain_scvi()训练 scVI 或 scANVI提供labels_key时自动走 scANVI 两阶段路线evaluate_integration()计算整合指标细胞类型 silhouette、批次 silhouette、批次混合度get_marker_genes()用 scVI 差异表达提取标记基因save_results()保存模型、数据、UMAP 图auto_select_model()根据数据特征推荐最优模型quick_clustering()Neighbors UMAP Leiden 一站式聚类compare_integrations()用标准指标比较多个整合嵌入plot_training_history()可视化训练收敛曲线ELBO 与重建损失整合质量评估的实现细节evaluate_integration()model_utils.py给出了一套不依赖额外包即可计算的量化指标silhouette_label基于细胞类型标签的轮廓系数越高说明细胞类型分离越好生物学保守性silhouette_batch基于批次标签的轮廓系数越低说明批次混合越好batch_mixing对每个细胞统计其 50 个最近邻中覆盖的独特批次占所有批次的比例并取平均衡量局部混合程度。compare_integrations()在此基础上还计算integration_score silhouette_label - silhouette_batch可横向比较 PCA、scVI、scANVI 等不同嵌入的整合质量更严谨的评估则可参考 scrna_integration.md 中基于scib-metrics的Benchmarker基准测试。快速决策树按需直达正确模型SKILL.md 提供了可落地的决策树是模型选型的核心工具完整逻辑如下Need to integrate scRNA-seq data?需要整合 scRNA-seq 数据 ├── Have cell type labels? → scANVI (references/label_transfer.md) └── No labels? → scVI (references/scrna_integration.md) Have multi-modal data?有多模态数据 ├── CITE-seq (RNA protein)? → totalVI (references/citeseq_totalvi.md) ├── Multiome (RNA ATAC)? → MultiVI (references/multiome_multivi.md) └── scATAC-seq only? → PeakVI (references/atac_peakvi.md) Have spatial data?有空间数据 └── Need cell type deconvolution? → DestVI (references/spatial_deconvolution.md) Have pre-trained reference model?有预训练参考模型 └── Map query to reference? → scArches (references/scarches_mapping.md) Need RNA velocity?需要 RNA 速率 └── veloVI (references/rna_velocity_velovi.md) Strong cross-technology batch effects?跨技术批次效应强 └── sysVI (references/batch_correction_sysvi.md)这条决策树与auto_select_model()的启发式逻辑相互印证后者会检查obsm中是否存在protein_expression→ totalVI、layers 中是否存在spliced/unspliced→ veloVI、特征数是否超 10 万→ 疑似 ATAC 峰PeakVI、以及obs中是否含 cell/type/label 类列与 batch/sample 类列→ 决定 scANVI 还是 scVI见 model_utils.py。环境安装与版本要求完整的安装指导见 environment_setup.md核心要点# 推荐方式Conda 环境 GPU 支持 conda create -n scvi-env python3.10 conda activate scvi-env pip install scvi-tools # GPU 加速需按 CUDA 版本选择如 CUDA 11.8 pip install torch --index-url https://download.pytorch.org/whl/cu118 # 常用依赖 pip install scanpy leidenalg按分析类型可选择附加组件空间分析加squidpyMultiome 加mudata muon。推荐版本底线为scvi-tools1.0.0、scanpy1.9.0、anndata0.9.0、torch2.0.0MultiVI 需mudata0.2.0veloVI 需scvelo0.2.5。1.x 与 0.x 的核心 API 差异在于setup_anndata/view_anndata_setup均从scvi.data迁移到了模型类方法。安装后可用scvi.data.heart_cell_atlas_subsampled()加载测试数据、以 1 个 epoch 快速验证训练链路是否通畅。常见问题速查与排查策略仓库的 troubleshooting.md 汇总了跨模型的高频问题此处提炼最核心的对照表症状可能原因快速修复X should contain integersX 中是归一化数据setup_anndata中指定layercounts或从adata.raw恢复原始计数CUDA out of memoryGPU 显存不足调小batch_size如 64、减小模型、先子集到 HVG、torch.cuda.empty_cache()训练 loss 为 NaN数据或学习率问题检查/过滤全零细胞与基因开启早停批次混合不佳共享特征过少增加 HVG 数量如 4000、检查基因重叠、延长训练、增大n_latent过度校正整合过于激进改用带标签的 scANVI或将batch_key换成categorical_covariate_keys[batch]CITE-seq 蛋白信号差蛋白数据被 CLR 归一化从 Seurat 导出 raw countsGetAssayData(assayADT, slotcounts)用get_normalized_expression(return_meanTrue)取去噪值导入错误依赖缺失pip install scvi-tools[all]训练调参经验来自 scrna_integration.md大数据集10 万细胞max_epochs100、batch_size256、train_size0.9小数据集1 万细胞n_latent10、n_layers1、dropout_rate0.2、max_epochs400、batch_size64始终监控model.history[elbo_train]与elbo_validation曲线判断收敛与过拟合可借助plot_training_history()一键绘图。完整性补充本文聚焦 scVI/scANVI 整合工作流其他模型的逐行代码实现分别见 atac_peakvi.md、citeseq_totalvi.md、multiome_multivi.md、spatial_deconvolution.md、label_transfer.md、scarches_mapping.md、batch_correction_sysvi.md 与 rna_velocity_velovi.md。所有脚本与工具函数的完整实现均可直接查阅 bio-research/skills/scvi-tools/scripts 目录按需链式组合即可搭建从原始 h5ad 到整合、聚类、差异表达与标签注释的完整单细胞分析流水线。【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考