single-cell-cellphonedb-communication-mapping

单细胞 CellPhoneDB 通信映射

概述

当用户希望量化已注释单细胞群体之间的配体-受体通信，并使用 OmicVerse 的 CellPhoneDB 绘图工具栈将结果可视化时，请使用此技能。此技能现在涵盖原有的底层 ov.pl.CellChatViz 工作流，以及较新的公开绘图 API：

• ov.pl.ccc_heatmap(...)
• ov.pl.ccc_network_plot(...)
• ov.pl.ccc_stat_plot(...)

若目标是使用稳定的公开 API 快速生成可直接用于发表的图表，默认使用 ccc_* 函数。当用户需要控制方法级别的细节，或希望在同一个笔记本中组合多个自定义可视化结果时，则使用 CellChatViz。

说明

1. 准备环境
   • 使用包含 omicverse>=0.2、scanpy、anndata、pandas、matplotlib、seaborn 和 CellPhoneDB 资源的环境。
   • 对于较新的可视化，还需确保在需要时安装以下可选绘图依赖项：
     • 用于热图和气泡矩阵绘图器的 marsilea。
     • 用于弦图的 mpl-chord-diagram。
     • 用于扩散图和网络风格图的 networkx。
     • 如果用户希望改善自动标签避让效果，请安装 adjustText。
   • 使用 ov.plot_set() 激活 OmicVerse 绘图默认设置。
2. 加载并验证已注释的 AnnData
   • 使用 ov.read(...) 读取标准化表达矩阵。
   • 确保通信分组列干净、为分类类型，并与预期的身份标签一致。
   • 建议进行以下检查：

     celltype_key = "cell_labels"
     assert celltype_key in adata.obs.columns, f"{celltype_key} missing from adata.obs"
     adata.obs[celltype_key] = adata.obs[celltype_key].astype("category").cat.remove_unused_categories()
     assert not adata.obs[celltype_key].isna().any(), f"NaN values found in {celltype_key}"
     min_per_group = adata.obs[celltype_key].value_counts().min()
     if min_per_group < 10:
         print(f"WARNING: smallest group has {min_per_group} cells; sparse groups may destabilize permutations")
     

   • 在运行 CellPhoneDB 前，确认矩阵已进行对数标准化。原始计数可能会扭曲基于置换的显著性结果。
3. 通过 OmicVerse 运行 CellPhoneDB
   • 使用 ov.single.run_cellphonedb_v5(...) 并保存输出：

     cpdb_results, adata_cpdb = ov.single.run_cellphonedb_v5(
         adata,
         cpdb_file_path="./cellphonedb.zip",
         celltype_key="cell_labels",
         min_cell_fraction=0.005,
         min_genes=200,
         min_cells=3,
         iterations=1000,
         threshold=0.1,
         pvalue=0.05,
         threads=10,
         output_dir="./cpdb_results",
         cleanup_temp=True,
     )
     

   • 保存 cpdb_results 和 adata_cpdb，以便后续重复绘图，而无需重新运行置换。
   • CellChat 替代方案（无需 R，除 PyTorch 外无需额外安装）：ov.single.run_cellchat 可复现 R CellChat 2.2（过表达基因和 LR 对完全相同，概率精度约为 1e-15），并将结果存入 adata.uns['cellchat_res']，所有 ov.pl.ccc_* 调用都会直接读取该结果：

     ov.single.run_cellchat(adata, groupby="cell_labels", species="human")  # log-normalised X
     comm = ov.single.format_cellchat_results(adata)                         # optional explicit comm AnnData
     df = ov.single.cellchat_subset_communication(adata, signaling=["TGFb"])  # significant LR table
     centr = ov.single.cellchat_centrality(adata)                             # sender/receiver/mediator/influencer
     

     CellChat 分数是概率（约为 1e-3），而非表达量；通路汇总会自动选择适合相应尺度的阈值。细胞数 <= min_cells（默认值为 10）的分组会被移除，与 R filterCommunication 中的处理一致。
4. 对于标准可视化需求，优先使用新的公共绘图 API
   • 矩阵类绘图使用 ov.pl.ccc_heatmap(...)：
     • 使用 plot_type="heatmap" 绘制聚合的通路级通信图。
     • 使用 plot_type="focused_heatmap" 在阈值筛除较弱条目后突出显示较强相互作用。
     • 使用 plot_type="dot" 或 "bubble" 绘制相互作用级汇总图。
     • 使用 plot_type="pathway_bubble" 绘制以通路为重点的 Marsilea 气泡汇总图。
     • 使用 plot_type="bubble_lr" 绘制配体-受体对专属气泡矩阵。
     • 使用 plot_type="role_heatmap"、"role_network" 或 "role_network_marsilea" 绘制信号角色汇总图。
     • 比较两个通信 AnnData 对象时，使用 plot_type="diff_heatmap"。
   • 图形类绘图使用 ov.pl.ccc_network_plot(...)：
     • 使用 plot_type="circle" 或 "circle_focused" 绘制全局通信网络。
     • 使用 plot_type="individual_outgoing" / "individual_incoming" 绘制以发送方或接收方为中心的圆形子图。
     • 使用 plot_type="individual" 绘制单条通路，并可选择指定一个 L-R 对。
     • 使用 plot_type="chord" 绘制细胞类型级通路弦图。
     • 使用 plot_type="gene_chord" 绘制跨通路特异性配体和受体节点的基因级弦图。
     • 使用 plot_type="lr_chord" 绘制指定的配体-受体对。
     • 使用 plot_type="diffusion" 绘制通路相似性和扩散风格的网络结构。
     • 比较两个通信对象时，使用 plot_type="diff_network"。
     • 使用 plot_type="bipartite"、"arrow"、"sigmoid" 或 "embedding_network" 绘制其他布局的图。
   • 统计和汇总面板使用 ov.pl.ccc_stat_plot(...)：
     • 使用 plot_type="pathway_summary" 按通信强度和显著性对通路排序。
     • 使用 plot_type="lr_contribution" 显示通路中的主要配体-受体对。
     • 使用 plot_type="scatter" 或 "role_scatter" 比较传出与传入信号角色。
     • 使用 plot_type="role_network" 或 "role_network_marsilea" 绘制矩阵式角色汇总图。
     • 使用 plot_type="sankey" 汇总通信流。
5. 当用户需要控制方法级别的细节时，直接使用 CellChatViz
   • 根据细胞标签创建稳定的调色板映射：

     color_dict = dict(zip(
         adata.obs["cell_labels"].cat.categories,
         adata.uns["cell_labels_colors"]
     ))
     viz = ov.pl.CellChatViz(adata_cpdb, palette=color_dict)
     

   • 建议的直接使用流程：
     • 运行 viz.compute_aggregated_network(...)，然后运行 viz.netVisual_circle(...)。
     • 运行 viz.compute_pathway_communication(...)，然后运行 viz.get_significant_pathways_v2(...)。
     • 使用 viz.netVisual_heatmap_marsilea(...) 或 viz.netVisual_heatmap_marsilea_focused(...)。
     • 使用 viz.netVisual_bubble_marsilea(...) 绘制通路气泡图。
     • 使用 viz.netVisual_bubble_lr(...) 绘制选定配体-受体对的气泡图。
     • 使用 viz.netVisual_chord_cell(...)、viz.netVisual_chord_gene(...) 和 viz.netVisual_chord_LR(...)。
     • 使用 viz.netVisual_individual(...) 绘制一条通路 / 一个富集对。
     • 运行 viz.netAnalysis_computeCentrality()，然后绘制角色热图、散点图和网络图。
     • 使用 viz.netAnalysis_contribution(pathway) 分析通路级别的配体-受体对贡献。
     • 使用 viz.netVisual_diffusion(...) 绘制通路相似性结构。
6. 清晰突出新的可视化功能
   • 回答中值得介绍的较新功能包括：
     • gene_chord：基因级弦图，而不仅仅是细胞类型级弦图。
     • bubble_lr：以明确指定的配体-受体对为中心的 Marsilea 气泡汇总图。
     • focused_heatmap：通过阈值筛选抑制较弱相互作用的通路热图。
     • role_network_marsilea：更丰富的角色汇总图，包含树状图、色条和重要性条。
     • diffusion：基于通信模式的通路相似性网络。
     • pathway_summary 和 lr_contribution：用于优先级排序的高层级汇总和统计视图。
   • 用户提到“新可视化”时，优先演示其中一种，而不是只展示旧版圆形图。
7. 较新绘图的参数提示
   • 对于通路气泡图：
     • group_pathways=True 可按通路而非单个 L-R 对分组。
     • 当细胞对行过多、标签难以辨认时，transpose=True 会很有用。
     • add_violin=True 可以展示分数分布，但会使图表更加密集。
   • 对于配体-受体气泡图：
     • 当用户希望比较固定的一组配体-受体对（即使其中有些较弱或不存在）时，show_all_pairs=True 会很有用。
     • pair_lr_use 或 interaction_use 应与 adata.var 中的配体-受体对命名一致。
   • 对于基因弦图：
     • 需要 adata.var["gene_a"] 和 adata.var["gene_b"]。
     • 当基因或细胞类型标签较长时，使用 rotate_names=True。
   • 对于聚焦热图和聚焦圆形图：
     • 调整 min_interaction_threshold，以便在绘图前移除较弱的边。
   • 对于角色图：
     • 使用低级 API 时，先运行 viz.netAnalysis_computeCentrality()。
     • 如果用户希望分别查看易于解释的发送方和接收方程序，请分别使用 pattern="incoming" 和 pattern="outgoing"。
8. 故障排除
   • 元数据对齐：通信分组列必须为分类类型，且不能包含缺失值。
   • 数据库包：cpdb_file_path 必须指向有效的 CellPhoneDB v5 SQLite zip 文件。
   • 稀疏分组：非常小的发送方或接收方分组常会导致不稳定或空输出。
   • adata.var 中缺少列：
     • 按通路筛选绘图需要 classification。
     • 基因级或配体-受体对专属绘图需要 gene_a 和 gene_b。
   • 可选依赖项错误：
     • 为 pathway_bubble、bubble_lr、聚焦热图和 Marsilea 角色网络视图安装 marsilea。
     • 为弦图安装 mpl-chord-diagram。
     • 如果标签重叠严重，请安装 adjustText。
   • 调色板不匹配：根据 adata.obs[celltype_key].cat.categories 中排序后的类别及对应的 adata.uns[f"{celltype_key}_colors"] 重新构建调色板。

示例

• “运行 CellPhoneDB，然后使用 ov.pl.ccc_heatmap(..., plot_type='focused_heatmap') 展示最强的通路。”
• “使用 ov.pl.ccc_network_plot(..., plot_type='gene_chord') 为 FGF 信号通路创建基因级弦图。”
• “使用 plot_type='bubble_lr' 比较发送者与接收者组合中的选定配体-受体对。”
• “使用 ccc_stat_plot(..., plot_type='pathway_summary') 总结排名靠前的通路，然后使用 plot_type='lr_contribution' 对通路内的配体-受体贡献进行排名。”
• “直接使用 CellChatViz 计算中心性并绘制 Marsilea 角色网络图。”

参考资料

• 教程笔记本：t_cellphonedb.ipynb
• 示例数据：omicverse_guide/docs/Tutorials-single/data/cpdb/
• 快速复制/粘贴命令：reference.md