phenotypic.refine.SmallToLargeMerger

class phenotypic.refine.SmallToLargeMerger(distance_threshold: float = 30.0, size_threshold: int = 100)

Bases: ObjectRefiner

Merge small colony fragments into their nearest large colony using hierarchical size-based merging.

Partitions objects into small (below size threshold) and large (at or above), then absorbs each small fragment into the nearest large neighbor within the distance threshold. Large colonies serve as stable anchors and never merge with each other, preventing false consolidation of distinct colonies.

Parameters:

• distance_threshold (float) – Maximum centroid-to-centroid distance in pixels for merging a small fragment into a large colony. Typical range: 10–50. Should be smaller than the minimum distance between distinct large colonies. Default: 30.0.

• size_threshold (int) – Pixel area separating small fragments from large anchor colonies. Objects below this are merge candidates; objects at or above are preserved as anchors. Typical range: 50–200. Default: 100.

Returns:

Input image with objmap updated so that small fragments are relabeled to their nearest large colony.

Return type:

Image

Raises:

ValueError – If distance_threshold or size_threshold is not positive.

Best For:

• Fragmented detections from heterogeneous pigmentation or uneven illumination where satellites cluster around a main colony.

• Post-watershed over-segmentation where one colony splits into a large core plus small peripheral regions.

• Removing small debris near real colonies without merging distinct large colonies.

• Plates with severe lighting gradients that produce satellite fragments around main detections.

Consider Also:

• TransitiveDistanceMerger when all nearby objects should merge regardless of size, including large-to-large merging.

• NearestNeighborMerger for simple nearest-neighbor merging without size partitioning.

• SmallObjectRemover when small fragments should be discarded entirely rather than absorbed.

See also

How To: Merge Fragmented Detections for fragment merging workflows. Refinement Strategies for a comparison of merging strategies.

Methods

__init__	Initialize the merger.
apply	Applies the operation to an image, either in-place or on a copy.
widget	Return (and optionally display) the root widget.

__init__(distance_threshold: float = 30.0, size_threshold: int = 100)

Initialize the merger.

Parameters:

• distance_threshold (float) – Maximum distance from small fragment to large colony for merging (pixels).

• size_threshold (int) – Minimum area for an object to be considered a “large” anchor colony. Smaller objects are candidates for merging.

Raises:

ValueError – If distance_threshold or size_threshold are not positive.

__del__()

Automatically stop tracemalloc when the object is deleted.

__getstate__()

Prepare the object for pickling by disposing of any widgets.

This ensures that UI components (which may contain unpickleable objects like input functions or thread locks) are cleaned up before serialization.

Note

This method modifies the object state by calling dispose_widgets(). Any active widgets will be detached from the object.

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.