spatialdata.SpatialData

spatialdata.SpatialData#

class spatialdata.SpatialData(images=None, labels=None, points=None, shapes=None, tables=None)#

The SpatialData object.

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

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

Parameters:

images (Optional[dict[str, Union[SpatialImage, MultiscaleSpatialImage]]] (default: None)) – Dict of 2D and 3D image elements. The following parsers are available: Image2DModel, Image3DModel.
labels (Optional[dict[str, Union[SpatialImage, MultiscaleSpatialImage]]] (default: None)) – 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 (Optional[dict[str, DataFrame]] (default: None)) – Dict of points elements. Points can contain annotations. The following parsers is available: PointsModel.
shapes (Optional[dict[str, GeoDataFrame]] (default: None)) – 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 – 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.

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`	Path to the Zarr storage.
`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 table with name table from tables if it exists.
`tables`	Return tables dictionary.

Methods table#

`add_image`(name, image[, storage_options, ...])	rtype: `None`
`add_labels`(name, labels[, storage_options, ...])	rtype: `None`
`add_points`(name, points[, overwrite])	rtype: `None`
`add_shapes`(name, shapes[, overwrite])	rtype: `None`
`aggregate`([values_sdata, values, by_sdata, ...])	Aggregate values by given region.
`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.
`gen_elements`()	Generate elements within the SpatialData object.
`gen_spatial_elements`()	Generate spatial elements within the SpatialData object.
`get`(key[, default_value])	Get element from SpatialData object based on corresponding name.
`get_annotated_regions`(table)	Get the regions annotated by a table.
`get_instance_key_column`(table)	Return the instance key column in table.obs containing for each row the instance id of that row.
`get_region_key_column`(table)	Get the column of table.obs containing per row the region annotated by that row.
`init_from_elements`(cls, elements[, tables])	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.
`locate_element`(element)	Locate a SpatialElement within the SpatialData object and returns its Zarr paths relative to the root.
`read`(file_path[, selection])	Read a SpatialData object from a Zarr storage (on-disk or remote).
`rename_coordinate_systems`(rename_dict)	Rename coordinate systems.
`set_table_annotates_spatialelement`(...[, ...])	Set the SpatialElement annotation target of a given AnnData table.
`subset`(element_names[, filter_tables, ...])	Subset the SpatialData object.
`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.
`update_annotated_regions_metadata`(table[, ...])	Update the annotation target of the table using the region_key column in table.obs.
`validate_table_in_spatialdata`(table)	Validate the presence of the annotation target of a SpatialData table in the SpatialData object.
`write`(file_path[, storage_options, ...])	rtype: `None`

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#: Path to the Zarr storage.

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 table with name table from tables if it exists.

Returns:: The table.

SpatialData.tables#

Return tables dictionary.

Returns:: dict[str, AnnData] Either the empty dictionary or a dictionary with as values the strings representing the table names and as values the AnnData tables themselves.

Methods#

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

Return type:: None

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

Return type:: None

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

Return type:: None

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

Return type:: None

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, table_name='table', **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.filter_by_coordinate_system(coordinate_system, filter_tables=True, include_orphan_tables=False)#

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_tables (bool (default: True)) – If True (default), the tables will be filtered to only contain regions of an element belonging to the specified coordinate system(s).
include_orphan_tables (bool (default: False)) – If True (not default), include tables that do not annotate SpatialElement(s). Only has an effect if filter_tables is also set to True.

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.

SpatialData.gen_elements()#

Generate elements within the SpatialData object.

This method generates elements in the SpatialData object (images, labels, points, shapes and tables)

Return type:

Generator[tuple[str, str, Union[SpatialImage, MultiscaleSpatialImage, GeoDataFrame, DataFrame, AnnData]], None, None]

Returns:

: A generator that yields tuples containing the name, description, and element objects themselves.

SpatialData.gen_spatial_elements()#

Generate spatial elements within the SpatialData object.

This method generates spatial elements (images, labels, points and shapes).

Return type:

Generator[tuple[str, str, Union[SpatialImage, MultiscaleSpatialImage, GeoDataFrame, DataFrame]], None, None]

Returns:

: A generator that yields tuples containing the element_type (string), name, and SpatialElement objects themselves.

SpatialData.get(key, default_value=None)#

Get element from SpatialData object based on corresponding name.

Parameters:

key (str) – The key to lookup in the spatial elements.
default_value (Union[SpatialImage, MultiscaleSpatialImage, GeoDataFrame, DataFrame, AnnData, None] (default: None)) – The default value (a SpatialElement or a table) to return if the key is not found. Default is None.

Return type:

Union[SpatialImage, MultiscaleSpatialImage, GeoDataFrame, DataFrame, AnnData]

Returns:

: The SpatialData element associated with the given key, if found. Otherwise, the default value is returned.

static SpatialData.get_annotated_regions(table)#

Get the regions annotated by a table.

Parameters:

table (AnnData) – The AnnData table for which to retrieve annotated regions.

Return type:

str | list[str]

Returns:

: The annotated regions.

static SpatialData.get_instance_key_column(table)#

Return the instance key column in table.obs containing for each row the instance id of that row.

Parameters:

table (AnnData) – The AnnData table.

Return type:

Series

Returns:

: The instance key column.

Raises:

KeyError – If the instance key column is not found in table.obs.

static SpatialData.get_region_key_column(table)#

Get the column of table.obs containing per row the region annotated by that row.

Parameters:

table (AnnData) – The AnnData table.

Return type:

Series

Returns:

: The region key column.

Raises:

KeyError – If the region key column is not found in table.obs.

classmethod SpatialData.init_from_elements(cls, elements, tables=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.
tables (Union[AnnData, dict[str, AnnData], None] (default: None)) – An optional table or dictionary of tables

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

SpatialData.locate_element(element)#

Locate a SpatialElement within the SpatialData object and returns its Zarr paths relative to the root.

Parameters:

element (Union[SpatialImage, MultiscaleSpatialImage, GeoDataFrame, DataFrame]) – The queried SpatialElement

Return type:

list[str]

Returns:

: A list of Zarr paths of the element relative to the root (multiple copies of the same element are allowed). The list is empty if the element is not present.

static SpatialData.read(file_path, selection=None)#

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

Parameters:

file_path (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.rename_coordinate_systems(rename_dict)#

Rename coordinate systems.

Parameters:: rename_dict (dict[str, str]) – A dictionary mapping old coordinate system names to new coordinate system names.
Return type:: None

Notes

The method does not allow to rename a coordinate system into an existing one, unless the existing one is also renamed in the same call.

SpatialData.set_table_annotates_spatialelement(table_name, region, region_key=None, instance_key=None)#

Set the SpatialElement annotation target of a given AnnData table.

Parameters:

table_name (str) – The name of the table to set the annotation target for.
region (str | Series) – The name of the target element for the annotation. This can either be a string or a pandas Series object.
region_key (Optional[str] (default: None)) – The region key for the annotation. If not specified, defaults to None which means the currently set region key is reused.
instance_key (Optional[str] (default: None)) – The instance key for the annotation. If not specified, defaults to None which means the currently set instance key is reused.

Raises:

ValueError – If the annotation SpatialElement target is not present in the SpatialData object.
TypeError – If no current annotation metadata is found and both region_key and instance_key are not specified.

Return type:

None

SpatialData.subset(element_names, filter_tables=True, include_orphan_tables=False)#

Subset the SpatialData object.

Parameters:

element_names (list[str]) – The names of the element_names to subset. If the element_name is the name of a table, this table would be completely included in the subset even if filter_table is True.
filter_table – If True (default), the table is filtered to only contain rows that are annotating regions contained within the element_names.
include_orphan_tables (bool (default: False)) – If True (not default), include tables that do not annotate SpatialElement(s). Only has an effect if filter_tables is also set to True.

Return type:

SpatialData

Returns:

: The subsetted SpatialData object.

SpatialData.transform_element_to_coordinate_system(element, target_coordinate_system, maintain_positioning=False)#

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.
maintain_positioning (bool (default: False)) – Default False (most common use case). If True, the data will be transformed but a transformation will be added so that the positioning of the data in the target coordinate system will not change. If you want to align datasets to a common coordinate system you should use the default value.

Return type:

Union[SpatialImage, MultiscaleSpatialImage, GeoDataFrame, DataFrame]

Returns:

: The transformed element.

SpatialData.transform_to_coordinate_system(target_coordinate_system, maintain_positioning=False)#

Transform the SpatialData to a given coordinate system.

Parameters:

target_coordinate_system (str) – The target coordinate system.
maintain_positioning (bool (default: False)) – Default False (most common use case). If True, the data will be transformed but a transformation will be added so that the positioning of the data in the target coordinate system will not change. If you want to align datasets to a common coordinate system you should use the default value.

Return type:

SpatialData

Returns:

: The transformed SpatialData.

static SpatialData.update_annotated_regions_metadata(table, region_key=None)#

Update the annotation target of the table using the region_key column in table.obs.

The table must already contain annotation metadata, e.g. the region, region_key and instance_key must already be specified for the table. If this is not the case please use TableModel.parse instead and specify the annotation metadata by passing the correct arguments to that function.

Parameters:

table (AnnData) – The AnnData table for which to set the annotation target.
region_key (Optional[str] (default: None)) – The column in table.obs containing the rows specifying the SpatialElements being annotated. If None the current value for region_key in the annotation metadata of the table is used. If specified but different from the current region_key, the current region_key is overwritten.

Return type:

AnnData

Returns:

: The table for which the annotation target has been set.

SpatialData.validate_table_in_spatialdata(table)#

Validate the presence of the annotation target of a SpatialData table in the SpatialData object.

This method validates a table in the SpatialData object to ensure that if annotation metadata is present, the annotation target (SpatialElement) is present in the SpatialData object, the dtypes of the instance key column in the table and the annotation target do not match. Otherwise, a warning is raised.

Parameters:

table (AnnData) – The table potentially annotating a SpatialElement

Raises:

UserWarning – If the table is annotating elements not present in the SpatialData object.
UserWarning – The dtypes of the instance key column in the table and the annotation target do not match.

Return type:

None

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

Return type:: None

spatialdata.SpatialData

Contents

spatialdata.SpatialData#

Attributes table#

Methods table#

Attributes#

Methods#