Spatial transcriptomics · ligand-receptor · cell communication · Squidpy
Why Spatial Context Matters for Cell Communication
Single-cell RNA-seq can tell you which ligands and receptors are expressed. It cannot tell you whether the cells expressing them are actually close enough to interact. Spatial transcriptomics closes that gap.
Two cells 500 µm apart in a tumor section are unlikely to exchange short-range signals regardless of what their transcriptomes predict. Squidpy's gr.ligrec and gr.nhood_enrichment functions let you ask both questions at once: what is being expressed, and are the right cells adjacent?
Figure 1. Left: ligand-receptor interaction scores between cell type pairs (* = p<0.05). Right: spatial co-occurrence z-scores — positive values indicate cell types that cluster together in tissue.
Setting Up the Interaction Database
Squidpy ships with a curated ligand-receptor database derived from CellChatDB and CellPhoneDB. You load it once and pass it to gr.ligrec:
import squidpy as sq
import scanpy as sc
# Load preprocessed Visium AnnData with cell type annotation in adata.obs["cell_type"]
adata = sc.read_h5ad("visium_annotated.h5ad")
# Build spatial graph first (required for proximity-aware analysis)
sq.gr.spatial_neighbors(adata, coord_type="grid", n_rings=2)
# Run ligand-receptor permutation test
sq.gr.ligrec(
adata,
n_perms=1000,
cluster_key="cell_type",
copy=False,
use_raw=False,
transmitter_params={"categories": "ligand"},
receiver_params={"categories": "receptor"},
)
# Results stored in adata.uns["cell_type_ligrec"]The permutation test shuffles cell type labels 1,000 times and asks: how often would this interaction score arise by chance given the spatial arrangement of cells? This is stricter than expression-only approaches because it accounts for the actual tissue layout.
Visualizing the Results
The raw output is a dictionary with means and pvalues DataFrames. Squidpy provides a dedicated dotplot:
sq.pl.ligrec(
adata,
cluster_key="cell_type",
source_groups="Macrophages",
target_groups=["T cells", "Cancer"],
means_range=(0.3, float("inf")), # filter weak interactions
alpha=0.05, # significance threshold
swap_axes=False,
figsize=(10, 6),
)Two practical filters here: means_range removes interactions with low absolute expression, and alpha applies the permutation p-value cutoff. Without both, the plot becomes unreadable with hundreds of LR pairs.
Neighborhood Enrichment: Are These Cells Actually Neighbors?
Before trusting any LR interaction, check whether the source and target cell types are spatially co-localized. gr.nhood_enrichment runs a permutation test on the spatial graph:
sq.gr.nhood_enrichment(adata, cluster_key="cell_type")
sq.pl.nhood_enrichment(
adata,
cluster_key="cell_type",
method="average",
cmap="RdBu_r",
vmin=-3, vmax=3,
figsize=(7, 6),
)Z-scores above +2 indicate strong spatial co-occurrence; below −2 indicates mutual exclusion. From the figure: Macrophages and Cancer cells co-occur strongly (z = 3.1) — a known feature of immunosuppressive tumor microenvironments where TAMs cluster around tumor nests. T cells and Fibroblasts are mutually exclusive (z = −0.9), consistent with fibroblast-mediated immune exclusion.
Combining Both Analyses: A Decision Framework
Use neighborhood enrichment as a gate before interpreting LR results:
High enrichment + significant LR → strong candidate interaction worth validating (e.g., SPP1-CD44 between Macrophages and Cancer)
Low enrichment + significant LR → likely expression artifact; cells aren't actually proximal enough to interact
High enrichment + no significant LR → cells co-localize for structural reasons (e.g., Fibroblasts around vessels) rather than active signaling
Key LR Pairs in the Tumor Microenvironment
These consistently appear in Visium TME datasets:
- SPP1 (OPN) → CD44: Macrophage-to-cancer signaling, promotes invasion and immunosuppression
- CXCL12 → CXCR4: T cell and cancer cell chemoattraction; CXCR4 inhibition is a clinical target
- VEGFA → KDR (VEGFR2): Tumor-to-endothelial angiogenic signaling; highest scores near vessel-rich regions
- TGFB1 → TGFBR2: Fibroblast-mediated immunosuppression and ECM remodeling
- PDGFB → PDGFRB: Pericyte recruitment by endothelial cells; marks active neovascularization zones
Performance Notes
gr.ligrec with 1,000 permutations on a full Visium slide (~3,500 spots, 10+ cell types) takes 5–15 minutes on a standard laptop. Use n_jobs=-1 to parallelize across CPU cores. For exploratory work, drop to n_perms=200 first to check the output structure, then rerun with 1,000 for publication figures.
# Fast exploratory run
sq.gr.ligrec(adata, n_perms=200, cluster_key="cell_type", n_jobs=-1)
# Extract top interactions programmatically
import pandas as pd
means = adata.uns["cell_type_ligrec"]["means"]
pvals = adata.uns["cell_type_ligrec"]["pvalues"]
# Filter: mean > 0.5, p < 0.05 for Macrophage->Cancer axis
mac_cancer = means.loc[:, ("Macrophages", "Cancer")]
sig = mac_cancer[pvals.loc[:, ("Macrophages", "Cancer")] < 0.05]
print(sig.sort_values(ascending=False).head(10))What's Next
Ligand-receptor analysis identifies candidate interactions. The next step is spatial trajectory analysis — reconstructing how gene expression changes as you move from one tissue region to another, which reveals which signals are active at each point along the tumor-stroma interface.
Working in tumor microenvironment biology? The companion blog NeoantigenLab covers the immunotherapy side — checkpoint inhibitor mechanisms, neoantigen prediction pipelines, and CAR-T biology for the same cell types you're mapping spatially.
Get the complete pack
SpatiaBio Squidpy Pack 1 — 16 Notebooks ($19)
All 16 notebooks — neighborhood enrichment, co-occurrence, ligand-receptor, spatial autocorrelation, publication figures, and the complete workflow. Includes memory tips for Visium HD. Ready to run on your own data.
Get it for $19 →From the NeoantigenLab sister blog
Working with tumor transcriptomics for neoantigen research?
NeoantigenLab covers neoantigen biology, WES pipelines, pVACseq, and HLA typing for experimental researchers — the biology behind what you're sequencing.
Visit NeoantigenLab →
