[Georicl]

Description

SpatialData inputs recompute element centroids on every spatial-neighbor call, even when the selected table already stores the required coordinates (#1199).

Add the keyword-only coordinate_source parameter to all six spatial-neighbor entry points. "elements" remains the default; "table" reads table.obsm[spatial_key] directly and skips centroid computation and coordinate transformation. Table mode validates coordinate type, shape and finite values while retaining region and instance association checks. copy=True isolates coordinates in the lightweight temporary AnnData; copy=False reuses the original array and saves graph results to the table.

Includes shared parameter documentation, a usage example and regression tests.

How has this been tested?

• Python 3.13.3/macOS ARM64: 154 passed across the four test files below, including all six interfaces, both copy modes, invalid inputs, multiple regions and read-only backed tables.
• Ruff v0.16.4 lint and formatting checks, and git diff --check, pass.
• All six expanded API docstrings checked; an offline Sphinx HTML smoke build passes with warnings treated as errors.

python -m pytest -p no:cov \
  tests/graph/test_spatial_neighbors_coordinate_source.py \
  tests/graph/test_spatial_neighbors_copy.py \
  tests/graph/test_spatial_neighbors.py \
  tests/utils/test_old_positionals.py

Performance

Previously measured at cbf140d on macOS ARM64/Python 3.13.3 with SpatialData 0.8.0: for 100,000 cells across 20 regions, median radius-graph time decreased from 0.68310 s to 0.43761 s (35.9%), and input preparation from 0.28549 s to 0.03208 s. These are medians of five calls using identical synthetic polygons and coordinates, radius 1.6, copy=True, n_jobs=1 and single-threaded numerical libraries; imports, warmup and initial coordinate preparation are excluded. Table mode made zero centroid calls and graph outputs matched the AnnData reference.

The benchmark script, method and recorded results remain available in the original commit.

Closes

Closes #1199.