Skip to content

docs: clarify how coordinates stored in tables are treated - #1274

Open
jan-glx wants to merge 3 commits into
docs/spatialdata-class-docstringfrom
docs/table-obsm-spatial-note
Open

jan-glx wants to merge 3 commits into
docs/spatialdata-class-docstringfrom
docs/table-obsm-spatial-note

Conversation

@jan-glx

@jan-glx jan-glx commented Oct 15, 2026 •

Copy link
Copy Markdown
Collaborator

(Stacked on #1273)

The SpatialData class docstring said that tables are stored as AnnData objects "with the spatial coordinates stored in the obsm slot". The library moved away from table coordinates early on (#123): tables have no coordinate system (design doc), and spatialdata never transforms, queries or validates coordinates stored in a table. The old line has likely contributed to recurring confusion, e.g. squidpy finding NaNs in obsm["spatial"] (#387), spatial queries ignoring centroids stored there (#573, #825), and queries crashing on tables that only carry obsm["spatial"] (#1248).

At the same time, obsm["spatial"] is the squidpy/scanpy convention (squidpy's default spatial_key, scanpy's sc.pl.spatial(basis="spatial")) and is populated widely in practice: by most spatialdata-io readers (xenium, visium, visium_hd, merscope, cosmx, dbit, mcmicro, steinbock), by the legacy-AnnData converter, and by spatialdata-plot's measure_obs (scverse/spatialdata-plot#705).
This PR therefore replaces the line with a description of the actual behaviour that names obsm["spatial"]
explicitly:

- tables are stored as :class:`anndata.AnnData` objects. Tables have no coordinate system: coordinates
  stored in a table (e.g. in ``obsm["spatial"]``, the squidpy/scanpy convention that several spatialdata-io
  readers populate) are currently not transformed or used by spatial queries, and can get out of sync with
  the SpatialElements the table annotates.

The SpatialData docstring said tables store "the spatial coordinates" in
the obsm slot. Since the move away from table coordinates (spatialdata
issue 123) the library does not process them (see docs/design_doc.md):
they have no coordinate system, are not transformed and are ignored by
spatial queries. Readers and tools nevertheless commonly populate
obsm["spatial"] (squidpy/scanpy convention), so name it explicitly and
state its limitations.
@jan-glx
jan-glx marked this pull request as ready for review October 15, 2026 14:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant