sparrow.im.align_labels_layers

sparrow.im.align_labels_layers#

sparrow.im.align_labels_layers(sdata, labels_layer_1, labels_layer_2, depth=100, chunks='auto', output_labels_layer=None, output_shapes_layer=None, scale_factors=None, overwrite=False, iou_depth=2, iou_threshold=0.7)#

Align two labels layers.

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

Parameters:

  • sdata (SpatialData) – The spatial data object containing the labels layers to be aligned.

  • labels_layer_1 (str) – The name of the first labels layer to align.

  • labels_layer_2 (str) – The name of the second labels layer to align.

  • 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: 'auto')) – 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. Default is “auto”.

  • output_labels_layer (Optional[str] (default: None)) – The name for the new labels layer generated after alignment. If None and overwrite is False, a ValueError is raised. If None and overwrite is True, ‘labels_layer_1’ will be overwritten with the aligned layer. Default is None.

  • output_shapes_layer (Optional[str] (default: None)) – The name for the new shapes layer generated from the aligned labels layer. If None, no shapes layer is created. Default is None.

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

  • overwrite (bool (default: False)) – If True, allows the function to overwrite the data in output_labels_layer and output_shapes_layer 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 spatial data object with the aligned labels layer.

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 layers match after the process.

Examples

>>> sdata = align_labels_layers(sdata, 'layer_1', 'layer_2', depth=(50, 50), overwrite=True)
Contents