Cell-cell communication

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

Algorithms are ported from CellPhoneDB, NicheNet, and CellChat reference implementations in products/oncology/applications/.

Prerequisites

• Per-cell expression CSV with cell_id and gene columns
• Metadata CSV with cell_id, cell_type, and optional condition for comparison
• Optional custom ligand-receptor pair table (defaults to built-in database)

Launching the pipeline

Open the study Communication page or dispatch via API:

curl -X POST http://localhost:8001/oncology/jobs/cell-communication \
  -H "Content-Type: application/json" \
  -d '{
    "study_id": "your-study-id",
    "parameters": {
      "expression_path": "/path/to/expression.csv",
      "metadata_path": "/path/to/metadata.csv",
      "cell_type_column": "cell_type",
      "condition_column": "condition",
      "condition_a": "baseline",
      "condition_b": "treated",
      "permutations": 100,
      "top_n": 100
    }
  }'

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	NicheNet-style ligand activity scores
condition_comparison	Top interaction score deltas between conditions

The frontend Communication page renders sender/receiver heatmaps, chord diagrams, and pathway summaries from these artifacts.

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

Next steps

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