Single-cell CellPhoneDB communication mapping

Overview

Apply this skill when a user wants to quantify ligand-receptor communication between annotated single-cell populations and visualize the result with OmicVerse's CellPhoneDB plotting stack. This skill now covers both the original low-level ov.pl.CellChatViz workflow and the newer public plotting APIs:

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

Use the ccc_* functions by default when the goal is to quickly generate publication-ready plots with a stable public API. Drop down to CellChatViz when the user needs method-level control or wants to combine several custom visualizations in one notebook.

Instructions

1. Prepare the environment
   • Use an environment with omicverse>=0.2, scanpy, anndata, pandas, matplotlib, seaborn, and CellPhoneDB resources.
   • For the newer visualizations, also ensure these optional plotting dependencies are available when needed:
     • marsilea for heatmap and bubble matrix plotters.
     • mpl-chord-diagram for chord diagrams.
     • networkx for diffusion and network-style plots.
     • adjustText if the user wants improved automatic label repulsion.
   • Activate OmicVerse plotting defaults with ov.plot_set().
2. Load and validate the annotated AnnData
   • Read the normalized expression matrix with ov.read(...).
   • Keep the communication grouping column clean, categorical, and aligned with the intended identities.
   • Recommended checks:

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

   • Confirm the matrix is log-normalized before running CellPhoneDB. Raw counts can distort permutation-based significance.
3. Run CellPhoneDB through OmicVerse
   • Use ov.single.run_cellphonedb_v5(...) and persist the outputs:

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

   • Save cpdb_results and adata_cpdb so downstream plotting can be repeated without rerunning permutations.
4. Prefer the new public plotting APIs for standard visualization requests
   • Use ov.pl.ccc_heatmap(...) for matrix-like plots:
     • plot_type="heatmap" for aggregated pathway-level communication.
     • plot_type="focused_heatmap" to highlight stronger interactions after thresholding weak entries.
     • plot_type="dot" or "bubble" for interaction-level summaries.
     • plot_type="pathway_bubble" for pathway-focused Marsilea bubble summaries.
     • plot_type="bubble_lr" for ligand-receptor-pair-specific bubble matrices.
     • plot_type="role_heatmap", "role_network", or "role_network_marsilea" for signaling role summaries.
     • plot_type="diff_heatmap" when comparing two communication AnnData objects.
   • Use ov.pl.ccc_network_plot(...) for graph-like plots:
     • plot_type="circle" or "circle_focused" for global communication networks.
     • plot_type="individual_outgoing" / "individual_incoming" for sender- or receiver-centric circle panels.
     • plot_type="individual" for a single pathway and optionally a selected L-R pair.
     • plot_type="chord" for cell-type-level pathway chords.
     • plot_type="gene_chord" for gene-level chord diagrams across pathway-specific ligand and receptor nodes.
     • plot_type="lr_chord" for specified ligand-receptor pairs.
     • plot_type="diffusion" for pathway similarity and diffusion-style network structure.
     • plot_type="diff_network" when comparing two communication objects.
     • plot_type="bipartite", "arrow", "sigmoid", or "embedding_network" for alternative layouts.
   • Use ov.pl.ccc_stat_plot(...) for statistics and summary panels:
     • plot_type="pathway_summary" to rank pathways by communication strength and significance.
     • plot_type="lr_contribution" to show the dominant ligand-receptor pairs within a pathway.
     • plot_type="scatter" or "role_scatter" to compare outgoing versus incoming signaling roles.
     • plot_type="role_network" or "role_network_marsilea" for matrix-style role summaries.
     • plot_type="sankey" for communication flow summaries.
5. Use CellChatViz directly when the user needs method-level control
   • Create a stable palette mapping from cell labels:

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

   • Recommended direct workflow:
     • viz.compute_aggregated_network(...) then viz.netVisual_circle(...).
     • viz.compute_pathway_communication(...) then viz.get_significant_pathways_v2(...).
     • viz.netVisual_heatmap_marsilea(...) or viz.netVisual_heatmap_marsilea_focused(...).
     • viz.netVisual_bubble_marsilea(...) for pathway bubbles.
     • viz.netVisual_bubble_lr(...) for selected ligand-receptor pairs.
     • viz.netVisual_chord_cell(...), viz.netVisual_chord_gene(...), and viz.netVisual_chord_LR(...).
     • viz.netVisual_individual(...) for one pathway / one enriched pair.
     • viz.netAnalysis_computeCentrality() followed by role heatmap, scatter, and network plots.
     • viz.netAnalysis_contribution(pathway) for pathway-level pair contribution analysis.
     • viz.netVisual_diffusion(...) for pathway similarity structure.
6. Highlight the new visualization capabilities clearly
   • The newer additions worth surfacing in answers are:
     • gene_chord: gene-level chord diagrams, not just cell-type-level chords.
     • bubble_lr: Marsilea bubble summaries centered on explicit ligand-receptor pairs.
     • focused_heatmap: thresholded pathway heatmaps that suppress weak interactions.
     • role_network_marsilea: richer role summaries with dendrograms, color bars, and importance bars.
     • diffusion: pathway similarity network based on communication patterns.
     • pathway_summary and lr_contribution: higher-level summary/statistical views for prioritization.
   • When the user says "new visualization", prioritize demonstrating one of these rather than only the legacy circle plot.
7. Parameter tips for the newer plots
   • For pathway bubbles:
     • group_pathways=True groups by pathway rather than individual L-R pairs.
     • transpose=True is useful when too many cell-pair rows make labels unreadable.
     • add_violin=True can expose score distributions but makes figures denser.
   • For ligand-receptor bubbles:
     • show_all_pairs=True is useful when the user wants to compare a fixed panel of pairs even if some are weak or absent.
     • pair_lr_use or interaction_use should match the pair naming in adata.var.
   • For gene chords:
     • Require adata.var["gene_a"] and adata.var["gene_b"].
     • Use rotate_names=True when genes or cell-type labels are long.
   • For focused heatmaps and focused circle plots:
     • Tune min_interaction_threshold to remove weak edges before plotting.
   • For role plots:
     • Run viz.netAnalysis_computeCentrality() first when using the low-level API.
     • Use pattern="incoming" and pattern="outgoing" separately if the user wants interpretable sender vs receiver programs.
8. Troubleshooting
   • Metadata alignment: the communication grouping column must be categorical and free of missing values.
   • Database bundle: cpdb_file_path must point to a valid CellPhoneDB v5 SQLite zip.
   • Sparse groups: very small sender or receiver groups often cause unstable or empty outputs.
   • Missing columns in adata.var:
     • classification is needed for pathway-filtered plotting.
     • gene_a and gene_b are needed for gene-level or ligand-receptor-specific plots.
   • Optional dependency errors:
     • install marsilea for pathway_bubble, bubble_lr, focused heatmaps, and role-network Marsilea views.
     • install mpl-chord-diagram for chord plots.
     • install adjustText if label overlap is severe.
   • Palette mismatches: rebuild the palette from sorted categories in adata.obs[celltype_key].cat.categories and the corresponding adata.uns[f"{celltype_key}_colors"].

Examples

• "Run CellPhoneDB and then use ov.pl.ccc_heatmap(..., plot_type='focused_heatmap') to show the strongest pathways."
• "Create a gene-level chord diagram for FGF signaling with ov.pl.ccc_network_plot(..., plot_type='gene_chord')."
• "Compare selected ligand-receptor pairs across sender-receiver combinations with plot_type='bubble_lr'."
• "Summarize the top pathways and then rank within-pathway ligand-receptor contributions with ccc_stat_plot(..., plot_type='pathway_summary') and plot_type='lr_contribution'."
• "Use CellChatViz directly to compute centrality and render Marsilea role-network plots."

References

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