GPTomics/bio-spatial-transcriptomics-spatial-communication

Version Compatibility

Reference examples tested with: squidpy 1.4+, scanpy 1.10+, anndata 0.10+, commot 0.0.3+

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

COMMOT is the distance-aware alternative shown below; LIANA+ wraps and benchmarks several methods/databases; CellChat v2 (R) and NicheNet (R) are noted in the decision table but not coded here.

Spatial Cell-Cell Communication

"Map cell-cell communication in my spatial data" -> Score ligand mRNA in a sender population against receptor mRNA in a receiver population, optionally weighted by spatial proximity, against a permutation null.

• Python: squidpy.gr.ligrec (CellPhoneDB engine, space-blind) or commot.tl.spatial_communication (optimal transport, distance-aware)
• R: CellChat v2 spatial mode, or NicheNet for downstream receiver-response linkage

Governing Principle

Co-expression is not communication, and segmentation spillover fabricates exactly the short-range signal these tools reward.

Every standard tool (squidpy ligrec, COMMOT, CellChat, CellPhoneDB, stLearn, SpaTalk, NicheNet) ultimately computes some function of ligand mRNA in a sender cell type and receptor mRNA in a receiver cell type, against a permutation null. None measures protein, binding, secretion, diffusion, or a downstream response. A "significant" ligand-receptor pair means "ligand mRNA in A and receptor mRNA in B are spatially co-expressed above a permutation null, under database D and radius r" -- a co-expression HYPOTHESIS, full stop. The field routinely reports these correlative pairs in the language of validated signaling ("cell type A signals to B via pathway X"); a careful analyst refuses that wording and reads every call as a testable hypothesis (Armingol 2021 Nat Rev Genet 22:71-88).

Spatial proximity is a weak filter, not evidence. A distance constraint removes the absurd long-range calls a non-spatial method would make, but two cells being adjacent and co-expressing a pair is nowhere near sufficient for signaling. Adding a radius converts an implausible call into a plausible-looking hypothesis -- that is all it does.

The spillover circularity is the spatial-specific trap. In imaging platforms, distance-dependent transcript mis-assignment between adjacent cells (segmentation spillover) bleeds a sender's ligand transcripts into a touching receiver and vice versa, manufacturing precisely the short-range ligand-receptor co-occurrence these methods detect. A "hit" between two touching cell types can therefore be pure segmentation artifact, and spillover is strongest between adjacent heterotypic cells -- the exact pairs a communication analysis is built to find (Mitchel 2026 Nat Genet 58:434). Validate every short-range call against segmentation quality before believing it (see spatial-transcriptomics/image-analysis).

The database is result-determining, as much as the algorithm. CellPhoneDB, CellChatDB, and other resources differ in content, complex/subunit handling, and curation; swapping the resource changes the inferred network as much as or more than swapping the method (Dimitrov 2022 Nat Commun 13:3224). Two tools agreeing is often two tools sharing a database, not independent confirmation. Report the database and version as a primary methods parameter.

On capture/spot platforms there is a second spatial trap distinct from imaging spillover: a Visium spot is a 1-10-cell MIXTURE, so the "cell types" fed to a communication tool are deconvolution estimates, and a ligand and its receptor can co-reside within the SAME multi-cell spot with no inter-cellular signaling implied at all. Running ligrec on spot clusters treats regions/niches as cell types and compounds deconvolution error into the L-R call. Prefer single-cell-resolution data, or deconvolve first and restrict the analysis to spots where the sender and receiver types are estimated to be present, and read spot-level calls as the weakest rung of the confidence ladder.

Method Decision Table

The first question is not "which tool" -- it is "does this method actually model spatial distance, and does it distinguish secreted from contact-dependent range?" Most do not.

| Method | Spatial mechanism | L-R database | Best when | Fails when | |--------|-------------------|--------------|-----------|------------| | squidpy ligrec (CellPhoneDB engine) | NONE by default -- permutes cluster labels; any cluster can "talk" to any cluster | CellPhoneDB (via omnipath) | Fast scanpy-native CellPhoneDB baseline on large data | Misused as "spatial" -- it is space-blind unless cells are pre-restricted; sensitive to clustering granularity | | COMMOT (Cang & Nie) | Collective optimal transport; distance COST with a per-pathway cutoff; isotropic, diffusion-like | CellPhoneDB/CellChat-derived, built in | True spatial data; want competition among L-R species + sender/receiver direction maps | One characteristic length per pathway -- cannot separate secreted vs contact; sensitive to the cutoff; transport is not flux | | stLearn cci | L-R co-expression within local neighborhoods; two-level (label + position) permutation | User-supplied (CellPhoneDB-style) | Spot/imaging hotspot maps of where a pair co-occurs | Tests spatial co-expression enrichment, not signaling; depends on neighborhood radius | | CellChat v2 (spatial mode, R) | Distance constraint applied as a FILTER on an expression-driven mass-action score | CellChatDB (cofactor-aware; differs from CellPhoneDB) | Pathway-level aggregation, cofactor/antagonist modeling, hierarchy summaries | Mass-action over group-averaged expression is not kinetics; spatial mode still filters a non-spatial score | | NicheNet (R) | NONE -- not spatial; uses analyst-defined sender/receiver sets | Curated integrated prior network | Linking a ligand to DOWNSTREAM target-gene response in the receiver | Not a detector; the prior is fixed/generic; a "top ligand" is a prior-weighted hypothesis | | MISTy (R) | Multi-view random forests over juxta/para radii; reports view importances | NONE -- marker-to-marker, no L-R DB | Highly-multiplexed imaging; dissecting spatial co-variation without an L-R DB | Models correlative spatial structure, not signaling flux |

Secreted vs contact-dependent ligands need DIFFERENT ranges, and most tools apply ONE cutoff to all pairs. A juxtacrine pair (Notch-Delta, contact-only) and a diffusible chemokine have categorically different interaction lengths; a single global radius over-calls one class and misses the other. Paracrine spread is a reaction-diffusion process, not a hard radius -- interrogate any fixed cutoff (the ~500 um conventions in the literature are conveniences, not biology). Because methods and databases genuinely compete here, verify current best practice against the latest LIANA+/benchmark docs before committing.

The Confidence Ladder

A communication claim earns confidence by climbing, not by a low p-value:

co-expression (bare L-R) < proximity-conditioned co-expression < downstream receiver-response support (NicheNet target DE up in neighboring receivers) < orthogonal protein co-localization (the ligand AND receptor protein imaged together) < perturbation (block the ligand/receptor, measure the receiver).

Almost nothing in the spatial literature reaches the perturbation tier. The single most defensible computational move is to require BOTH spatial proximity AND a coherent downstream transcriptional response in the receiver: co-expression proposes, receiver-response disposes.

Space-Blind Baseline (squidpy ligrec)

Goal: Rank ligand-receptor pairs that are co-expressed across annotated cell-type pairs as a fast CellPhoneDB-style baseline.

Approach: Run the permutation engine over cluster labels; recognize this is space-blind -- it tests "is this pair unusual for these two cell types," not "is this pair unusually co-located." It needs cell-type annotations (see spatial-transcriptomics/spatial-domains) and fetches the database from omnipath (internet required).

import squidpy as sq

adata = sq.datasets.seqfish()                            # built-in single-cell-resolution fixture with celltype labels
res = sq.gr.ligrec(
    adata,
    cluster_key='celltype_mapped_refined',
    n_perms=1000,                                        # permutation null; more = stabler p-values, slower
    threshold=0.01,                                      # min FRACTION of cells in a cluster expressing the gene -- NOT a p-value
    use_raw=False,                                       # seqfish has no .raw; default True errors here
    copy=True,
)
pvalues = res['pvalues']                                 # MultiIndex columns = (cluster_1, cluster_2), index = (ligand, receptor)
means = res['means']

The threshold argument is the expression-fraction floor inside the engine, not a significance cutoff -- mislabeling it as a p-value is a common error. The default fetches all omnipath interactions; pass interactions=<DataFrame with 'source'/'target'> to pin a known database/version.

Honest Significance and Multiple Testing

Goal: Extract co-expression hypotheses without manufacturing a network from nominal p-values.

Approach: The test space is thousands of L-R pairs times every ordered cell-type pair; correct over the full space and treat survivors as ranked hypotheses, not findings.

import numpy as np
import pandas as pd
from statsmodels.stats.multitest import multipletests

flat = pvalues.stack([0, 1], future_stack=True).rename('pval').reset_index()
flat = flat.dropna(subset=['pval'])
flat['padj'] = multipletests(flat['pval'].values, method='fdr_bh')[1]   # correct over the WHOLE pair x celltype-pair space
hits = flat[flat['padj'] < 0.05].sort_values('padj')
print(f'{len(hits)} co-expression hypotheses survive BH-FDR out of {len(flat)} tests')

Reporting top-ranked pairs at nominal p without an honest corrected null is how interaction networks get manufactured. Label permutation and position permutation answer different questions; neither asks "is there signaling."

Distance-Aware Inference (COMMOT)

Goal: Score communication with spatial distance actually in the model, and respect a finite signaling range rather than letting any cluster talk to any cluster.

Approach: Optimal transport moves ligand "mass" to receptor "mass" across real coordinates under a per-pathway distance cost; set dis_thr to the signaling length scale and handle heteromeric complexes explicitly. Use micron coordinates, not pixels.

import commot as ct

# database= identifiers drift across commot releases -- verify against the installed version
df_ligrec = ct.pp.ligand_receptor_database(database='CellPhoneDB_v4.0', species='human')
ct.tl.spatial_communication(
    adata,
    database_name='cellphonedb',
    df_ligrec=df_ligrec,
    dis_thr=200,                                         # signaling range in COORDINATE UNITS (um) -- one length per pathway, isotropic
    heteromeric=True,                                    # respect multi-subunit complexes (e.g. TGFBR1_TGFBR2)
)
# sender/receiver signaling stored in adata.obsm['commot-cellphonedb-sum-sender'] / '-receiver'

dis_thr is a single characteristic length applied isotropically -- it cannot distinguish a contact-only pair from a diffusing cytokine, so set it per pathway when secreted and juxtacrine pairs are both in play, and report it. Optimal transport gives a directional, competition-aware map, but "transport" is a model device, not measured flux.

Visualize and Audit

Goal: Inspect top pairs while keeping the spillover and panel caveats visible.

Approach: Plot the ligrec dotplot for chosen sender/receiver groups, then overlay the actual ligand and receptor expression in space to eyeball whether a "hit" sits exactly at a cell-type boundary (the spillover signature).

sq.pl.ligrec(res, source_groups='Endothelium', alpha=0.05, swap_axes=True)

If a short-range hit localizes to the seam between two touching cell types, suspect transcript spillover before signaling: re-check the segmentation, or test whether the pair survives on a re-segmented (Baysor/proseg) matrix.

Common Errors

| Symptom | Cause | Fix | |---------|-------|-----| | "Cell type A signals to B via pathway X" written as a finding | Treating an L-R score as validated signaling | Report it as a co-expression hypothesis; climb the confidence ladder (receiver-response, protein co-localization, perturbation) | | Short-range hit between two touching cell types that vanishes after re-segmentation | Distance-dependent transcript spillover manufactured the co-occurrence | Validate against segmentation quality; re-run on a Baysor/proseg matrix (spatial-transcriptomics/image-analysis) | | Two tools "confirm" the same interaction | They share the same L-R database, not independent evidence | Report database + version as a primary parameter; vary the resource (Dimitrov 2022) | | Juxtacrine pair over-called or cytokine missed | One global distance cutoff applied to secreted and contact-dependent pairs alike | Set range per signaling class; interrogate any fixed radius (~500 um is a convention) | | sq.gr.ligrec results look space-aware but are not | ligrec permutes cluster labels -- it is space-blind by default | Use COMMOT/stLearn for distance-modeled inference, or pre-restrict cells to a neighborhood | | L-R call between two cell types inside one Visium spot | A spot is a 1-10-cell mixture; "cell types" are deconvolution estimates and both genes can live in the same spot | Prefer single-cell-resolution data, or deconvolve then restrict to spots where both types are present; treat spot-level calls as the weakest evidence | | Hundreds of "significant" pairs at nominal p | No correction over thousands of pair x cell-type-pair tests | Apply BH-FDR over the FULL test space; treat survivors as ranked hypotheses | | Almost no genes match the database; "no communication found" | Targeted imaging panel (Xenium/MERFISH/CosMx) lacks the relevant ligands/receptors/cofactors | Absence on a panel is uninformative; check panel coverage before concluding | | threshold filters nothing / errors as a p-value | threshold is the expression-fraction floor, not a significance cutoff | Set it as a fraction (e.g. 0.01-0.1); filter significance on pvalues afterward | | ValueError about .raw in ligrec | use_raw=True default with no .raw present | Pass use_raw=False |

Related Skills

• spatial-transcriptomics/image-analysis - the segmentation-spillover circularity that fabricates short-range L-R hits; validate here first
• spatial-transcriptomics/spatial-neighbors - build the spatial graph that distance-aware methods inherit
• spatial-transcriptomics/spatial-statistics - neighborhood enrichment and permutation-null co-occurrence for which-types-co-occur questions
• spatial-transcriptomics/spatial-domains - annotate the cell types that define senders and receivers
• single-cell/cell-communication - the non-spatial CellPhoneDB/CellChat/NicheNet baseline and database choice
• pathway-analysis/go-enrichment - enrich downstream receiver-response programs (note: enrichment on predicted L-R lists is circular)

References

• Cang Z, Zhao Y, Almet AA, et al. (2023) Screening cell-cell communication in spatial transcriptomics via collective optimal transport (COMMOT). Nature Methods 20(2):218-228. DOI 10.1038/s41592-022-01728-4
• Dimitrov D, Turei D, Garrido-Rodriguez M, et al. (2022) Comparison of methods and resources for cell-cell communication inference from single-cell RNA-Seq data. Nature Communications 13:3224. DOI 10.1038/s41467-022-30755-0
• Palla G, Spitzer H, Klein M, et al. (2022) Squidpy: a scalable framework for spatial omics analysis. Nature Methods 19(2):171-178. DOI 10.1038/s41592-021-01358-2
• Jin S, Guerrero-Juarez CF, Zhang L, et al. (2021) Inference and analysis of cell-cell communication using CellChat. Nature Communications 12:1088. DOI 10.1038/s41467-021-21246-9
• Browaeys R, Saelens W, Saeys Y (2020) NicheNet: modeling intercellular communication by linking ligands to target genes. Nature Methods 17(2):159-162. DOI 10.1038/s41592-019-0667-5
• Pham D, Tan X, Balderson B, et al. (2023) Robust mapping of spatiotemporal trajectories and cell-cell interactions in healthy and diseased tissues (stLearn). Nature Communications 14:7739. DOI 10.1038/s41467-023-43120-6
• Tanevski J, Ramirez Flores RO, Gabor A, et al. (2022) Explainable multiview framework for dissecting spatial relationships from highly multiplexed data (MISTy). Genome Biology 23:97. DOI 10.1186/s13059-022-02663-5
• Mitchel J, Gao T, Petukhov V, et al. (2026) Impact and correction of segmentation errors in spatial transcriptomics. Nature Genetics 58:434-444. DOI 10.1038/s41588-025-02497-4
• Armingol E, Officer A, Harismendy O, Lewis NE (2021) Deciphering cell-cell interactions and communication from gene expression. Nature Reviews Genetics 22(2):71-88. DOI 10.1038/s41576-020-00292-x