harpy.im.merge_labels

Contents

harpy.im.merge_labels#

harpy.im.merge_labels(sdata, candidate_labels_name, priority_labels_name, threshold=0.5, chunks=None, output_labels_name=None, output_shapes_name=None, scale_factors=None, overwrite=False)#

Merge two labels elements using a global object-level overlap rule.

This function treats priority_labels_name as the authoritative segmentation and candidate_labels_name as a labels element that can fill uncovered regions. For each non-zero candidate object, overlaps with all non-zero priority objects are accumulated globally across the full image. A candidate object is kept if:

candidate_fraction = overlap_with_any_priority / area_candidate <= threshold

Candidate objects with no overlap with the priority segmentation therefore have candidate_fraction = 0 and are kept. Accepted candidate objects are written only at pixels where the priority segmentation is 0.

Accepted candidate labels are relabeled above the existing priority labels to avoid label-id collisions in the merged result.

Parameters:

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

  • candidate_labels_name (str) – The name of the labels element containing candidate objects to add to the merged result when they satisfy the overlap rule.

  • priority_labels_name (str) – The name of the labels element that takes precedence in the merged result.

  • threshold (float (default: 0.5)) – Maximum allowed candidate_fraction for keeping a candidate object. Must lie between 0 and 1. A value of 0 keeps only candidates with no overlap with the priority segmentation. A value of 1 keeps all candidate objects.

  • chunks (str | int | tuple[int, int] | None (default: None)) – Chunk specification used when rechunking the label arrays before overlap accumulation and rendering. If a tuple is provided, it is interpreted as the desired (y, x) chunk size. If set to "auto", Dask determines the chunking.

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

  • output_shapes_name (str | None (default: None)) – The name of the output shapes element where results will be stored if shape data is produced from the merge operation.

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

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

Return type:

SpatialData

Returns:

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

Raises:

  • ValueError – If the provided labels elements do not have the same shape or transformations.

  • ValueError – If threshold is outside the interval [0, 1].

  • ValueError – If candidate label ids can not be relabeled safely into _SEG_DTYPE without colliding with priority label ids.

See also

harpy.im.match_labels_to_reference

map labels from a merged or processed labels element back to labels in one or more reference elements.

Example

sdata = hp.datasets.mibi_example()

sdata = hp.im.merge_labels(
    sdata,
    candidate_labels_name="masks_whole",
    priority_labels_name="masks_nuclear",
    threshold=0.5,
    chunks=256,
    output_labels_name="masks_merged",
    output_shapes_name="masks_merged_boundaries",
    overwrite=True,
)
Contents