SpatialData abstract data model#
SpatialData (Marconato et al., 2025) is a data model for spatially resolved, multimodal datasets. It brings together images, segmentation masks, geometric objects, point clouds, and measurement tables, and relates them in two distinct ways: spatially, through coordinate systems and transformations that express the locations of spatial elements in common coordinates, and by annotation, through tables whose observations reference instances of spatial elements.
This page describes the abstract data model: the concepts and semantics that all implementations share, independently of how they represent them. Implementations may use different programming languages, data structures, metadata locations, and APIs, provided they interpret the data model consistently. The storage format specifies how datasets are serialized; it repeats each part of the data model and follows it with its storage.
Datasets and elements#
A SpatialData dataset is a collection of named elements of five types: images, labels, points, shapes, and tables. It may contain any number of elements of each type, including none. Element names must be unique within a dataset, even across different element types.
Elements may exist independently of each other, with their own coordinate systems and without annotations.
A dataset may also contain user-defined metadata.
The five element types. Tables annotate instances of labels, points and shapes.#
Spatial elements#
Four element types represent spatially located data: images, labels, points, and shapes.
The axes are the spatial axes x, y, and optionally z, and the channel axis c. Images and
labels have the spatial axes; images additionally have the channel axis. Points and shapes use
spatial coordinates rather than raster axes.[1]Units are not part of the current model: stores carry a placeholder unit.
Multiscale rasters represent the same spatial data at different resolutions. Their resolution levels belong to a single spatial element.
Images#
Images are two- or three-dimensional raster arrays of measurements, with one or more channels. They may have multiple resolution levels (multiscale images).
Labels#
Labels are two- or three-dimensional integer-valued raster arrays identifying spatial regions. Pixels with the same nonzero value belong to the same instance; zero represents the background. Labels may also be multiscale.
Points#
Points are collections of two- or three-dimensional locations, optionally associated with per-point values such as gene identity or intensity.
Shapes#
Shapes are collections of two-dimensional geometries: within one shapes element, either all
circles, each given by a centre and a positive radius, or all polygons and multipolygons. Each
geometry represents an individually identifiable instance. Geometries MUST be two-dimensional,
with axes x and y.[2]Outlook: z coordinates for shapes are expected to come through an RFC.
Coordinate systems and transformations#
SpatialData relates spatial elements through named coordinate systems, which provide common reference frames for interpreting their locations.
Each spatial element has an intrinsic coordinate system, defined by its spatial axes and coordinates. This coordinate system is specific to the element and may be unnamed.
A spatial element is associated with one or more named coordinate systems through coordinate transformations. Each transformation maps coordinates from the element’s intrinsic coordinate system to a named coordinate system. An element has at most one transformation to each named coordinate system.
Multiple elements may share a named coordinate system; their locations are then expressed in the same coordinates.
An element may be associated with multiple named coordinate systems, representing its location in different reference frames.
Named coordinate systems are identified by their name; they may exist only as a name, without a separate object.
Each spatial element has its own intrinsic coordinate system and is mapped into one or more named coordinate systems by coordinate transformations.#
Transformations include identity, axis mapping, translation, scaling, affine transformations, and their composition. They operate on named axes, independently of the order in which those axes are represented.
Transformations directly associate spatial elements with named coordinate systems, rather than relating pairs of spatial elements or named coordinate systems.[3]Outlook: with NGFF 0.6 support, transformations will relate named coordinate systems to each other, and an element may have more than one path into a coordinate system. Further transformations may be derived through composition and inversion where possible.
Coordinate transformations describe spatial relationships without modifying the underlying data. Applying transformations to raster or vector data is a separate operation.
A transformation places the raw data in space without changing it (top). Applying the transformation rewrites the data (bottom); both are positioned identically. The figure simplifies: the transformation that remains is shown as the identity, but a resampled raster generally keeps a translation that places it.#
Sharing a coordinate system does not imply spatial overlap or biological correspondence between elements. Elements without a shared coordinate system have no defined spatial relationship unless one can be established through a chain of transformations.
Tables have no spatial coordinate systems or coordinate transformations of their own.
Instances and identifiers#
Points, labels, and shapes can contain identifiable instances:
In labels, instances are identified by their nonzero integer values.
In shapes and points, each geometry or point has an identifier. Shape identifiers are unique within their element. Point identifiers may repeat; points can be annotated by a table only when their identifiers are unique within the element.[4]Points may carry a column naming the instance (for example a cell in a labels or shapes element) that each point was assigned to. This is a per-point value like any other.
Instance identifiers are local to their spatial element. An instance is therefore identified by the combination of its element name and instance identifier.
Different elements may represent the same biological objects, but matching identifiers or coordinates do not automatically establish correspondence.
Annotation tables#
Tables contain observations, variables, measurements, and associated annotations. They support observation-by-variable matrices, additional measurement layers, observation and variable metadata, and structured auxiliary data.
A table may annotate instances of points, labels, or shapes. In a table that annotates spatial elements, each observation references one spatial instance through two columns:
Element: The name of the spatial element being annotated.
Instance: The identifier of the instance within that element.
Together, these values identify the spatial instance referenced by an observation.
For example, the pixels with value 7 in a labels element cells form one instance. A table row
annotating it has element cells and instance 7. The row also has its own name (the row name of
the table), such as cell_7; it names the row, not the instance. A points element may record for each point the
cell it lies in, such as 7 in cells. That is a per-point value, not the point’s own identifier,
which is what a table annotating the points refers to.
A table may annotate multiple spatial elements, and a spatial element may be annotated by multiple tables. Within a table, each instance is referenced by at most one observation; spatial instances may have no corresponding observations.
Dangling references are valid. A table may refer to elements or instances that are not in the dataset, for example after subsetting or after deleting an element. Such references are ignored when the table is related to the dataset.
Tables may also exist without annotating any spatial elements.
Annotation relationships do not depend on coordinate systems or transformations.