harpy.im.align_labels

Contents

harpy.im.align_labels#

harpy.im.align_labels(sdata, labels_name_1, labels_name_2, threshold=0.0, depth=100, chunks=None, output_labels_name=None, output_shapes_name=None, scale_factors=None, overwrite=False, iou_depth=2, iou_threshold=0.7)#

Align two labels elements.

This function aligns two labels elements by examining the labels in labels_name_1 and identifying their maximum overlap with labels in labels_name_2. It then updates the labels in labels_name_1, reassigning them to match the corresponding overlapping label values from labels_name_2. If there is no overlap with a label from labels_name_1 with labels_name_2, the label in labels_name_1 is set to zero. The function can also generate a shapes element based on the resulting output_labels_name. The elements are identified by their names and must exist within the passed SpatialData object.

Parameters:

  • sdata (SpatialData) – The SpatialData object containing the labels elements to be aligned.

  • labels_name_1 (str) – The name of the first labels element to align.

  • labels_name_2 (str) – The name of the second labels element to align.

  • threshold (float (default: 0.0)) – Minimum required overlap between a label in labels_name_1 and any label in labels_name_2. If the overlap fraction is less than this threshold, the label is set to 0 in output_labels_name.

  • depth (tuple[int, int] | int (default: 100)) – 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 size to avoid chunking effects.

  • chunks (str | int | tuple[int, int] | None (default: None)) – The desired chunk size for the Dask computation in ‘y’ and ‘x’, or “auto” to allow the function to choose an optimal chunk size based on the data.

  • output_labels_name (str | None (default: None)) – The name for the new labels element generated after alignment. If None and overwrite is False, a ValueError is raised. If None and overwrite is True, labels_name_1 will be overwritten with the aligned element. Default is None.

  • output_shapes_name (str | None (default: None)) – The name for the new shapes element generated from the aligned labels element. If None, no shapes element is created. Default is None.

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

  • overwrite (bool (default: False)) – If True, allows the function to overwrite the data in output_labels_name and output_shapes_name with the aligned data.

  • iou_depth (tuple[int, int] | int (default: 2)) – iou depth used for linking labels.

  • iou_threshold (float (default: 0.7)) – iou threshold used for linking labels.

Return type:

SpatialData

Returns:

: The modified SpatialData object with the aligned labels element.

Raises:

AssertionError – If the shapes of the label arrays or their translations do not match.

Notes

  • The function works with Dask arrays and can handle large datasets that don’t fit into memory.

  • Only arrays with the same shape are supported for alignment. Misaligned arrays could be due to various reasons, including errors in previous processing steps or physical shifts in the samples.

  • The alignment respects the original labelling but ensures that corresponding areas in both labels elements match after the process.

Examples

>>> sdata = align_labels(sdata, "labels_a", "labels_b", depth=(50, 50), overwrite=True)
Contents