该技能用于将同一斑点或细胞上测得的多模态数据，或同一组织的多个切片，整合为一个表示。产出包括联合潜空间与聚类、去噪后的蛋白图谱、整合后的切片、迁移的标签，以及组织上的特征评分。
用途与对应方法：同一斑点或细胞上的 RNA 与蛋白用 totalVI（模块 1-2）；同一细胞上的 RNA 与染色质可及性用 MultiVI（模块 3）；单一模态的多个切片或样本用 BBKNN（模块 4）；把已注释切片的标签迁移到新切片用 scanpy ingest（模块 5）；在组织上打分通路或细胞状态用 sc.tl.score_genes（模块 6）；跨 2 个以上组学做无监督因子分析用 MOFA+（模块 mofaplus-multi-omics）。
适用场景：用 RNA 与蛋白联合模型分析 Visium CytAssist Gene and Protein 或 CITE-seq 数据；整合同一细胞上测得的 RNA 与 ATAC（10x Multiome、空间 ATAC-RNA）；在不合并坐标的前提下对多个组织切片聚类；把已注释切片的标签复制到同平台的新切片；将通路或细胞状态特征映射到组织上。若是不涉及空间维度的解离细胞 scVI/scANVI 流程，应改用 scvi-tools-single-cell；跨组学层的因子分析应改用 mofaplus-multi-omics 或 muon-multiomics-singlecell。
前提条件：输入为每个模态的原始计数（totalVI 与 MultiVI 都建模计数）；计算方面 scvi-tools 会拉取 torch，MultiVI 推荐使用 GPU，totalVI 在几千个斑点时可在 CPU 上运行；Python 包为 scvi-tools、mudata（模块 3）、bbknn（模块 4）、scanpy。安装命令：pixi add --pypi scvi-tools mudata bbknn scanpy，只安装 import 报缺失的包；--pypi 可保留环境中的 scanpy/numba 栈，conda 添加可能替换它，裸 pip 可能遮蔽它。
主要能力（按模块）： 模块 1 加载空间 RNA 与蛋白（Visium CytAssist），按 feature_types 拆分为 Gene Expression 与 Antibody Capture，把蛋白放入 obsm["protein_expression"]，并读取 spatial/tissue_positions.csv 设置 obsm["spatial"]。 模块 2 用 totalVI 联合建模 RNA 与蛋白：在 log 数据上选高变基因（默认 4000），在计数上建模，训练 400 个 epoch 并启用早停，得到联合潜表示 X_totalVI 与去噪蛋白表达 protein_denoised，再据此做邻居图、UMAP 和 Leiden 聚类。建议在信任聚类前对比已知标志物（如扁桃体滤泡的 CD3、CD20/MS4A1、CD21）的原始与去噪蛋白图谱，同型对照抗体去噪后应接近零。 模块 3 用 MultiVI 联合 RNA 与 ATAC：输入为含同一细胞 RNA 与 ATAC 模态的 MuData（10x Multiome；空间 ATAC-RNA 布局相同并另带坐标），需要传入 n_genes 与 n_regions，强烈建议使用 GPU（约 10 万个 peak），可得到联合潜表示 X_multivi 与插补的染色质可及性矩阵。有批次时在 setup_mudata 中加入 batch_key。 模块 4 用 BBKNN 整合多个切片：按每个切片取 k 个邻居构建邻居图，切片在图中混合而表达值不变、空间坐标仍按切片保留；输出整合后的聚类，可用交叉表检查是否仍有切片特异性聚类。 模块 5 用 scanpy ingest 迁移标签：把查询切片投影到参考的 PCA/UMAP 并复制最近邻标签；该方法不做批次校正，因此仅适用于同平台、同 panel 的切片之间。若要把 scRNA-seq 参考迁移到成像数据，应改用空间转录组细胞类型注释中的 Harmony 路线；Visium 斑点则应使用解卷积。 模块 6 用 sc.tl.score_genes 在组织上给基因特征打分：默认 ctrl_size=50、n_bins=25，分数相对相似表达的随机对照基因；在仅几百个基因的靶向 panel 上应调低 ctrl_size，并把分数理解为排序而非绝对活性。
常见工作流：一是用去噪蛋白为 totalVI 聚类命名，按聚类汇总蛋白 z 分数与 RNA 差异基因，生成证据表；一个聚类若只有 RNA 支持而蛋白不支持（或相反），应在报告中注明。二是整合切片后比较特征评分，按联合聚类与切片分组汇总各特征分数。
关键参数：n_latent（totalVI）默认 20，为联合潜维度；n_top_genes（totalVI）默认 4000，为与蛋白一起建模的 RNA 基因数；max_epochs 在 totalVI 为 400、MultiVI 用 scvi 默认值，配合基于验证损失的早停；batch_key 默认 None，用于在 scvi 模型内校正切片或样本；neighbors_within_batch 默认 3，为 BBKNN 从每个切片取的邻居数；ctrl_size（score_genes）默认 50，为每个表达分箱的对照基因数。
预期输出：totalvi_result.h5ad 与 totalvi_model/（联合潜空间、去噪蛋白、聚类）；multivi_result.h5ad（RNA+ATAC 潜空间与聚类）；bbknn_result.h5ad（整合切片与聚类）；ingest_annotations.csv 与 ingest_result.h5ad（迁移到新切片的标签）；signature_scores.csv（每个斑点或细胞的特征分数）；figures/（聚类、蛋白与分数的空间图）。
限制与排错提示：所有模态需提供原始计数；totalVI 若蛋白误放在 X 而非 obsm 会报错，需按 feature_types 拆出到 obsm["protein_expression"]；去噪蛋白处处平坦可能是训练轮数过少或抗体计数极低；MultiVI 的 n_genes/n_regions 报错多因构造尺寸缺失或模态命名不符；MultiVI 在 CPU 上处理约 10 万 peak 会很慢，建议用 GPU 或只保留在 1-5% 以上细胞中出现的 peak；BBKNN 聚类仍按切片分裂说明批次效应强，应改用带 batch_key 的 scVI 或 Harmony；ingest 标签全为同一类型通常源于切片间平台或归一化方式不同。多切片联合 totalVI 时各切片需使用相同的抗体 panel，若不同则只保留共有蛋白。