spatialdata.rasterize

Contents

spatialdata.rasterize#

spatialdata.rasterize(data, axes, min_coordinate, max_coordinate, target_coordinate_system, target_unit_to_pixels=None, target_width=None, target_height=None, target_depth=None, sdata=None, value_key=None, table_name=None, return_regions_as_labels=False, agg_func=None, return_single_channel=None)#

Rasterize a SpatialData object or a SpatialElement (image, labels, points, shapes).

Parameters:
  • data (Union[SpatialData, DataArray, DataTree, GeoDataFrame, DataFrame, str]) – The SpatialData object or SpatialElement to rasterize. In alternative, the name of the SpatialElement in the SpatialData object, when the SpatialData object is passed to values_sdata.

  • axes (tuple[str, ...]) – The axes that min_coordinate and max_coordinate refer to.

  • min_coordinate (list[Union[int, float]] | ndarray[Any, dtype[float64]]) – The minimum coordinates of the bounding box.

  • max_coordinate (list[Union[int, float]] | ndarray[Any, dtype[float64]]) – The maximum coordinates of the bounding box.

  • target_coordinate_system (str) – The coordinate system in which we define the bounding box. This will also be the coordinate system of the produced rasterized image.

  • target_unit_to_pixels (Optional[float] (default: None)) – The number of pixels per unit that the target image should have. It is mandatory to specify precisely one of the following options: target_unit_to_pixels, target_width, target_height, target_depth.

  • target_width (Optional[float] (default: None)) – The width of the target image in units. It is mandatory to specify precisely one of the following options: target_unit_to_pixels, target_width, target_height, target_depth.

  • target_height (Optional[float] (default: None)) – The height of the target image in units. It is mandatory to specify precisely one of the following options: target_unit_to_pixels, target_width, target_height, target_depth.

  • target_depth (Optional[float] (default: None)) – The depth of the target image in units. It is mandatory to specify precisely one of the following options: target_unit_to_pixels, target_width, target_height, target_depth.

  • sdata (Optional[SpatialData] (default: None)) – SpatialData object containing the values to aggregate if value_key refers to values from a table. Must be None when data is a SpatialData object.

  • value_key (Optional[str] (default: None)) –

    Name of the column containing the values to aggregate; can refer both to numerical or categorical values.

    The key can be:

    • the name of a column(s) in the dataframe (Dask DataFrame for points or GeoDataFrame for shapes);

    • the name of obs column(s) in the associated AnnData table (for points, shapes, and labels);

    • the name of a var(s), referring to the column(s) of the X matrix in the table (for points, shapes, and labels).

    See the notes for more details on the default behavior. Must be None when data is a SpatialData object.

  • table_name (Optional[str] (default: None)) – The table optionally containing the value_key and the name of the table in the returned SpatialData object. Must be None when data is a SpatialData object, otherwise it assumes the default value of 'table'.

  • return_regions_as_labels (bool (default: False)) – By default, single-scale images of shape (c, y, x) are returned. If True, returns labels and shapes as labels of shape (y, x) as opposed to an image of shape (c, y, x). Points and images are always returned as images, and multiscale raster data is always returned as single-scale data.

  • agg_func (Union[str, Reduction, None] (default: None)) – Available only when rasterizing points and shapes. A reduction function from datashader (its name, or a Callable). See the notes for more details on the default behavior. Must be None when data is a SpatialData object.

  • return_single_channel (Optional[bool] (default: None)) – Only used when rasterizing points and shapes and when value_key refers to a categorical column. If False, each category will be rasterized in a separate channel.

Return type:

SpatialData | DataArray

Returns:

: The rasterized SpatialData object or SpatialData supported DataArray. Each SpatialElement will be rasterized into a DataArray (not a DataTree). So if a SpatialData object with elements is passed, a SpatialData object with single-scale images and labels will be returned.

Notes

For images and labels, the parameters value_key, table_name, agg_func, and return_single_channel are not used.

Instead, when rasterizing shapes and points, the following table clarifies the default datashader reduction used for various combinations of parameters.

In particular, the first two rows refer to the default behavior when the parameters (value_key, ‘table_name’, returned_single_channel, agg_func) are kept to their default values.

value_key

Shapes or Points

return_single_chan

datashader reduct.

table_name

None*

Point (default)

NA

count

‘table’

None**

Shapes (default)

True

first

‘table’

None**

Shapes

False

count_cat

‘table’

category

NA

True

first

‘table’

category

NA

False

count_cat

‘table’

int/float

NA

NA

sum

‘table’

Explicitly, the default behaviors are as follows.

  • for points, each pixel counts the number of points belonging to it, (the count function is applied to an artificial column of ones);

  • for shapes, each pixel gets a single index among the ones of the shapes that intersect it (the index of the shapes is interpreted as a categorical column and then the first function is used).