squidpy.gr.spatial_neighbors_from_builder

squidpy.gr.spatial_neighbors_from_builder(data, builder, *, spatial_key='spatial', elements_to_coordinate_systems=None, table_key=None, library_key=None, key_added='spatial', copy=False, n_jobs=1)[source]

Create a graph from spatial coordinates using an explicit builder instance.

This function is the bridge between the high-level API (e.g., spatial_neighbors_knn(), spatial_neighbors_radius()) and advanced customization via builder classes. Use this when you need to:

Stack or chain builder behaviors
Pass pre-configured builder instances multiple times
Implement custom builders (see Extensibility)

Parameters:

adata – Annotated data object.
builder (GraphBuilder[Any, Any]) – Graph construction strategy to execute. Built-in builders subclass {{class}}`~squidpy.gr.neighbors.GraphBuilderCSR`, while custom backends can implement the more generic {{class}}`~squidpy.gr.neighbors.GraphBuilder` interface directly. Reusable post-build operations are also exposed via DistanceIntervalPostprocessor, PercentilePostprocessor, and TransformPostprocessor. Custom builders only need to implement multi-library support when using library_key; otherwise leaving combine() unimplemented is fine.
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.
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.