bio-spatial-transcriptomics-spatial-communication

name	bio-spatial-transcriptomics-spatial-communication
description	Maps cell-cell communication and ligand-receptor co-expression in spatial transcriptomics (Visium, Xenium, MERFISH, CosMx, Slide-seq) with Squidpy ligrec, COMMOT, stLearn, CellChat-spatial, and NicheNet. Use when choosing a method by whether spatial distance is actually modeled (squidpy ligrec is space-blind cluster-permutation vs COMMOT optimal-transport is distance-aware vs stLearn neighborhood vs CellChat-spatial filter) and by secreted-vs-contact-dependent range; choosing the ligand-receptor database knowingly because it drives the result as much as the algorithm; guarding against segmentation-spillover circularity that fabricates short-range hits; treating every ligand-receptor score as a co-expression hypothesis on a confidence ladder, not validated signaling; correcting for thousands of pair-by-cell-type-pair permutation tests; and recognizing that a targeted imaging panel rarely contains the relevant ligands and receptors so a "no communication" call is uninformative.
tool_type	python
primary_tool	squidpy

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 present

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