single-cell-downstream-analysis

单细胞下游分析快速参考

本指南将 OmicVerse 单细胞下游教程提炼为可执行的检查清单。每个模块都重点介绍前置条件、核心 API 入口、结果解读检查点、资源规划说明，以及教程中提到的可选验证或导出步骤。

防御性验证模式

运行任何下游模块前，请先验证前置条件：

# Before AUCell: verify embeddings exist
assert 'X_umap' in adata.obsm or 'X_pca' in adata.obsm, \
    "Embedding required. Run ov.pp.umap(adata) or ov.pp.pca(adata) first."

# Before metacell DEG: verify raw counts are preserved
assert adata.raw is not None, "adata.raw required. Set adata.raw = adata.copy() before HVG filtering."

# Before SCENIC: verify raw counts (not log-transformed) are available
if hasattr(adata.X, 'max') and adata.X.max() < 20:
    print("WARNING: SCENIC expects raw counts. Data may be log-transformed.")

# Before scDrug: verify tumor annotations
# assert 'cell_type' in adata.obs.columns, "Cell type annotation required for scDrug"

AUCell 通路评分（t_aucell.ipynb）

• 前置条件
  • 运行教程前，下载与研究物种匹配的通路集合（GO、KEGG 或自定义集合）。
  • 确保已准备好带有聚类和嵌入信息（adata.obsm['X_umap']）的 AnnData 对象。
• 核心调用
  • 使用 ov.single.geneset_aucell 计算单个通路；使用 ov.single.pathway_aucell 计算多个通路。
  • 使用 ov.single.pathway_aucell_enrichment 对某个通路库中的所有通路进行评分（设置 num_workers 以启用并行处理）。
• 结果检查
  • 将 AUCell 分数视为类似表达量的数值（0–1）。使用 sc.pl.embedding 确认通路活性模式。
  • 对 AUCell AnnData 运行 sc.tl.rank_genes_groups，查找在特定聚类中富集的通路，并使用 sc.pl.rank_genes_groups_dotplot 可视化。
• 资源
  • 对整个通路库评分会消耗大量 CPU 资源；请分配足够的工作进程（教程中为 num_workers=8），并为稠密 AUCell 矩阵预留充足内存。
• 可选验证 / 导出
  • 使用 adata_aucs.write_h5ad('...') 保存分数，以便重复使用。
  • 使用 ov.single.pathway_enrichment 和 ov.single.pathway_enrichment_plot 热图绘制富集通路。

scRNA-seq 差异表达基因（DEG，bulk 风格的元细胞）（t_scdeg.ipynb）

• 前置条件
  • 运行质量控制和预处理（ov.pp.qc、ov.pp.preprocess、ov.pp.scale、ov.pp.pca）。
  • 在筛选高变基因（HVG）之前，将原始计数保留在 adata.raw 中。
• 核心调用
  • 使用 ov.bulk.pyDEG(test_adata.to_df(...).T) 构建差异分析对象，以分析全细胞和元细胞视图。
  • 有 GPU 可用于加速时，使用 ov.single.MetaCell(..., use_gpu=True) 构建元细胞。
• 结果检查
  • 检查火山图（dds.plot_volcano）和目标基因箱线图（dds.plot_boxplot），查看排名靠前的差异表达基因（DEG）。
  • 使用 ov.pl.embedding 将 DEG 标记映射回 UMAP 嵌入，以确认其定位。
• 资源
  • GPU 有助于构建元细胞，但也可以回退到 CPU；请确保内存足以容纳传递给 pyDEG 的转置稠密矩阵。
• 可选验证 / 导出
  • 使用 matplotlib 图形保存元细胞嵌入；调整 legend_* 设置，以生成适合发表的可视化效果。

scRNA-seq 差异表达基因（DEG，细胞类型与组成）（t_deg_single.ipynb）

• 前置条件
  • 准备带有 condition、cell_label 和可选 batch 元数据的已注释 adata。
  • 使用基于图的差异丰度（DA）方法时，初始化混合 CPU/GPU 资源（ov.settings.cpu_gpu_mixed_init()）。
• 核心调用
  • 使用 ov.single.DEG(..., method='wilcoxon'|'t-test'|'memento-de')，并调用 deg_obj.run(...) 对目标细胞类型进行分析。
  • 使用 ov.single.DCT(..., method='sccoda'|'milo') 进行差异组成检验。
  • Milo 的图设置：ov.pp.preprocess、ov.single.batch_correction、ov.pp.neighbors、ov.pp.umap。
• 结果检查
  • 检查 deg_obj 生成的 DEG 表（Wilcoxon / memento），并调整捕获率 / 自举次数以提高稳定性。
  • 对于 scCODA，使用 sim_results.set_fdr() 调整 FDR；结合条件水平的变化解读箱线图。
  • Milo 诊断图：P 值直方图、logFC 与 –log10 FDR 散点图、差异丰度蜂群图。
• 资源
  • Memento 和 Milo 需要多个 CPU（num_cpus、num_boot、较大的 k）；请确保有充足的计算时间。
  • 启用 Harmony / scVI 批次校正时需要 GPU 内存；请做好显存使用规划。
• 可选验证 / 导出
  • 可视化诊断包括 UMAP 叠加图（ov.pl.embedding）、Milo 蜂群图和自定义调色板。

scDrug 药物反应预测（t_scdrug.ipynb）

• 先决条件
  • 获取以肿瘤为重点的数据集（例如，infercnvpy.datasets.maynard2020_3k）。
  • 在运行预测之前下载参考资源：
    • 通过 ov.utils.get_gene_annotation 获取基因注释（需要来自 GENCODE 或 T2T-CHM13 的 GTF）。
    • 使用 ov.utils.download_GDSC_data() 和 ov.utils.download_CaDRReS_model() 获取药物反应模型。
    • 克隆 CaDRReS-Sc 仓库（git clone https://github.com/CSB5/CaDRReS-Sc）。
• 核心调用
  • 肿瘤分辨率检测：ov.single.autoResolution(adata, cpus=4)。
  • 药物反应运行器：ov.single.Drug_Response(adata, scriptpath='CaDRReS-Sc', modelpath='models/', output='result')。
• 结果检查
  • 检查存储在 output 下的聚类和 IC50 输出；并与推断出的 CNV 状态交叉参照。
• 资源
  • 需要外部 CaDRReS-Sc 环境（Python/R 依赖项）以及用于下载模型的存储空间。
  • 运行 inferCNV 预处理可能需要多个 CPU 和大量 RAM。
• 可选验证 / 导出
  • 持久化中间 AnnData（adata.write('scanpyobj.h5ad')），以便用于下游分析或重新运行。

SCENIC 调控子发现（t_scenic.ipynb）

如需全面了解 SCENIC（数据库下载、RegDiffusion 调优、RSS 解读、GRN 可视化），请使用 search_skills('SCENIC regulon GRN') 加载专门的 SCENIC 技能。

• 先决条件
  • 通过 ov.single.mouse_hsc_nestorowa16() 加载小鼠造血数据集（或提供包含原始计数的预处理数据）。
  • 下载对应物种的 cisTarget 排名数据库（*.feather）和基序注释（motifs-*.tbl）；预留

    3 GB 磁盘空间并验证路径（db_glob、motif_path）。

• 核心调用
  • 初始化分析：ov.single.SCENIC(adata, db_glob=..., motif_path=..., n_jobs=12)。
  • 通过 SCENIC 对象方法运行基于 RegDiffusion 的 GRN 推断、调控子剪枝和 AUCell 评分。
• 结果检查
  • 检查调控子活性矩阵（scenic_obj.auc_mtx.head()）、RSS 分数，以及按调控子活性着色的嵌入图。
  • 使用 RSS 图、树状图和 AUCell 分布来解读 TF 特异性和活性阈值。
• 资源
  • 建议使用多核 CPU（n_jobs 与可用核心数相匹配）；确保有足够的 RAM 用于基序富集。
  • 大型下载和中间对象（pickle/h5ad）需要磁盘空间。
• 可选验证 / 导出
  • 保存 scenic_obj（ov.utils.save）和调控子 AnnData（regulon_ad.write）。
  • 可选图表：每种细胞类型的 RSS、调控子嵌入图、带阈值线的 AUC 直方图、GRN 网络可视化。

cNMF 程序发现（t_cnmf.ipynb）

• 先决条件
  • 使用 HVG 选择（ov.pp.preprocess）、缩放（ov.pp.scale）和 PCA 进行预处理，并准备 UMAP 嵌入以供检查。
  • 选择成分范围（例如，np.arange(5, 11)）和迭代次数；确保输出目录已存在。
• 核心调用
  • 实例化分析：ov.single.cNMF(..., output_dir='...', name='...')。
  • 分解工作流：cnmf_obj.factorize(...)、cnmf_obj.combine(...)、cnmf_obj.k_selection_plot()、 cnmf_obj.consensus(...)。
  • 提取结果：cnmf_obj.load_results(...)、cnmf_obj.get_results(...)；还可通过 get_results_rfc 使用 RF 分类器。
• 结果检查
  • 通过 K 选择图和局部密度直方图评估稳定性；使用共识热图确认选定的 K。
  • 检查主题使用量嵌入（ov.pl.embedding）、聚类标签，以及顶级基因的点图。
• 资源
  • 多次迭代和多个成分会大量占用 CPU；考虑分配多个工作进程（total_workers），并确认有足够磁盘 空间存储中间分解文件。
• 可选验证 / 导出
  • 可视化包括欧氏距离热图、密度直方图、主题/聚类的 UMAP 叠加图和点图。

NOCD 重叠社区（t_nocd.ipynb）

• 前提条件
  • 运行 NOCD 前，使用 ov.single.scanpy_lazy 准备 AnnData（自动预处理）。
  • 注意：教程指出，NOCD 的实现仍在积极开发中，因此结果可能存在差异。
• 核心调用
  • 流水线封装器：scbrca = ov.single.scnocd(adata)，随后链式调用方法（matrix_transform、matrix_normalize、 GNN_configure、GNN_preprocess、GNN_model、GNN_result、GNN_plot、cal_nocd、calculate_nocd）。
• 结果检查
  • 在 UMAP 嵌入图上比较标准 Leiden 聚类与 NOCD 输出，以识别多命运细胞。
• 资源
  • 图神经网络阶段可使用 GPU 加速；请确保 CUDA 可用，否则需做好 CPU 运行时间较长的准备。
  • 构建大型邻接矩阵时，请监控内存使用情况。
• 可选验证 / 导出
  • 使用共享颜色映射生成多个 UMAP 叠加图（sc.pl.umap），分别显示 nocd、nocd_n 和 Leiden 标签。

惰性流水线与报告（t_lazy.ipynb）

• 前提条件
  • 安装 OmicVerse ≥1.7.0，并确保包含惰性工具；目前支持人类和小鼠。
  • 准备批次元数据（sample_key），并可选择初始化混合计算（ov.settings.cpu_gpu_mixed_init()）。
• 核心调用
  • 一站式预处理：ov.single.lazy(adata, species='mouse', sample_key='batch', ...)，可选传入 reforce_steps 和模块专用关键字参数。
  • 报告：使用 ov.single.generate_scRNA_report(...) 生成 HTML 摘要；使用 ov.generate_reference_table(adata) 跟踪引用。
• 结果检查
  • 检查生成的嵌入图（ov.pl.embedding），评估质量和注释一致性。
  • 查看 HTML 报告中的 QC 指标、标准化、批次校正和嵌入结果。
• 资源
  • Harmony 或 scVI 等步骤可能会调用 GPU；请确认硬件可用，或据此调整 reforce_steps。
  • 生成报告时会写入磁盘；请确保输出路径可写。
• 可选验证 / 导出
  • 按颜色键自定义嵌入图；将 HTML 报告和引用表与项目文档一同保存。