spatial_neigbours extensibility features and clarification

docs/api.md

@@ -18,6 +18,12 @@ import squidpy as sq
     :toctree: api
 
     gr.spatial_neighbors
+    gr.spatial_neighbors_from_builder
+    gr.spatial_neighbors_knn
+    gr.spatial_neighbors_radius
+    gr.spatial_neighbors_delaunay
+    gr.spatial_neighbors_grid
+    gr.GraphMatrixT
     gr.SpatialNeighborsResult
     gr.mask_graph
     gr.nhood_enrichment
@@ -109,3 +115,27 @@ import squidpy as sq
     datasets.visium_hne_image_crop
     datasets.visium_fluo_image_crop
 ```
+
+
+## Extensibility
+
+See the {doc}`extensibility guide </extensibility>` for how to implement a custom graph builder.
+
+```{eval-rst}
+.. module:: squidpy.gr.neighbors
+.. currentmodule:: squidpy
+.. autosummary::
+    :toctree: api
+
+    gr.neighbors.GraphBuilder
+    gr.neighbors.GraphBuilderCSR
+    gr.neighbors.GraphMatrixT
+    gr.neighbors.GraphPostprocessor
+    gr.neighbors.DistanceIntervalPostprocessor
+    gr.neighbors.PercentilePostprocessor
+    gr.neighbors.TransformPostprocessor
+    gr.neighbors.KNNBuilder
+    gr.neighbors.RadiusBuilder
+    gr.neighbors.DelaunayBuilder
+    gr.neighbors.GridBuilder
+```

docs/extensibility.md

@@ -0,0 +1,104 @@
+# Extensibility
+
+## Custom graph builders
+
+The `squidpy.gr.neighbors` module exposes two builder base classes:
+
+- {class}`~squidpy.gr.neighbors.GraphBuilder` is the generic builder pipeline.
+  Use it when you want to plug in a custom coordinate type or sparse-matrix backend.
+- {class}`~squidpy.gr.neighbors.GraphBuilderCSR` is the CSR-specialized builder used
+  by the built-in graph construction strategies. Use it when your builder returns
+  {class}`~scipy.sparse.csr_matrix` objects and should reuse Squidpy's CSR-specific
+  postprocessors, sparse warning suppression, and multi-library combination.
+- Reusable postprocessors such as
+  {class}`~squidpy.gr.neighbors.DistanceIntervalPostprocessor`,
+  {class}`~squidpy.gr.neighbors.PercentilePostprocessor`, and
+  {class}`~squidpy.gr.neighbors.TransformPostprocessor` are also exposed for
+  custom builder composition.
+
+### What to override
+
+| Base class | Method / property | Required | Purpose |
+|---|---|---|---|
+| {class}`~squidpy.gr.neighbors.GraphBuilder` | {meth}`~squidpy.gr.neighbors.GraphBuilder.build_graph` | yes | Construct and return ``(adj, dst)`` using the coordinate and matrix types of your custom backend. |
+| {class}`~squidpy.gr.neighbors.GraphBuilder` | {meth}`~squidpy.gr.neighbors.GraphBuilder.postprocessors` | no | Return post-build processing steps for ``(adj, dst)``. You can either override this or pass ``postprocessors=...`` to ``super().__init__()``. |
+| {class}`~squidpy.gr.neighbors.GraphBuilder` | {meth}`~squidpy.gr.neighbors.GraphBuilder.combine` | no | Combine per-library results when using ``library_key``. If you do not need ``library_key`` support, leaving this unimplemented is fine. |
+
+
+The generic builder only defines the pipeline. The CSR-specialized builder adds
+multi-library ``library_key`` combination and
+{class}`~scipy.sparse.SparseEfficiencyWarning` suppression, while built-in and
+custom CSR builders can compose the public reusable postprocessors for
+distance-interval pruning, percentile filtering, and adjacency transforms.
+
+Here ``adj`` and ``dst`` are square sparse matrices of shape ``(n_obs, n_obs)``
+with matching sparsity structure:
+
+- ``adj`` is the connectivity / adjacency matrix. Non-zero entries mark edges in
+  the graph, and built-in builders typically use ``1.0`` for present edges.
+- ``dst`` is the distance matrix for those same edges. For generic graphs this is
+  usually the Euclidean edge length. For grid builders it may instead encode
+  graph-distance semantics such as ring number.
+- When subclassing {class}`~squidpy.gr.neighbors.GraphBuilderCSR`, both should be
+  returned as {class}`~scipy.sparse.csr_matrix`.
+- For CSR-based builders, ``adj`` often behaves like a boolean or indicator
+  matrix describing whether an edge is present, even if it is stored with a
+  numeric dtype such as ``float32``. ``dst`` stores edge-associated values such
+  as distances and will often use a floating-point dtype. The exact dtype choice
+  is left to the builder implementation and may depend on performance, memory,
+  and numerical accuracy requirements.
+- By convention, ``dst`` should have a zero diagonal, and ``adj`` should only
+  have a non-zero diagonal when ``set_diag=True``.
+
+### Example: fast radius search with SNN
+
+The built-in {class}`~squidpy.gr.neighbors.RadiusBuilder` uses scikit-learn's
+``NearestNeighbors``. The [snnpy](https://github.com/nla-group/snn) library
+provides a faster exact fixed-radius search based on PCA-based pruning. The
+example below swaps the backend while keeping full compatibility with the rest
+of the Squidpy graph pipeline:
+
+```python
+import numpy as np
+from scipy.sparse import csr_matrix
+from snnpy import build_snn_model
+
+from squidpy.gr.neighbors import GraphBuilderCSR
+
+
+class SNNRadiusBuilder(GraphBuilderCSR):
+    """Radius graph using the SNN fixed-radius search backend."""
+
+    def __init__(self, radius: float, **kwargs):
+        super().__init__(**kwargs)
+        self.radius = radius
+
+    def build_graph(self, coords):
+        N = coords.shape[0]
+        model = build_snn_model(coords, verbose=0)
+        indices, dists = model.batch_query_radius(
+            coords, self.radius, return_distance=True,
+        )
+
+        row = np.repeat(np.arange(N), [len(idx) for idx in indices])
+        col = np.concatenate(indices)
+        d = np.concatenate(dists).astype(np.float64)
+
+        adj = csr_matrix(
+            (np.ones(len(row), dtype=np.float32), (row, col)),
+            shape=(N, N),
+        )
+        dst = csr_matrix((d, (row, col)), shape=(N, N))
+
+        adj.setdiag(1.0 if self.set_diag else adj.diagonal())
+        dst.setdiag(0.0)
+        return adj, dst
+```
+
+Use it like any other builder:
+
+```python
+import squidpy as sq
+
+sq.gr.spatial_neighbors_from_builder(adata, SNNRadiusBuilder(radius=100.0))
+```

docs/index.md

@@ -63,6 +63,7 @@ We are happy about any contributions! Before you start, check out our [contribut
     installation
     api
     classes
+    extensibility
     release_notes
     references
     contributing

src/squidpy/_docs.py

@@ -359,6 +359,33 @@ def decorator2(obj: Any) -> Any:
     If multiple `library_id`, column in :attr:`anndata.AnnData.obs`
     which stores mapping between ``library_id`` and obs."""
 
+_sdata_params = """\
+elements_to_coordinate_systems
+    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 :class:`spatialdata.SpatialData`.
+table_key
+    Key in :attr:`spatialdata.SpatialData.tables` where the spatialdata table is stored. Must not be ``None`` if
+    ``adata`` is a :class:`spatialdata.SpatialData`."""
+_graph_common_params = """\
+percentile
+    Percentile of the distances to use as threshold.
+transform
+    Adjacency matrix transform (``'spectral'``, ``'cosine'``, or ``None``).
+set_diag
+    Whether to set the diagonal of the connectivities to ``1.0``.
+key_added
+    Key which controls where the results are saved if ``copy = False``."""
+_spatial_neighbors_returns = """\
+If ``copy = True``, returns a :class:`~squidpy.gr.SpatialNeighborsResult` with the
+spatial connectivities and distances matrices.
+
+Otherwise, modifies the ``adata`` with the following keys:
+
+    - :attr:`anndata.AnnData.obsp` ``['{key_added}_connectivities']`` - the spatial connectivities.
+    - :attr:`anndata.AnnData.obsp` ``['{key_added}_distances']`` - the spatial distances.
+    - :attr:`anndata.AnnData.uns`  ``['{key_added}']`` - :class:`dict` containing parameters."""
+
 d = DocstringProcessor(
     adata=_adata,
     img_container=_img_container,
@@ -401,4 +428,7 @@ def decorator2(obj: Any) -> Any:
     groups=_groups,
     plotting_library_id=_plotting_library_id,
     library_key=_library_key,
+    sdata_params=_sdata_params,
+    graph_common_params=_graph_common_params,
+    spatial_neighbors_returns=_spatial_neighbors_returns,
 )

src/squidpy/gr/__init__.py

@@ -2,7 +2,18 @@
 
 from __future__ import annotations
 
-from squidpy.gr._build import SpatialNeighborsResult, mask_graph, spatial_neighbors
+from squidpy.gr import neighbors
+from squidpy.gr._build import (
+    GraphMatrixT,
+    SpatialNeighborsResult,
+    mask_graph,
+    spatial_neighbors,
+    spatial_neighbors_delaunay,
+    spatial_neighbors_from_builder,
+    spatial_neighbors_grid,
+    spatial_neighbors_knn,
+    spatial_neighbors_radius,
+)
 from squidpy.gr._ligrec import ligrec
 from squidpy.gr._nhood import (
     NhoodEnrichmentResult,
@@ -16,10 +27,17 @@
 from squidpy.gr._sepal import sepal
 
 __all__ = [
+    "GraphMatrixT",
     "SpatialNeighborsResult",
     "NhoodEnrichmentResult",
+    "neighbors",
     "mask_graph",
     "spatial_neighbors",
+    "spatial_neighbors_from_builder",
+    "spatial_neighbors_knn",
+    "spatial_neighbors_radius",
+    "spatial_neighbors_delaunay",
+    "spatial_neighbors_grid",
     "ligrec",
     "centrality_scores",
     "interaction_matrix",