Cell-cell communication

Cell-cell communication analysis identifies ligand-receptor interactions across TME cell populations and compares signaling patterns between conditions.

The oncology implementation uses the shared Immunology communication engine, then adds tumor microenvironment interpretation: malignant, CAF, TAM/myeloid, immune, endothelial, and dendritic sender/receiver classes; tumor-immune and tumor-stroma context labels; IO pathway axis summaries; clinical metadata summaries; and spatial boundary priorities when coordinates or region labels exist.

When a CompBio single-cell CNV handoff has been reviewed through Oncology Malignant Cell Detection, use cnv_malignant_status and cnv_subclone_id as metadata columns to stratify tumor senders by inferred malignant state or CNV-defined subclone.

Prerequisites

• Per-cell expression CSV with cell_id and gene columns
• Metadata CSV with cell_id, cell_type, and optional condition for comparison
• Optional CNV-derived metadata fields from Malignant Cell Detection (cnv_malignant_status, cnv_subclone_id)
• Optional custom ligand-receptor pair table (defaults to built-in database)

Launching the pipeline

Open the study Communication page, select your expression and metadata datasets, and set the cell-type/condition columns and comparison groups before running.

Key parameters

Parameter	Default	Purpose
expression_path	—	Per-cell expression matrix CSV
metadata_path	—	Cell metadata with type and condition labels
ligand_receptor_path	built-in	Custom LR pair database
cell_type_column	cell_type	Column name for cell type labels
condition_column	—	Column for condition comparison
condition_a, condition_b	—	Groups to compare
min_cells	2	Minimum cells per type for scoring
min_expression_fraction	0.1	Minimum fraction of cells expressing a gene
permutations	0	Permutation count for p-value estimation
top_n	100	Maximum interactions returned

Outputs

Output	Description
interactions	Scored ligand-receptor pairs with sender/receiver cell types
pathways	Pathway-level aggregated signaling scores
network	Sender/receiver adjacency for network visualization
ligand_activity	Ligand activity scores
condition_comparison	Top interaction score deltas between conditions
oncology_context	TME classes, communication contexts, IO axis summaries, cancer-state program summaries, clinical strata
oncology_spatial	Region counts, cell-type spatial profiles, communication map edges, boundary priorities
tumor_board_summary	Research-use highlights and caveats

The frontend Communication page renders oncology summaries, TME context scores, IO axis summaries, spatial TME communication sections, top interactions, pathways, condition deltas, and clinical metadata summaries from these artifacts.

Ligand activity IO hypotheses

Use the separate ligand_activity pipeline when you want ligand-to-target hypotheses rather than only ligand-receptor interaction scores. It consumes per-cell expression and metadata, uses the shared Immunology ligand activity engine, and adds oncology target presets for exhaustion, interferon response, antigen presentation, suppression, and cytotoxicity.

This is a Python-native port of the NicheNet method (Browaeys et al., Nat Methods 2019), not an expression-abundance heuristic: it builds a receiver gene program from your condition comparison, then ranks candidate sender ligands by how well each one's regulatory-potential targets (from NicheNet's own prior model) predict that program — AUPR-corrected and Pearson metrics, with permutation-based p/q-values. A prioritization step then rank-scales ligand activity together with expression and condition-specificity to produce a ranked sender→receiver ligand-receptor table.

Outputs include ligand activity rankings with significance, active ligand-target and ligand-receptor links, the prioritized sender→receiver table, TME sender/receiver class annotations, clinical contrast summaries, and tumor-board-style hypothesis highlights. When the hosted NicheNet prior model isn't configured, results fall back to a small built-in demo prior with a caveat flag — check for this before treating rankings as comprehensive.

Typical use cases

• Compare immunosuppressive signaling between responders and non-responders
• Identify dominant cytokine axes in post-treatment samples
• Map co-stimulatory vs. checkpoint signaling across TME compartments
• Compare malignant subclone sender programs against immune or stromal receivers
• Prioritize tumor, stromal, or myeloid ligands that may explain T-cell exhaustion or interferon target programs

Next steps

• Immuno-oncology profiling
• Sample data — communication test fixtures
• Pipelines reference