single-cell-cellphonedb-communication-mapping（单细胞 cellphonedb 通信映射）

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

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

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

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

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

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

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

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