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.cccnetworkplot(...)
• ov.pl.cccstatplot(...)

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: ``python celltypekey = "celllabels" assert celltypekey in adata.obs.columns, f"{celltypekey} missing from adata.obs" adata.obs[celltypekey] = adata.obs[celltypekey].astype("category").cat.removeunusedcategories() assert not adata.obs[celltypekey].isna().any(), f"NaN values found in {celltypekey}" minpergroup = adata.obs[celltypekey].valuecounts().min() if minpergroup < 10: print(f"WARNING: smallest group has {minpergroup} 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.runcellphonedbv5(...) and persist the outputs: ``python cpdbresults, adatacpdb = ov.single.runcellphonedbv5( adata, cpdbfilepath="./cellphonedb.zip", celltypekey="celllabels", mincellfraction=0.005, mingenes=200, mincells=3, iterations=1000, threshold=0.1, pvalue=0.05, threads=10, outputdir="./cpdbresults", cleanuptemp=True, ) ` - Save cpdbresults 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.cccheatmap(...) for matrix-like plots: - plottype="heatmap" for aggregated pathway-level communication. - plottype="focusedheatmap" to highlight stronger interactions after thresholding weak entries. - plottype="dot" or "bubble" for interaction-level summaries. - plottype="pathwaybubble" for pathway-focused Marsilea bubble summaries. - plottype="bubblelr" for ligand-receptor-pair-specific bubble matrices. - plottype="roleheatmap", "rolenetwork", or "rolenetworkmarsilea" for signaling role summaries. - plottype="diffheatmap" when comparing two communication AnnData objects. - Use ov.pl.cccnetworkplot(...) for graph-like plots: - plottype="circle" or "circlefocused" for global communication networks. - plottype="individualoutgoing" / "individualincoming" for sender- or receiver-centric circle panels. - plottype="individual" for a single pathway and optionally a selected L-R pair. - plottype="chord" for cell-type-level pathway chords. - plottype="genechord" for gene-level chord diagrams across pathway-specific ligand and receptor nodes. - plottype="lrchord" for specified ligand-receptor pairs. - plottype="diffusion" for pathway similarity and diffusion-style network structure. - plottype="diffnetwork" when comparing two communication objects. - plottype="bipartite", "arrow", "sigmoid", or "embeddingnetwork" for alternative layouts. - Use ov.pl.cccstatplot(...) for statistics and summary panels: - plottype="pathwaysummary" to rank pathways by communication strength and significance. - plottype="lrcontribution" to show the dominant ligand-receptor pairs within a pathway. - plottype="scatter" or "rolescatter" to compare outgoing versus incoming signaling roles. - plottype="rolenetwork" or "rolenetworkmarsilea" 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: ``python colordict = dict(zip( adata.obs["celllabels"].cat.categories, adata.uns["celllabelscolors"] )) viz = ov.pl.CellChatViz(adatacpdb, palette=colordict) ` - Recommended direct workflow: - viz.computeaggregatednetwork(...) then viz.netVisualcircle(...). - viz.computepathwaycommunication(...) then viz.getsignificantpathwaysv2(...). - viz.netVisualheatmapmarsilea(...) or viz.netVisualheatmapmarsileafocused(...). - viz.netVisualbubblemarsilea(...) for pathway bubbles. - viz.netVisualbubblelr(...) for selected ligand-receptor pairs. - viz.netVisualchordcell(...), viz.netVisualchordgene(...), and viz.netVisualchordLR(...). - viz.netVisualindividual(...) for one pathway / one enriched pair. - viz.netAnalysiscomputeCentrality() followed by role heatmap, scatter, and network plots. - viz.netAnalysiscontribution(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: - genechord: gene-level chord diagrams, not just cell-type-level chords. - bubblelr: Marsilea bubble summaries centered on explicit ligand-receptor pairs. - focusedheatmap: thresholded pathway heatmaps that suppress weak interactions. - rolenetworkmarsilea: richer role summaries with dendrograms, color bars, and importance bars. - diffusion: pathway similarity network based on communication patterns. - pathwaysummary 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: - grouppathways=True groups by pathway rather than individual L-R pairs. - transpose=True is useful when too many cell-pair rows make labels unreadable. - addviolin=True can expose score distributions but makes figures denser. - For ligand-receptor bubbles: - showallpairs=True is useful when the user wants to compare a fixed panel of pairs even if some are weak or absent. - pairlruse or interactionuse should match the pair naming in adata.var. - For gene chords: - Require adata.var["genea"] and adata.var["geneb"]. - Use rotatenames=True when genes or cell-type labels are long. - For focused heatmaps and focused circle plots: - Tune mininteractionthreshold 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: cpdbfilepath 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. - genea and geneb are needed for gene-level or ligand-receptor-specific plots. - Optional dependency errors: - install marsilea for pathwaybubble, bubblelr, 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[celltypekey].cat.categories and the corresponding adata.uns[f"{celltypekey}_colors"].

Examples

• "Run CellPhoneDB and then use ov.pl.cccheatmap(..., plottype='focused_heatmap') to show the strongest pathways."
• "Create a gene-level chord diagram for FGF signaling with ov.pl.cccnetworkplot(..., plottype='genechord')."
• "Compare selected ligand-receptor pairs across sender-receiver combinations with plottype='bubblelr'."
• "Summarize the top pathways and then rank within-pathway ligand-receptor contributions with cccstatplot(..., plottype='pathwaysummary') and plottype='lrcontribution'."
• "Use CellChatViz directly to compute centrality and render Marsilea role-network plots."

References

• Tutorial notebook: [tcellphonedb.ipynb](../../omicverseguide/docs/Tutorials-single/t_cellphonedb.ipynb)
• Example data: [omicverseguide/docs/Tutorials-single/data/cpdb/](../../omicverseguide/docs/Tutorials-single/data/cpdb/)
• Quick copy/paste commands: [reference.md](reference.md)