single-cell-cellphonedb-communication-mapping

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Single-cell CellPhoneDB communication mapping

单细胞CellPhoneDB通讯图谱绘制

Overview

概述

Apply this skill when a user wants to quantify ligand–receptor communication between annotated single-cell populations and display the networks with

CellChatViz

. It distils the workflow from

t_cellphonedb.ipynb

, which analyses EVT trophoblast data.

当用户想要量化带注释的单细胞群体之间的配体-受体通讯，并使用

CellChatViz

展示网络时，可应用此技能。它提炼自

t_cellphonedb.ipynb

中的工作流，该教程分析了EVT滋养层细胞数据。

Instructions

操作步骤

Prepare the environment
- Use an environment with
```
omicverse>=0.2
```
  ,
```
scanpy
```
  ,
```
anndata
```
  ,
```
pandas
```
  ,
```
matplotlib
```
  , and
```
cellphonedb
```
  resources. The tutorial assumes the pre-built CellPhoneDB v5 SQLite bundle downloaded as
```
cellphonedb.zip
```
  in the working directory.
- Activate omicverse plotting defaults via
```
ov.plot_set()
```
  so that downstream figures follow the project palette.
Load and subset the annotated AnnData object
- Read the normalised counts with
```
adata = ov.read('data/cpdb/normalised_log_counts.h5ad')
```
  .
- Filter to the cell populations of interest using
```
adata.obs['cell_labels']
```
  (e.g., EVT, dNK, VCT). Ensure
```
adata.obs['cell_labels']
```
  is categorical and free of missing values so CellPhoneDB groups cells correctly.
- Confirm values are log-normalised (
```
adata.X.max()
```
  should be <10 and non-integer); raw counts inflate CellPhoneDB permutations.

Run CellPhoneDB via omicverse

Execute

ov.single.run_cellphonedb_v5

with the curated AnnData and metadata column:

python

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,
)

Persist the outputs for reuse (
```
ov.utils.save(cpdb_results, ...)
```
,
```
adata_cpdb.write(...)
```
). Saving avoids recomputing permutations.

Initialise CellChat-style visualisation
- Create a colour dictionary that maps ordered
```
cell_labels
```
  categories to
```
adata.uns['cell_labels_colors']
```
  from previous plots.
- Instantiate the viewer:
```
viz = ov.pl.CellChatViz(adata_cpdb, palette=color_dict)
```
  . Inspect
```
adata_cpdb
```
  to ensure communication slots (
```
uns
```
  /
```
obsm
```
  ) were populated.
Summarise global communication
- Derive aggregated counts/weights with
```
viz.compute_aggregated_network(pvalue_threshold=0.05, use_means=True)
```
  .
- Plot overall interaction strength and counts using
```
viz.netVisual_circle(...)
```
  with matching figure sizes and colormaps.
- Generate outgoing/incoming per-celltype circles using
```
viz.netVisual_individual_circle
```
  and
```
viz.netVisual_individual_circle_incoming
```
  to highlight senders versus receivers.

Interrogate specific pathways

Compute pathway summaries:

pathway_comm = viz.compute_pathway_communication(method='mean', min_lr_pairs=2, min_expression=0.1)

Identify significant signalling routes with

viz.get_significant_pathways_v2(...)

, then plot selected pathways using

viz.netVisual_aggregate(..., layout='circle')

viz.netVisual_chord_cell(...)

, or

viz.netVisual_heatmap_marsilea(...)

For ligand–receptor focus, call

viz.netVisual_chord_LR(...)

viz.netAnalysis_contribution(pathway)

to surface dominant pairs.

System-level visualisations

Compose bubble summaries for multiple pathways with
```
viz.netVisual_bubble_marsilea(...)
```
, optionally restricting
```
sources_use
```
/
```
targets_use
```
.
Display gene-level chords via
```
viz.netVisual_chord_gene(...)
```
to inspect signalling directionality.

Evaluate signalling roles using

viz.netAnalysis_computeCentrality()

viz.netAnalysis_signalingRole_network_marsilea(...)

viz.netAnalysis_signalingRole_scatter(...)

, and

viz.netAnalysis_signalingRole_heatmap(...)

for incoming/outgoing programmes.

Troubleshooting tips
- Metadata alignment: CellPhoneDB requires a categorical
```
celltype_key
```
  . If the column contains spaces, mixed casing, or
```
NaN
```
  , clean it (
```
adata.obs['cell_labels'] = adata.obs['cell_labels'].astype('category').cat.remove_unused_categories()
```
  ).
- Database bundle:
```
cpdb_file_path
```
  must point to a full CellPhoneDB v5 SQLite zip. If omicverse raises
```
FileNotFoundError
```
  or missing receptor tables, re-download the bundle from the official release and ensure the zip is not corrupted.
- Permutation failures: Low cell counts per group (<
```
min_cells
```
  ) cause early termination. Increase
```
min_cell_fraction
```
  thresholds or merge sparse clusters before rerunning.
- Palette mismatches: When colours render incorrectly, rebuild
```
color_dict
```
  from
```
adata.uns['cell_labels_colors']
```
  after sorting categories to keep nodes and legends consistent.

准备环境
- 使用包含
```
omicverse>=0.2
```
  、
```
scanpy
```
  、
```
anndata
```
  、
```
pandas
```
  、
```
matplotlib
```
  以及
```
cellphonedb
```
  资源的环境。本教程假设预构建的CellPhoneDB v5 SQLite包已下载到工作目录，命名为
```
cellphonedb.zip
```
  。
- 通过
```
ov.plot_set()
```
  激活omicverse的绘图默认设置，以便后续图表遵循项目配色方案。
加载并筛选带注释的AnnData对象
- 使用
```
adata = ov.read('data/cpdb/normalised_log_counts.h5ad')
```
  读取归一化后的计数数据。
- 利用
```
adata.obs['cell_labels']
```
  筛选出感兴趣的细胞群体（例如EVT、dNK、VCT）。确保
```
adata.obs['cell_labels']
```
  为分类类型且无缺失值，以便CellPhoneDB正确分组细胞。
- 确认数据为对数归一化（
```
adata.X.max()
```
  应小于10且为非整数）；原始计数会导致CellPhoneDB的置换分析结果失真。

通过omicverse运行CellPhoneDB

使用整理好的AnnData和元数据列执行

ov.single.run_cellphonedb_v5

：

python

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,
)

保存输出结果以便复用（
```
ov.utils.save(cpdb_results, ...)
```
、
```
adata_cpdb.write(...)
```
）。保存操作可避免重复计算置换分析。

初始化CellChat风格的可视化
- 创建一个颜色字典，将排序后的
```
cell_labels
```
  分类映射到之前绘图中
```
adata.uns['cell_labels_colors']
```
  的颜色值。
- 实例化查看器：
```
viz = ov.pl.CellChatViz(adata_cpdb, palette=color_dict)
```
  。检查
```
adata_cpdb
```
  以确保通讯相关的存储槽（
```
uns
```
  /
```
obsm
```
  ）已填充数据。
汇总全局通讯情况
- 使用
```
viz.compute_aggregated_network(pvalue_threshold=0.05, use_means=True)
```
  生成汇总计数/权重。
- 使用
```
viz.netVisual_circle(...)
```
  绘制整体相互作用强度和计数，匹配合适的图幅大小和颜色映射。
- 使用
```
viz.netVisual_individual_circle
```
  和
```
viz.netVisual_individual_circle_incoming
```
  生成每个细胞类型的 outgoing/incoming 环形图，以突出发送方和接收方。

探究特定通路

计算通路汇总信息：

pathway_comm = viz.compute_pathway_communication(method='mean', min_lr_pairs=2, min_expression=0.1)

。

使用

viz.get_significant_pathways_v2(...)

识别显著的信号通路，然后使用

viz.netVisual_aggregate(..., layout='circle')

、

viz.netVisual_chord_cell(...)

或

viz.netVisual_heatmap_marsilea(...)

绘制选定通路。

若聚焦配体-受体对，可调用

viz.netVisual_chord_LR(...)

或

viz.netAnalysis_contribution(pathway)

来找出主导配对。

系统级可视化

使用
```
viz.netVisual_bubble_marsilea(...)
```
生成多个通路的气泡汇总图，可选择性限制
```
sources_use
```
/
```
targets_use
```
。
通过
```
viz.netVisual_chord_gene(...)
```
展示基因层面的弦图，以检查信号传导方向。

使用

viz.netAnalysis_computeCentrality()

、

viz.netAnalysis_signalingRole_network_marsilea(...)

、

viz.netAnalysis_signalingRole_scatter(...)

和

viz.netAnalysis_signalingRole_heatmap(...)

评估信号传导角色，分析 outgoing/incoming 程序。

故障排除提示
- 元数据对齐：CellPhoneDB要求
```
celltype_key
```
  为分类类型。若该列包含空格、大小写混合或
```
NaN
```
  ，请清理数据（
```
adata.obs['cell_labels'] = adata.obs['cell_labels'].astype('category').cat.remove_unused_categories()
```
  ）。
- 数据库包：
```
cpdb_file_path
```
  必须指向完整的CellPhoneDB v5 SQLite压缩包。若omicverse抛出
```
FileNotFoundError
```
  或提示缺失受体表，请从官方发布渠道重新下载压缩包并确保其未损坏。
- 置换分析失败：每组细胞数量过少（小于
```
min_cells
```
  ）会导致提前终止。可提高
```
min_cell_fraction
```
  阈值，或在重新运行前合并稀疏集群。
- 配色不匹配：若颜色渲染错误，请在排序分类后重新从
```
adata.uns['cell_labels_colors']
```
  构建
```
color_dict
```
  ，以保持节点和图例的一致性。

Examples

示例

"Run CellPhoneDB on our trophoblast dataset and export both the cpdb results pickle and processed AnnData."
"Highlight significant 'Signaling by Fibroblast growth factor' interactions with chord and bubble plots."
"Generate outgoing versus incoming communication circles to compare dNK subsets."

"在我们的滋养层数据集上运行CellPhoneDB，并导出cpdb结果的pickle文件和处理后的AnnData。"
"用弦图和气泡图突出显示显著的‘成纤维细胞生长因子信号传导’相互作用。"
"生成 outgoing 与 incoming 通讯环形图，以比较dNK亚群。"

References

参考资料

Tutorial notebook:
```
t_cellphonedb.ipynb
```

Example data:

omicverse_guide/docs/Tutorials-single/data/cpdb/

Quick copy/paste commands:
```
reference.md
```

教程笔记本：
```
t_cellphonedb.ipynb
```

示例数据：

omicverse_guide/docs/Tutorials-single/data/cpdb/

快速复制命令：
```
reference.md
```