single-cell-multi-omics-integration

单细胞多组学整合

本技能介绍 OmicVerse 的多组学整合工具，用于组合 scRNA-seq、scATAC-seq 和其他模态。每种方法针对不同的场景，请根据数据结构和分析目标进行选择。

方法选择指南

编写代码前，先选择合适的工具：

场景	方法	核心类
来自同一细胞的配对 RNA + ATAC	直接使用 MOFA	ov.single.pyMOFA
非配对 RNA + ATAC（来自不同实验）	GLUE 配对 → MOFA	ov.single.GLUE_pair → pyMOFA
多批次单模态整合	SIMBA	ov.single.pySIMBA
从已注释的参考数据转移标签	TOSICA	ov.single.pyTOSICA
对预处理后的多组学数据进行轨迹分析	StaVIA	VIA.core.VIA

说明

1. 对配对多组学数据使用 MOFA

如果有配对测量数据（来自同一细胞的 RNA + ATAC），请使用 MOFA。MOFA 会学习共享因子和模态特异因子，用于解释不同组学层之间的方差。

1. 将每种模态加载为单独的 AnnData对象
2. 使用匹配的 omics 和 omics_name 列表初始化 pyMOFA
3. 运行 mofa_preprocess() 以选择 HVG，然后运行 mofa_run(outfile=...) 进行训练
4. 使用 pyMOFAART(model_path=...) 检查因子相关性、权重和方差图
5. 依赖项：mofapy2；仅支持 CPU

2. 先使用 GLUE 配对，再使用 MOFA

如果 RNA 和 ATAC 来自不同实验（非配对），请使用 GLUE。GLUE 通过学习共享嵌入来对齐不同模态的细胞，然后由 MOFA 识别联合因子。

1. 从 GLUE 生成的嵌入开始（嵌入位于 .obsm 中的 .h5ad 文件）
2. 构建 GLUE_pair 并调用 correlation() 来匹配非配对细胞
3. 筛选出 HVG，并按照配对工作流运行 MOFA
4. 依赖项：mofapy2、scglue、scvi-tools；MDE 嵌入可选用 GPU

3. 使用 SIMBA 进行批次整合

对于多批次单模态数据（例如，多个胰腺研究），请使用 SIMBA。SIMBA 根据分箱特征构建图，并通过 PyTorch-BigGraph 学习经过批次校正的嵌入。

1. 加载已合并的 AnnData，并确保 .obs 中有 batch 列
2. 初始化 pySIMBA(adata, workdir) 并运行预处理流程
3. 调用 gen_graph()，然后调用 train(num_workers=...) 学习嵌入
4. 应用 batch_correction()，获取包含 X_simba 的协调后 AnnData
5. 依赖项：simba、simba_pbg；可选用 GPU，且需要足够的 CPU 线程

4. 使用 TOSICA 迁移参考数据

使用 TOSICA 将细胞类型标签从注释完善的参考数据转移到查询数据集。TOSICA 使用通路掩码 Transformer，也提供基于注意力机制的可解释性。

1. 使用 ov.utils.download_tosica_gmt() 下载基因集 GMT 文件
2. 使用参考 AnnData、GMT 路径、标签键和项目路径初始化 pyTOSICA
3. 使用 train(epochs=...) 训练并保存，然后在查询数据上进行预测
4. 依赖项：TOSICA（PyTorch Transformer）；建议设置 depth=1（depth=2 会使内存需求翻倍）

5. 使用 StaVIA 绘制轨迹图谱

使用 StaVIA/VIA 对包含速度信息的预处理数据进行轨迹推断。VIA 会计算伪时间、聚类图和流图。

1. 使用 OmicVerse 进行预处理（HVG、缩放、PCA、邻居、UMAP）
2. 配置 VIA 的根节点选择、组件、邻居和分辨率
3. 运行 v0.run_VIA()，并从 single_cell_pt_markov 中提取伪时间
4. 依赖项：scvelo、pyVIA；受 CPU 限制

关键 API 参考

MOFA：omics 必须是由单独 AnnData 对象组成的列表

# CORRECT — each modality is a separate AnnData
mofa = ov.single.pyMOFA(omics=[rna_adata, atac_adata], omics_name=['RNA', 'ATAC'])

# WRONG — do NOT pass a single concatenated AnnData
# mofa = ov.single.pyMOFA(omics=combined_adata, omics_name=['RNA', 'ATAC'])  # TypeError!

omics 列表和 omics_name 列表的长度必须相同。每个 AnnData 都应包含来自同一实验的细胞（配对测量）。

SIMBA：必须先运行 preprocess()，再运行 gen_graph()

# CORRECT — preprocess first, then build graph
simba = ov.single.pySIMBA(adata, workdir)
simba.preprocess(batch_key='batch', min_n_cells=3, method='lib_size', n_top_genes=3000, n_bins=5)
simba.gen_graph()
simba.train(num_workers=6)

# WRONG — skipping preprocess causes gen_graph to fail
# simba.gen_graph()  # KeyError: missing binned features

TOSICA：gmt_path 必须是实际文件路径

# CORRECT — download GMT files first, then pass the file path
ov.utils.download_tosica_gmt()
tosica = ov.single.pyTOSICA(adata=ref, gmt_path='genesets/GO_bp.gmt', ...)

# WRONG — passing a database name string instead of file path
# tosica = ov.single.pyTOSICA(adata=ref, gmt_path='GO_Biological_Process', ...)  # FileNotFoundError!

MOFA HDF5：outfile 目录必须存在

import os
os.makedirs('models', exist_ok=True)  # Create output directory first
mofa.mofa_run(outfile='models/rna_atac.hdf5')

防御性验证模式

运行整合方法前，务必验证输入：

# Before MOFA: verify inputs are compatible
assert isinstance(omics, list), "omics must be a list of AnnData objects"
assert len(omics) == len(omics_name), f"omics ({len(omics)}) and omics_name ({len(omics_name)}) must match in length"
for i, a in enumerate(omics):
    assert a.n_obs > 0, f"AnnData '{omics_name[i]}' has 0 cells"
    assert a.n_vars > 0, f"AnnData '{omics_name[i]}' has 0 genes/features"

# Before SIMBA: verify batch column exists
assert 'batch' in adata.obs.columns, "adata.obs must contain a 'batch' column for SIMBA"
assert adata.obs['batch'].nunique() > 1, "Need >1 batch for batch integration"

# Before TOSICA: verify GMT file exists and reference has labels
import os
assert os.path.isfile(gmt_path), f"GMT file not found: {gmt_path}. Run ov.utils.download_tosica_gmt() first."
assert label_name in ref_adata.obs.columns, f"Label column '{label_name}' not found in reference AnnData"

# Before StaVIA: verify PCA and neighbors are computed
assert 'X_pca' in adata.obsm, "PCA required. Run ov.pp.pca(adata) first."
assert 'neighbors' in adata.uns, "Neighbor graph required. Run ov.pp.neighbors(adata) first."

故障排除

• 写入 MOFA HDF5 时出现 PermissionError 或 OSError：mofa_run(outfile=...) 的输出目录必须已存在且可写。训练前使用 os.makedirs() 创建该目录。
• GLUE correlation() 返回空 DataFrame：RNA 和 ATAC 嵌入没有重叠特征。请确认两个 AnnData 对象都已完成 GLUE 预处理，并且 .obsm 中包含嵌入。
• SIMBA gen_graph() 内存不足：减少 n_top_genes（可尝试 2000），或增大 n_bins 以压缩特征空间。SIMBA 图构建的内存开销会随基因数量增加。
• download_tosica_gmt() 后出现 TOSICA FileNotFoundError：下载的文件会写入当前工作目录下的 genesets/。请确认文件位于预期路径，或传入绝对路径。
• StaVIA root_user 不匹配：根节点必须是 true_label 数组中存在的值。请检查 adata.obs['clusters'].unique()，找到有效的根节点名称。
• ImportError: No module named 'mofapy2'：使用 pip install mofapy2 安装。同样，SIMBA 需要使用 pip install simba simba_pbg 安装。
• MOFA 因子全为零或 NaN：输入的 AnnData 可能包含恒定值或全零特征。运行 MOFA 前，使用 sc.pp.filter_genes(adata, min_cells=10) 过滤基因。

示例

• “我有成对的 scRNA 和 scATAC h5ad 文件——运行 MOFA 找出共享因子，并绘制每个因子的方差解释率。”
• “使用 SIMBA 整合三个胰腺批次，并按批次和细胞类型着色，可视化校正后的嵌入。”
• “使用 TOSICA 和 GO biological process 通路，将细胞类型标签从已注释的参考数据集转移到新的查询数据集。”

参考资料

• MOFA 教程：t_mofa.ipynb
• GLUE+MOFA 教程：t_mofa_glue.ipynb
• SIMBA 教程：t_simba.ipynb
• TOSICA 教程：t_tosica.ipynb
• StaVIA 教程：t_stavia.ipynb
• 快速复制/粘贴命令：reference.md