sparrow.im.apply_labels_layers

sparrow.im.apply_labels_layers#

sparrow.im.apply_labels_layers(sdata, func, labels_layers, output_labels_layer=None, output_shapes_layer=None, depth=100, chunks='auto', 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 layer in a SpatialData object.

Parameters:

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

  • func (Callable[..., ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]] | Array]) – The Callable to apply to the labels layer.

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

  • output_labels_layer (Optional[str] (default: None)) – The name of the output labels layer where results will be stored. This must be specified.

  • output_shapes_layer (Optional[str] (default: None)) – The name of the output shapes layer 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: 'auto')) – 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 (Optional[Sequence[Union[dict[str, int], int]]] (default: None)) – Scale factors to apply for multiscale.

  • overwrite (bool (default: False)) – If True, overwrites the output layer 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 layer added to the specified output_labels_layer. If output_shapes_layer is provided, a shapes layer will be created corresponding to this labels layer.

Raises:

  • ValueError – If output_labels_layer 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 label layer in labels_layer 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 layers 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