Models utils

spatialdata.models.get_model(e, validate=True)

Get the model for the given element. Validate using the model if validate is True.

Parameters:

• e (DataArray | DataTree | GeoDataFrame | DataFrame) – The element.

• validate (bool (default: True)) – Whether to validate the element using the model.

Return type:

type[Image2DModel] | type[Image3DModel] | type[Labels2DModel] | type[Labels3DModel] | type[PointsModel] | type[ShapesModel] | type[TableModel]

Returns:

: The SpatialData model.

spatialdata.models.validate_element(e)

Validate a spatial element against its model schema.

Parameters:

e (DataArray | DataTree | GeoDataFrame | DataFrame) – The spatial element to validate.

Raises:

ValueError – If the element is invalid (e.g. missing or empty transformations, wrong dtypes).

Return type:

None

spatialdata.models.SpatialElement = xarray.core.dataarray.DataArray | xarray.core.datatree.DataTree | geopandas.geodataframe.GeoDataFrame | dask.dataframe.dask_expr._collection.DataFrame

Represent a PEP 604 union type

E.g. for int | str

spatialdata.models.get_axes_names(e)

spatialdata.models.get_axes_names(e)

spatialdata.models.get_axes_names(e)

spatialdata.models.get_axes_names(e)

spatialdata.models.get_axes_names(e)

Get the dimensions of a SpatialElement.

Parameters:

e (DataArray | DataTree | GeoDataFrame | DataFrame) – SpatialElement

Return type:

tuple[str, ...]

Returns:

: Dimensions of the SpatialElement (e.g. (“z”, “y”, “x”))

spatialdata.models.get_spatial_axes(axes)

Get the spatial axes of interest.

Parameters:

axes (tuple[str, ...]) – Should be a subset of [‘x’, ‘y’, ‘z’, ‘c’]

Return type:

tuple[str, ...]

Returns:

: The spatial axes, i.e. the input axes but without ‘c’

spatialdata.models.points_geopandas_to_dask_dataframe(gdf, suppress_z_warning=False)

Convert a GeoDataFrame which represents 2D or 3D points to a Dask DataFrame that passes the schema validation.

Parameters:

gdf (GeoDataFrame) – GeoDataFrame with a geometry column that contains 2D or 3D points.

Return type:

DataFrame

Returns:

: The Dask DataFrame converted from the GeoDataFrame. The Dask DataFrame passes the schema validation.

Notes

The returned Dask DataFrame gets the ‘x’ and ‘y’ columns from the geometry column, and eventually the ‘z’ column (and the rest of the columns), from the remaining columns of the GeoDataFrame.

spatialdata.models.points_dask_dataframe_to_geopandas(points, suppress_z_warning=False)

Convert a Dask DataFrame to a GeoDataFrame.

Parameters:

points (DataFrame) – Dask DataFrame with columns “x” and “y”. Eventually, it can contain a column “z” that will be not included in the geometry column.

Return type:

GeoDataFrame

Returns:

: The GeoDataFrame with the geometry column constructed from the “x” and “y” columns and, if present, the rest of the columns.

Notes

The “z” column is not included in the geometry column because it is not supported by GeoPandas. The resulting GeoDataFrame does not currenlty passes the validation of the SpatialData models. In fact currently points need to be saved as a Dask DataFrame. We will be restructuring the models to allow for GeoDataFrames soon.

spatialdata.models.get_channel_names(data)

spatialdata.models.get_channel_names(data)

spatialdata.models.get_channel_names(data)

Get channels from data for an image element (both single and multiscale).

Parameters:

data (Any) – data to get channels from

Return type:

list[Any]

Returns:

: List of channels

Notes

For multiscale images, the channels are validated to be consistent across scales.

spatialdata.models.set_channel_names(element, channel_names)

Set the channel names for a image SpatialElement in the SpatialData object.

Parameters:

• element (DataArray | DataTree) – The image SpatialElement or parsed ImageModel.

• channel_names (str | list[str]) – The channel names to be assigned to the c dimension of the image SpatialElement.

Return type:

DataArray | DataTree

Returns:

: The image SpatialElement or parsed ImageModel with the channel names set to the c dimension.

spatialdata.models.force_2d(gdf)

Force the geometries of a shapes object GeoDataFrame to be 2D by modifying the geometries in place.

Geopandas introduced a method called force_2d() to drop the z dimension. Unfortunately, this feature, as of geopandas == 0.14.3, is still not released. Similarly, the recently released shapely >= 2.0.3 implemented force_2d(), but currently there are installation errors.

A similar function has been developed in When .force_2d()

Parameters:

gdf (GeoDataFrame) – GeoDataFrame with 2D or 3D geometries

Return type:

None