Bio Spatial Transcriptomics Spatial Neighbors

Version Compatibility

Reference examples tested with: squidpy 1.4+, scanpy 1.10+, anndata 0.10+, numpy 1.26+

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.

Spatial Neighbor Graphs

"Build a spatial neighbor graph for my tissue" -> Define which cells or spots count as spatial neighbors, encoded as a sparse weights matrix W over adata.obsm['spatial'].

• Python: squidpy.gr.spatial_neighbors() -> writes adata.obsp['spatial_connectivities'] and adata.obsp['spatial_distances']

The platform-class fork sets the default geometry. Sequencing/capture data on a fixed lattice (Visium hex, Visium HD grid) has a KNOWN adjacency -> use coord_type='grid'. Imaging/in-situ point clouds (Xenium, MERFISH, CosMx) have irregular cell positions -> use coord_type='generic' with Delaunay or kNN. The first question is always which side of the fork the data is on, because it decides whether "neighbor" is a lattice fact or a modeling choice.

Governing Principle

The graph is the model that all spatial statistics inherit. Moran's I, Geary's C, neighborhood enrichment, co-occurrence, and every graph-neural-network spatial-domain method are functions f(expression, W) of the spatial weights matrix W -- the graph is not preprocessing, it is literally an argument to the statistic. Change k from 6 to 30, switch Delaunay to kNN, or row-standardize W instead of leaving it binary, and the Moran's I value, the enrichment z-scores, the SVG ranking, and the domain boundaries all move. The analyst is never measuring "spatial structure"; they are measuring spatial structure as seen through one particular definition of adjacency.

This is the most under-reported researcher degree of freedom in the field, and it has a name geographers settled decades ago: the modifiable areal unit problem -- aggregate or re-adjacency the units and the answer changes. There is no canonical W. The honest workflow therefore does what almost no paper does: build the graph under at least two definitions, rerun the downstream statistic, and report which genes/pairs/domains are graph-robust versus graph-fragile. A result that survives only one graph choice is a result about that graph, not about the tissue.

Two failure directions bound the choice. Too dense a graph (large k, large radius, many rings) over-smooths -- it inflates apparent autocorrelation, washes out local detail, and merges distinct domains into blobs. Too sparse a graph fragments the tissue into disconnected components, flags spurious local outliers, and misses real medium-scale structure. The right density is the one whose downstream conclusion is stable; the specific k is not the deliverable, the stability across k is.

The Graph-Construction Decision

Each family silently assumes something different about the tissue, and that assumption -- not the algorithm -- is what fails.

Three points the naive analyst misses. squidpy.gr.nhood_enrichment builds NO graph of its own -- it consumes whatever graph spatial_neighbors already stored in obsp (and errors if none exists); the Squidpy non-grid default is kNN with n_neighs=6 (delaunay=False), so a published z-score is specific to whichever graph produced it and would change under a different graph -- always know which graph produced the number. kNN is asymmetric; "mutual kNN" (edge only if both cells are in each other's k-set) is more conservative and stops hub cells in dense regions from dominating. Unpruned Delaunay over tissue with necrotic holes or folds connects cells micrometers apart on the slide but biologically unrelated -- pruning by a max edge length is the standard fix.

Variable Cell Density: There Is No Free Lunch

A fixed-radius neighborhood gives dense regions more neighbors and sparse regions fewer. Because neighborhood enrichment, co-occurrence, and local statistics all depend on neighbor COUNTS, a pure density gradient masquerades as biological signal: a dense lymphoid follicle gets inflated "enrichment" of everything simply because every cell there has more neighbors. kNN fixes the count (it adapts the radius to local density) but then distorts physical distance -- a "neighbor" in sparse stroma may sit far away. The density structure of the tissue dictates which distortion is tolerable: use kNN/Delaunay when density varies (the common case in real tissue); reserve fixed-radius for roughly uniform tissue where an absolute physical interaction range is the actual biological question.

The Coordinate-Unit Trap

A radius, a co-occurrence interval, and a Delaunay pruning cutoff are all in PHYSICAL distance units. If adata.obsm['spatial'] holds pixels, array row/col indices, or arbitrary units, a "50-unit radius" is silently meaningless. Visium array row/col is a lattice index, not microns; full-resolution Visium pixel coordinates need the Space Ranger scale factor (spot_diameter_fullres, tissue_hires_scalef) to convert to physical distance. Imaging platforms store microns or pixels depending on the reader. Confirm the unit BEFORE setting any distance parameter -- the single cheapest check is to measure nearest-neighbor spacing and compare it to the known platform pitch (Visium ~100 microns center-to-center).

Goal: Confirm the coordinate unit so that any radius is physically meaningful.

Approach: Measure median nearest-neighbor distance from a temporary kNN graph and compare it to the known platform geometry; a Visium grid in microns should read ~100, in pixels it reads hundreds-to-thousands.

import squidpy as sq
import scanpy as sc
import numpy as np

sq.gr.spatial_neighbors(adata, coord_type='generic', n_neighs=1)   # nearest neighbor only, just to read spacing
nn = adata.obsp['spatial_distances'].data
print(f'median nearest-neighbor spacing: {np.median(nn):.1f} units')
# Visium pitch is ~100 microns; a value of hundreds-to-thousands means coords are in PIXELS -> rescale or use grid mode

Build the Graph by Platform Class

Goal: Construct the adjacency that matches the platform geometry rather than a one-size default.

Approach: Use grid mode for Visium hex (the lattice is exact and known); use generic Delaunay or kNN for imaging point clouds; store under named keys so multiple graphs coexist for the sensitivity check below.

# Visium hex lattice: 6 immediate neighbors per ring; n_rings=2 widens the neighborhood deliberately
sq.gr.spatial_neighbors(adata, coord_type='grid', n_neighs=6, n_rings=1, key_added='visium_hex')

# Imaging point cloud, fixed-degree: constant k, radius adapts to local density
sq.gr.spatial_neighbors(adata, coord_type='generic', n_neighs=10, key_added='knn10')

# Imaging point cloud, parameter-free contact graph (delaunay=True is opt-in; the
# generic default is kNN with n_neighs=6)
sq.gr.spatial_neighbors(adata, coord_type='generic', delaunay=True, key_added='delaunay')

Prune Delaunay Long Edges Across Tissue Gaps

Goal: Stop Delaunay from inventing long-range "neighbors" that leap across necrotic holes, folds, or slide background.

Approach: Build Delaunay, then prune to a physically sensible maximum edge length using radius as a (min, max) interval -- edges longer than max (in microns) are dropped.

# radius as a (min, max) tuple prunes the graph to edges within that physical-distance interval;
# choose max from the tissue: a few cell diameters (e.g. 50 microns) kills cross-gap edges, keeps true contacts
sq.gr.spatial_neighbors(adata, coord_type='generic', delaunay=True, radius=(0.0, 50.0), key_added='delaunay_pruned')

pruned = adata.obsp['delaunay_pruned_connectivities']
print(f'edges after pruning: {pruned.nnz}; mean degree: {pruned.nnz / adata.n_obs:.1f}')