squidpy.gr.spatial_neighbors_grid

squidpy.gr.spatial_neighbors_grid(data, *, spatial_key='spatial', elements_to_coordinate_systems=None, table_key=None, library_key=None, n_neighs=6, n_rings=1, delaunay=False, transform=None, set_diag=False, key_added='spatial', copy=False, n_jobs=1)[source]

Create a grid-based graph from spatial coordinates.

This is the mode used for Visium-like grid coordinates. It assumes observations lie on an approximately regular lattice, so it is usually not appropriate for continuous coordinates such as Xenium point clouds. On irregular coordinates, the resulting graph and ring distances may not have a meaningful grid interpretation.

Parameters:

adata – Annotated data object.
spatial_key (str) – Key in anndata.AnnData.obsm where spatial coordinates are stored.
elements_to_coordinate_systems (dict[str, str] | None) – A dictionary mapping element names of the SpatialData object to coordinate systems. The elements can be either Shapes or Labels. For compatibility, the spatialdata table must annotate all regions keys. Must not be None if adata is a spatialdata.SpatialData.
table_key (str | None) – Key in spatialdata.SpatialData.tables where the spatialdata table is stored. Must not be None if adata is a spatialdata.SpatialData.
library_key (str | None) – If multiple library_id, column in anndata.AnnData.obs which stores mapping between library_id and obs.
n_neighs (int) – Number of neighboring tiles used to form the base grid connectivity. Defaults to 6 for Visium-like grid coordinates.
n_rings (int) – Number of rings of neighbors. Defaults to 1. n_rings=1 keeps only immediate neighbors; larger values add progressively more distant shells and encode the shell number in dst. For example, n_neighs=3 with n_rings=2 on a Visium-like grid starts from a sparse three-neighbor base graph and then adds a second graph-distance ring relative to that base connectivity.
delaunay (bool) – Whether to derive the base grid connectivity from a Delaunay triangulation. This is still grid mode: unlike spatial_neighbors_delaunay(), the resulting distance matrix encodes grid or ring distances rather than Euclidean edge lengths. In practice, this changes how the first-ring connectivity is inferred, but not the meaning of the resulting distances.
percentile – Percentile of the distances to use as threshold.
transform (str | Transform | None) – Adjacency matrix transform ('spectral', 'cosine', or None).
set_diag (bool) – Whether to set the diagonal of the connectivities to 1.0.
key_added (str) – Key which controls where the results are saved if copy = False.
copy (bool) – If True, return the result, otherwise save it to the adata object.
n_jobs (int) – Number of parallel jobs used to build the per-library graphs when library_key is set. Each library’s graph is computed independently, so this only has an effect for multi-library data. 1 (default) builds the graphs sequentially and does not change behavior; -1 uses all available CPUs. Has no effect when library_key is None. Speedup is sub-linear (memory-bandwidth bound), and process-based backends pay a one-time worker start-up cost, so parallelism mainly pays off for many large libraries.

Return type:

SpatialNeighborsResult | None

Returns:

If copy = True, returns a SpatialNeighborsResult with the spatial connectivities and distances matrices.

Otherwise, modifies the adata with the following keys:

anndata.AnnData.obsp ['{key_added}_connectivities'] - the spatial connectivities.

anndata.AnnData.obsp ['{key_added}_distances'] - the spatial distances.

anndata.AnnData.uns ['{key_added}'] - dict containing parameters.