single-cellphone-db_skill

Overview

This skill runs omicverse's CellPhoneDB v5 wrapper on an annotated single-cell AnnData object to infer ligand–receptor communication networks and produce CellChat-style visualisations. It outputs reusable CPDB results and a processed AnnData ready for network summarisation and plotting. The workflow is tuned to generate circle, chord, bubble, heatmap, and centrality views of intercellular signalling.

How this skill works

The skill prepares a curated AnnData with categorical cell labels, calls ov.single.run_cellphonedb_v5 to perform permutation testing against a CellPhoneDB v5 SQLite bundle, and saves the results. It then instantiates ov.pl.CellChatViz on the processed AnnData to compute aggregated networks, pathway-specific summaries, and gene/LR-level contributions. Visualization functions produce CellChat-style plots and system-level analyses (centrality, signalling roles, bubbles, chords).

When to use it

• You have annotated single-cell RNA-seq data and want to quantify cell-type-level ligand–receptor interactions.
• You need CellPhoneDB v5-compatible permutation testing with reproducible outputs for downstream plots or publications.
• You want CellChat-style visual summaries (circle, chord, bubble, heatmap) of signalling networks from CPDB results.
• You need to identify pathway-specific signalling routes or dominant ligand–receptor pairs between groups.
• You want system-level metrics such as centrality and signalling role analyses for incoming/outgoing programmes.

Best practices

• Ensure adata.obs[celltype_key] is categorical, has no NaNs, and matches the ordered categories you want to visualise.
• Use log-normalised expression (adata.X non-integer, max < 10) to avoid inflated permutation signals.
• Provide a validated CellPhoneDB v5 SQLite zip via cpdb_file_path and persist cpdb_results and adata_cpdb to avoid recomputation.
• Set sensible min_cells/min_cell_fraction and iterations to balance sensitivity and runtime; save temporary outputs if permutations are long.
• Build a color dictionary from adata.uns['cell_labels_colors'] after ordering categories to keep node colours consistent.

Example use cases

• Run CellPhoneDB on trophoblast single-cell data and export cpdb_results plus the processed AnnData for sharing.
• Compare outgoing versus incoming signalling of dNK subsets using individual circle plots and centrality scatterplots.
• Highlight a pathway like 'Signaling by Fibroblast growth factor' with aggregate chord and bubble visualisations.
• Inspect dominant ligand–receptor pairs driving a pathway using netAnalysis_contribution and LR chord plots.