harpy.im.add_grid_labels

harpy.im.add_grid_labels#

harpy.im.add_grid_labels(sdata, shape, size, output_shapes_name, output_labels_name, grid_type='hexagon', offset=(0, 0), chunks=None, client=None, transformations=None, scale_factors=None, overwrite=False)#

Adds a grid-based labels element to the SpatialData object using either a hexagonal or square grid.

The function creates a corresponding shapes element based on the specified grid type and parameters.

Parameters:

  • sdata – The SpatialData object to which the new grid-based labels and shapes elements will be added.

  • shape (tuple[int, int]) – The (y, x) shape of the resulting labels element. This defines the grid’s size in terms of height (y) and width (x).

  • size (int) – The size of the grid cells. For a hexagonal grid, this is the radius of the hexagons; for a square grid, this is the side length of the squares.

  • output_shapes_name (str) – The name of the shapes element that corresponds to the generated grid. This element will contain the polygons representing the grid.

  • output_labels_name (str) – The name of the labels element that corresponds to the generated grid. This element will contain the labels generated from the shapes.

  • grid_type (Literal['hexagon', 'square'] (default: 'hexagon')) – The type of grid to create. Can be either "hexagon" for a hexagonal grid or "square" for a square grid. The default is "hexagon".

  • offset (tuple[int, int] (default: (0, 0))) – An optional translation offset applied to the grid. This is a tuple (y_offset, x_offset) that can shift the grid. Default is (0, 0), but it is recommended to use a zero offset, and specify the offset via passing a spatialdata.transformations.Translation to transformations.

  • chunks (int | None (default: None)) – Specifies the chunk size for Dask arrays when calculating the labels element.

  • client (Client | None (default: None)) – A Dask Client instance, which will be passed to ‘harpy.im.rasterize’ (function which rasterizes the generated output_shapes_name) if specified. Refer to the ‘harpy.im.rasterize’ docstring for further details.

  • transformations (dict[str, BaseTransformation] | None (default: None)) – Transformations that will be added to the resulting output_shapes_name and output_labels_name.

  • scale_factors (Sequence[dict[str, int] | int] | None (default: None)) – Scale factors to apply for multiscale. Only applies to output_labels_name.

  • overwrite (bool (default: False)) – If True, overwrites the output_shapes_name and output_labels_name if it already exists in sdata.

Return type:

SpatialData

Returns:

: The updated SpatialData object with the newly added grid-based shapes and labels elements.

Raises:

ValueError – If an unsupported grid type is specified. The valid options are "hexagon" or "square".

Notes

The function first generates a grid of shapes (either hexagons or squares) based on the specified grid type and parameters. These shapes are added as a new shapes element in sdata. Then, a corresponding labels element is generated from the shapes element. The labels element has the same spatial dimensions as specified in shape.