spatialdata.SpatialData

class spatialdata.SpatialData(images=mappingproxy({}), labels=mappingproxy({}), points=mappingproxy({}), shapes=mappingproxy({}), table=None)

The SpatialData object.

The SpatialData object is a modular container for arbitrary combinations of SpatialElements. The elements can be accesses separately and are stored as standard types (anndata.AnnData, geopandas.GeoDataFrame, xarray.DataArray).

Parameters:

• images (dict[str, Union[SpatialImage, MultiscaleSpatialImage]] (default: mappingproxy({}))) – Dict of 2D and 3D image elements. The following parsers are available: Image2DModel, Image3DModel.

• labels (dict[str, Union[SpatialImage, MultiscaleSpatialImage]] (default: mappingproxy({}))) – Dict of 2D and 3D labels elements. Labels are regions, they can’t contain annotation, but they can be annotated by a table. The following parsers are available: Labels2DModel, Labels3DModel.

• points (dict[str, DataFrame] (default: mappingproxy({}))) – Dict of points elements. Points can contain annotations. The following parsers is available: PointsModel.

• shapes (dict[str, GeoDataFrame] (default: mappingproxy({}))) – Dict of 2D shapes elements (circles, polygons, multipolygons). Shapes are regions, they can’t contain annotation, but they can be annotated by a table. The following parsers are available: ShapesModel.

• table (Optional[AnnData] (default: None)) – AnnData table containing annotations for regions (labels and shapes). The following parsers is available: TableModel.

Notes

The SpatialElements are stored with standard types:

• images and labels are stored as spatial_image.SpatialImage or

  multiscale_spatial_image.MultiscaleSpatialImage objects, which are respectively equivalent to xarray.DataArray and to a datatree.DataTree of xarray.DataArray objects.

• points are stored as dask.dataframe.DataFrame objects.

• shapes are stored as geopandas.GeoDataFrame.

• the table are stored as anndata.AnnData objects, with the spatial coordinates stored in the obsm

  slot.

The table can annotate regions (shapesor labels) and can be used to store additional information. Points are not regions but 0-dimensional locations. They can’t be annotated by a table, but they can store annotation directly.

The elements need to pass a validation step. To construct valid elements you can use the parsers that we provide:

• Image2DModel,

• Image3DModel,

• Labels2DModel,

• Labels3DModel,

• PointsModel,

• ShapesModel,

• TableModel

Attributes table

coordinate_systems
images	Return images as a Dict of name to image data.
labels	Return labels as a Dict of name to label data.
path
points	Return points as a Dict of name to point data.
query
shapes	Return shapes as a Dict of name to shape data.
table	Return the table.

Methods table

add_image(name, image[, storage_options, ...])	Add an image to the SpatialData object.
add_labels(name, labels[, storage_options, ...])	Add labels to the SpatialData object.
add_points(name, points[, overwrite])	Add points to the SpatialData object.
add_shapes(name, shapes[, overwrite])	Add shapes to the SpatialData object.
aggregate([values_sdata, values, by_sdata, ...])	Aggregate values by given region.
contains_element(element[, raise_exception])	Check if the SpatialElement is contained in the SpatialData object.
filter_by_coordinate_system(coordinate_system)	Filter the SpatialData by one (or a list of) coordinate system.
from_elements_dict(elements_dict)	Create a SpatialData object from a dict of elements.
init_from_elements(elements[, table])	Create a SpatialData object from a dict of named elements and an optional table.
is_backed()	Check if the data is backed by a Zarr storage or if it is in-memory.
read(file_path[, selection])	Read a SpatialData object from a Zarr storage (on-disk or remote).
transform_element_to_coordinate_system(...)	Transform an element to a given coordinate system.
transform_to_coordinate_system(...)	Transform the SpatialData to a given coordinate system.
write(file_path[, storage_options, ...])	Write the SpatialData object to Zarr.

Attributes

SpatialData.coordinate_systems

SpatialData.images

Return images as a Dict of name to image data.

SpatialData.labels

Return labels as a Dict of name to label data.

SpatialData.path: Optional[str] = None

SpatialData.points

Return points as a Dict of name to point data.

SpatialData.query

SpatialData.shapes

Return shapes as a Dict of name to shape data.

SpatialData.table

Return the table.

Returns:

The table.

Methods

SpatialData.add_image(name, image, storage_options=None, overwrite=False)

Add an image to the SpatialData object.

Parameters:

• name (str) – Key to the element inside the SpatialData object.

• image (SpatialImage | MultiscaleSpatialImage) – The image to add, the object needs to pass validation (see Image2DModel and Image3DModel).

• storage_options (Union[Dict[str, Any], list[Dict[str, Any]], None] (default: None)) – Storage options for the Zarr storage. See https://zarr.readthedocs.io/en/stable/api/storage.html for more details.

• overwrite (bool (default: False)) – If True, overwrite the element if it already exists.

Return type:

None

Notes

If the SpatialData object is backed by a Zarr storage, the image will be written to the Zarr storage.

SpatialData.add_labels(name, labels, storage_options=None, overwrite=False)

Add labels to the SpatialData object.

Parameters:

• name (str) – Key to the element inside the SpatialData object.

• labels (SpatialImage | MultiscaleSpatialImage) – The labels (masks) to add, the object needs to pass validation (see Labels2DModel and Labels3DModel).

• storage_options (Union[Dict[str, Any], list[Dict[str, Any]], None] (default: None)) – Storage options for the Zarr storage. See https://zarr.readthedocs.io/en/stable/api/storage.html for more details.

• overwrite (bool (default: False)) – If True, overwrite the element if it already exists.

Return type:

None

Notes

If the SpatialData object is backed by a Zarr storage, the image will be written to the Zarr storage.

SpatialData.add_points(name, points, overwrite=False)

Add points to the SpatialData object.

Parameters:

• name (str) – Key to the element inside the SpatialData object.

• points (DataFrame) – The points to add, the object needs to pass validation (see spatialdata.PointsModel).

• storage_options – Storage options for the Zarr storage. See https://zarr.readthedocs.io/en/stable/api/storage.html for more details.

• overwrite (bool (default: False)) – If True, overwrite the element if it already exists.

Return type:

None

Notes

If the SpatialData object is backed by a Zarr storage, the image will be written to the Zarr storage.

SpatialData.add_shapes(name, shapes, overwrite=False)

Add shapes to the SpatialData object.

Parameters:

• name (str) – Key to the element inside the SpatialData object.

• shapes (GeoDataFrame) – The shapes to add, the object needs to pass validation (see ShapesModel).

• storage_options – Storage options for the Zarr storage. See https://zarr.readthedocs.io/en/stable/api/storage.html for more details.

• overwrite (bool (default: False)) – If True, overwrite the element if it already exists.

Return type:

None

Notes

If the SpatialData object is backed by a Zarr storage, the image will be written to the Zarr storage.

SpatialData.aggregate(values_sdata=None, values=None, by_sdata=None, by=None, value_key=None, agg_func='sum', target_coordinate_system='global', fractions=False, region_key='region', instance_key='instance_id', deepcopy=True, **kwargs)

Aggregate values by given region.

Return type:

SpatialData

Notes

This function calls spatialdata.aggregate() with the convenience that values and by can be string without having to specify the values_sdata and by_sdata, which in that case will be replaced by self.

Please see spatialdata.aggregate() for the complete docstring.

SpatialData.contains_element(element, raise_exception=False)

Check if the SpatialElement is contained in the SpatialData object.

Parameters:

• element (Union[SpatialImage, MultiscaleSpatialImage, GeoDataFrame, DataFrame]) – The SpatialElement to check

• raise_exception (bool (default: False)) – If True, raise an exception if the element is not found. If False, return False if the element is not found.

Return type:

bool

Returns:

: True if the element is found; False otherwise (if raise_exception is False).

SpatialData.filter_by_coordinate_system(coordinate_system, filter_table=True)

Filter the SpatialData by one (or a list of) coordinate system.

This returns a SpatialData object with the elements containing a transformation mapping to the specified coordinate system(s).

Parameters:

• coordinate_system (str | list[str]) – The coordinate system(s) to filter by.

• filter_table (bool (default: True)) – If True (default), the table will be filtered to only contain regions of an element belonging to the specified coordinate system(s).

Return type:

SpatialData

Returns:

: The filtered SpatialData.

static SpatialData.from_elements_dict(elements_dict)

Create a SpatialData object from a dict of elements.

Parameters:

elements_dict (dict[str, Union[SpatialImage, MultiscaleSpatialImage, GeoDataFrame, DataFrame, AnnData]]) – Dict of elements. The keys are the names of the elements and the values are the elements. A table can be present in the dict, but only at most one; its name is not used and can be anything.

Return type:

SpatialData

Returns:

: The SpatialData object.

classmethod SpatialData.init_from_elements(elements, table=None)

Create a SpatialData object from a dict of named elements and an optional table.

Parameters:

• elements (dict[str, Union[SpatialImage, MultiscaleSpatialImage, GeoDataFrame, DataFrame]]) – A dict of named elements.

• table (Optional[AnnData] (default: None)) – An optional table.

Return type:

SpatialData

Returns:

: The SpatialData object.

SpatialData.is_backed()

Check if the data is backed by a Zarr storage or if it is in-memory.

Return type:

bool

static SpatialData.read(file_path, selection=None)

Read a SpatialData object from a Zarr storage (on-disk or remote).

Parameters:

• file_path (str) – The path or URL to the Zarr storage.

• selection (Optional[tuple[str]] (default: None)) – The elements to read (images, labels, points, shapes, table). If None, all elements are read.

Return type:

SpatialData

Returns:

: The SpatialData object.

SpatialData.transform_element_to_coordinate_system(element, target_coordinate_system)

Transform an element to a given coordinate system.

Parameters:

• element (Union[SpatialImage, MultiscaleSpatialImage, GeoDataFrame, DataFrame]) – The element to transform.

• target_coordinate_system (str) – The target coordinate system.

Return type:

Union[SpatialImage, MultiscaleSpatialImage, GeoDataFrame, DataFrame]

Returns:

: The transformed element.

SpatialData.transform_to_coordinate_system(target_coordinate_system)

Transform the SpatialData to a given coordinate system.

Parameters:

target_coordinate_system (str) – The target coordinate system.

Return type:

SpatialData

Returns:

: The transformed SpatialData.

SpatialData.write(file_path, storage_options=None, overwrite=False, consolidate_metadata=True)

Write the SpatialData object to Zarr.

Return type:

None