/spatial-transcriptomics-cell-cell-communication

name: "spatial-transcriptomics-cell-cell-communication"
description: "Spatial cell-cell communication / ligand-receptor (LR) interaction analysis, one skill for every route: LIANA consensus ranking between annotated cell types, CellPhoneDB v5 permutation p-values, DEG method and spatial microenvironments, squidpy neighbourhood enrichment to keep spatially adjacent sender-receiver pairs, LIANA bivariate local LR scores on the tissue (works on Visium spots without labels), pathway-focused candidate evidence tables (immune checkpoints, chemokines, Notch, Wnt, TGF-beta) with contact vs secreted classes and PubMed co-mentions, and multi-sample Tensor-cell2cell and MISTy models. Xenium/MERFISH/CosMx cells, Visium spots, scRNA-seq. Route-specific steps follow the main workflow. Needs cell type labels first (spatial-transcriptomics-cell-type-annotation or a deconvolution skill)."
license: "CC-BY-4.0"

Spatial Cell-Cell Communication

Overview

Expression-based ligand-receptor (LR) inference ranks pairs that *could* signal; spatial data adds whether sender and receiver actually sit next to each other. This skill runs one inference (LIANA consensus by default, or CellPhoneDB statistics), puts the result into one table, keeps interactions whose cell types are spatial neighbours, scores LR co-expression at each location, and narrows the table to the user's question with an evidence class per candidate. Expression of both partners never proves signalling: every result is a candidate.

| Question | Route | |---|---| | Which LR pairs between my cell types, and are the types neighbours | Workflow Steps 1-6 | | Permutation p-values per pair, DEG-driven or microenvironment-restricted tests | Route: CellPhoneDB v5 Statistics, in place of Step 2 | | Where on the tissue an LR pair is co-expressed (labels not needed) | Step 5; p-value/category layers in Route: LIANA Multi-sample | | Communication differences across samples or conditions | Route: LIANA Multi-sample (by-sample ranking, Tensor-cell2cell) | | What in the neighbourhood explains cell type composition | Route: LIANA Multi-sample (MISTy) | | Literature support and which candidates to validate | After Step 6, Route: Literature Evidence |

All routes are in `## Task Routes` below the Workflow.

When to Use

• Finding which annotated cell types may signal to each other in a spatial section
• Separating interactions between neighbouring cell types from those between distant ones
• Testing which LR pairs are specific to a sender-receiver pair with CellPhoneDB p-values
• Mapping where on the tissue a ligand and its receptor are co-expressed, also on Visium spots
• Asking about one pathway family (immune checkpoints, chemokines, Notch, Wnt, TGF-beta) after inference
• Comparing communication programs across samples or conditions
• For neighbourhood enrichment or co-occurrence alone, without LR pairs, use `spatial-transcriptomics-analysis-squidpy`

Prerequisites

• **Input**: log-normalised expression in `X` (not z-scored) and `obsm["spatial"]`
• **Labels**: a cell type column in `obs` for Steps 2-4 and 6

(`spatial-transcriptomics-cell-type-annotation`). Visium spots have no labels: Step 5 works without them; Steps 2-4 need a deconvolution first (`spatial-transcriptomics-deconvolution-cell2location`)

• **Genes**: gene symbols; CellPhoneDB is human-only (mouse via orthologs, see its reference)
• **Python packages**: `liana`, `squidpy`, `scanpy`; `cellphonedb`, `cell2cell` only for their routes

# Install only what `import` reports missing. `--pypi` keeps the env's scanpy/numba
# stack; a conda add can swap it and bare pip can shadow it.
pixi add --pypi liana squidpy scanpy

Pre-flight Interview

decisions:
  - id: D1
    param: CELL_TYPE_KEY
    kind: required
    source: data
    ask: "Which column holds the cell types whose communication you want to study?"
    default: null

  - id: D2
    param: RESOURCE
    kind: required
    source: data
    ask: "The gene symbols look <human/mouse>: use the <human/mouse> ligand-receptor database?"
    default: "consensus for human symbols, mouseconsensus for mouse symbols"

  - id: D3
    param: METHOD
    kind: required
    source: user
    ask: "Rank interactions by agreement across several methods (LIANA consensus, recommended), or do you need CellPhoneDB permutation p-values per pair (slower, human symbols)?"
    default: "LIANA consensus"

  - id: D4
    param: QUERY
    kind: optional
    source: user
    ask: "Is there a pathway (immune checkpoints, chemokines, growth factors, Notch, Wnt, TGF-beta) or a sender -> receiver direction you care about?"
    default: "all pathways and all cell type pairs"

  - id: D5
    param: SAMPLE_KEY
    kind: required
    source: data
    skip_if: "the data holds a single sample"
    ask: "Which column identifies the samples, and which one the condition to compare?"
    default: null

  - id: D6
    param: expr_prop
    kind: optional
    source: user
    ask: "Minimum fraction of a cell type that must express each partner gene?"
    default: "0.1"

  - id: D7
    param: NEIGHBOUR_Z
    kind: optional
    source: user
    ask: "How strongly must two cell types co-locate to count as neighbours?"
    default: "neighbourhood z > 2 over 15 nearest neighbours"

  - id: D8
    param: BANDWIDTH
    kind: optional_conditional
    source: data
    ask: "The coordinates are in <microns/pixels>; how wide should the local neighbourhood be?"
    default: "from li.pp.query_bandwidth: a few to tens of neighbours per location"

  - id: D9
    param: REGION_KEY
    kind: optional_conditional
    source: data
    depends_on: [D3]
    skip_if: "METHOD is LIANA consensus"
    ask: "Should CellPhoneDB only test cell types that share a tissue region? If so, which region/niche column?"
    default: "no restriction"

  - id: D10
    param: n_perms
    kind: optional
    source: user
    ask: "How many permutations for p-values?"
    default: "1000 for nei