/sc-cell-communication

name: sc-cell-communication
description: Load when computing cell-cell ligand-receptor communication on an annotated scRNA AnnData
  via builtin scorer, LIANA, CellPhoneDB, CellChat (R), or NicheNet (R). Skip when assigning cell-type
  labels (use sc-cell-annotation); transcription factor → target regulatory networks (use sc-grn).
trigger: cell communication, cell-cell communication, ligand receptor, cellchat, liana, cellphonedb, nichenet
tags:
- singlecell
- scrna
- cell-communication
- ligand-receptor
- liana
- cellphonedb
- cellchat
- nichenet

sc-cell-communication

When to use

The user has an annotated scRNA AnnData (cell-type labels in `obs["cell_type"]` or another column passed via `--cell-type-key`) and wants ligand-receptor / sender-receiver interaction tables and figures. Five backends:

• `builtin` (default) — compact curated L-R set, heuristic score, no p-values.
• `liana` — Python LIANA rank aggregation (recommended general default).
• `cellphonedb` — official CellPhoneDB statistical workflow (human-only).
• `cellchat_r` — R-backed CellChat with pathway / centrality outputs.
• `nichenet_r` — R-backed NicheNet ligand prioritisation; needs explicit `--receiver` + `--senders` + `--condition-*` (human-only).

For TF → target gene regulatory networks use `sc-grn`. For cell-type labelling use `sc-cell-annotation`.

Use in an analysis step

Use `load_skill` from the notebook SDK; write returned objects with `write_output`. This runnable example is also in `examples/example_step.py`. The CLI remains available for standalone reports and galleries.

# Rank curated ligand-receptor mean products across PBMC clusters.
# Reads pbmc3k_processed and uses its log-normalized raw snapshot.
# Calls sc-cell-communication: communicate, sender_receiver_summary, interaction_heatmap_figure.
# The builtin method does not test statistical significance.

from skills._sdk.notebook import load_demo, load_skill, write_output

communication = load_skill('sc-cell-communication')
adata = load_demo('pbmc3k_processed').raw.to_adata()

table = communication.communicate(adata, cell_type_key='louvain')
write_output(table, 'tables/lr_interactions.csv')
write_output(communication.sender_receiver_summary(table), 'tables/sender_receiver.csv')
write_output(communication.interaction_heatmap_figure(table), 'figures/interaction_heatmap.png')

assert not table.empty
assert table.pvalue.isna().all()
assert (table.score > 0).all()
assert set(table.source).issubset(set(adata.obs['louvain'].astype(str)))

Inputs & Outputs

Input is an annotated AnnData. builtin, LIANA, CellPhoneDB and CellChat use normalized X; NicheNet needs count-like data. PCA and neighbors are not required. The API returns an interaction DataFrame, with backend diagnostics and optional tables accessible through helpers.

The CLI writes `processed.h5ad`, `report.md`, `result.json`, and `tables/lr_interactions.csv`, `top_interactions.csv`, `sender_receiver_summary.csv`, `group_role_summary.csv`, `pathway_summary.csv`. CellChat can add pathway, centrality, count and weight tables; CellPhoneDB can add means, p-values and significant means; NicheNet can add ligand activities and target links. Those tables and the corresponding figures are conditional. Backend exchange files are temporary.

Flow

1. Load AnnData; preflight `--cell-type-key`, species, and per-method requirements (e.g., NicheNet needs `--receiver` / `--senders` / `--condition-*`). 2. Dispatch via `communicate` to the chosen backend (one of `builtin` / `liana` / `cellphonedb` / `cellchat_r` / `nichenet_r`). 3. Standardise the L-R table to columns `ligand`, `receptor`, `source`, `target`, `score`, `pvalue`, `pathway`. 4. Build sender-receiver / role / pathway summaries. 5. Detect "no interactions found" and print a UX-guardrail message; do NOT raise. 6. Save tables, figures, `processed.h5ad`, `report.md`, `result.json` (incl. `score_semantics` / `significance_semantics` / `pvalue_available`).

Gotchas

• `run_info(table)["fallback_used"]` is false: a missing selected backend raises; the API does not silently switch to builtin.
• builtin scores are grouped ligand mean × receptor mean, not interaction probabilities. `pvalue` is NaN and `n_significant` is zero.
• LIANA's `specificity_rank` is a consensus rank, not a p-value. `tables/lr_interactions.csv` retains that column, leaves `pvalue` NaN and reports zero significant interactions. Its default seed is 1337; the wrapper retains its existing species-independent resource selection.
• CellPhoneDB is human-only and now passes seed 0 to `debug_seed`. `cellphonedb_lr(random_state=...)` changes it. Its v4.1.0 database downloads on first use to the user's cache; this is not an offline path unless cached.
• CellChat and NicheNet need their R dependency stacks. NicheNet is human-only and also requires `lr_network_human_21122021.rds` and `weighted_networks_nsga2r_final.rds` under the user's `.cache/omicsclaw/nichenet/`; the wrapper does not download them.
• Empty interaction tables are valid output. Check `run_info(table)["n_interactions_tested"]` before plotting or interpreting them.

Key CLI

# Demo (built-in annotated PBMC)
python skills/singlecell/scrna/sc-cell-communication/sc_cell_communication.py --demo --output /tmp/sc_ccc_demo

# Default builtin scorer (heuristic, no pvalue)
python skills/singlecell/scrna/sc-cell-communication/sc_cell_communication.py \
  --input annotated.h5ad --output results/

# LIANA rank aggregation (recommended general default)
python skills/singlecell/scrna/sc-cell-communication/sc_cell_communication.py \
  --input annotated.h5ad --output results/ --method liana

# CellPhoneDB statistical (human only)
python skills/singlecell/scrna/sc-cell-communication/sc_cell_communication.py \
  --input annotated.h5ad --output results/ \
  --method cellphonedb --cellphonedb-iterations 1000 --cellphonedb-threshold 0.1

# CellChat R workflow
python skills/singlecell/scrna/sc-cell-communicatio