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:

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(...) or 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.

Defensive validation

# Before CellPhoneDB: validate cell type column
assert celltype_key in adata.obs.columns, f"Column '{celltype_key}' not found in 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 in '{celltype_key}' — clean before running CellPhoneDB"
min_per_group = adata.obs[celltype_key].value_counts().min()
if min_per_group < 10:
    print(f"WARNING: smallest cell group has {min_per_group} cells — may cause permutation failures")

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.

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."

References

Tutorial notebook: t_cellphonedb.ipynb
Example data: omicverse_guide/docs/Tutorials-single/data/cpdb/
Quick copy/paste commands: reference.md

single-cell-cellphonedb-communication-mapping

Single-cell CellPhoneDB communication mapping

Overview