harpy.im.map_labels

Contents

harpy.im.map_labels#

harpy.im.map_labels(sdata, func, labels_name, output_labels_name=None, output_shapes_name=None, depth=100, chunks=None, scale_factors=None, overwrite=False, relabel_chunks=True, trim=False, iou_depth=2, iou_threshold=0.7, **kwargs)#

Apply a specified function to a labels element in a SpatialData object.

Parameters:

  • sdata (SpatialData) – Spatial data object containing the labels element to be processed.

  • func (Callable[..., ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]] | Array]) – The Callable to apply to the labels element.

  • labels_name (list[str] | str) – The labels element(s) in sdata to process.

  • output_labels_name (str | None (default: None)) – The name of the output labels element where results will be stored. This must be specified.

  • output_shapes_name (str | None (default: None)) – The name of the output shapes element where results will be stored.

  • depth (tuple[int, int] | int (default: 100)) – The overlapping depth used in dask.array.map_overlap. If specified as a tuple or dict, it contains the depth used in ‘y’ and ‘x’ dimension. The depth around the boundary of each block to load when the array is split into blocks (for alignment). This ensures that the split isn’t causing misalignment along the edges. Default is 100. Please set depth>cell diameter to avoid chunking effects.

  • chunks (str | int | tuple[int, int] | None (default: None)) – Specification for rechunking the data before applying the function. If chunks is a Tuple, they should contain desired chunk size for ‘y’, ‘x’.

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

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

  • relabel_chunks (bool (default: True)) – Whether to relabel the labels of each chunk after being processed by func. If set to True, a bit shift will be applied, ensuring no collisions.

  • trim (bool (default: False)) – Whether to trim overlap added by map_overlap, or postprocess the chunks to avoid chunking effects. Set to true if you do not expect chunking effects from func, e.g. func is a filter on size or shape of individual labels, and is designed carefully to prevent chunking effects.

  • iou_depth (tuple[int, int] | int (default: 2)) – iou depth used for linking labels. Ignored if trim is set to True.

  • iou_threshold (float (default: 0.7)) – iou threshold used for linking labels. Ignored if trim is set to True.

  • **kwargs (Any) – Keyword arguments to be passed to func.

Return type:

SpatialData

Returns:

: The sdata object with the processed labels element added to the specified output_labels_name. If output_shapes_name is provided, a shapes element will be created corresponding to this labels element.

Raises:

  • ValueError – If output_labels_name is not provided.

  • ValueError – If chunks is a Tuple, and does not match (y,x).

  • ValueError – If depth is a Tuple, and does not match (y,x).

  • ValueError – If iou_depth is a Tuple, and does not match (y,x).

  • ValueError – If a labels element in labels_name can not be found.

  • ValueError – If number of blocks in z-dimension is not equal to 1.

Notes

This function is designed for processing labels elements stored in a SpatialData object using dask for potential parallelism and out-of-core computation. It takes care of relabeling across chunks, to avoid collisions.

Contents