phenotypic.refine.NearestNeighborMerger#

class phenotypic.refine.NearestNeighborMerger(distance_threshold: float = 20.0, min_size: int | None = 50)[source]

Bases: ObjectRefiner

Merge small fragments into their nearest neighboring colony.

Each object below min_size is absorbed into its single closest neighbor within distance_threshold. Unlike transitive merging, this is one-directional and conservative — it cleans up debris without cascading merges across the plate.

Parameters:

  • distance_threshold (float) – Maximum centroid distance (pixels) for merging. Objects beyond this distance remain independent. Typical range: 15–40. Default: 25.

  • min_size (Optional[int]) – Only objects with area below this threshold are merge candidates. Larger objects serve as anchor targets. None merges all objects (rarely desired). Default: 50.

Returns:

Input image with objmask and objmap updated after merging small objects into their nearest neighbors.

Return type:

Image

Best For:

  • Absorbing dust or noise fragments near real colonies.

  • Cleaning up small detection artifacts without risking cascading merges.

  • Size-selective cleanup where only fragments below a threshold merge.

Consider Also:

See also

How To: Merge Fragmented Detections for fragment merging strategies. Refinement Strategies for choosing the right refinement approach.

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 = 20.0, min_size: int | None = 50)[source]

Initialize the merger.

Parameters:

  • distance_threshold (float) – Maximum distance to nearest neighbor for merging. Objects farther than this remain independent.

  • min_size (int | None) – Minimum area to preserve independently. Objects smaller than this merge to nearest neighbor if within distance_threshold. Larger objects remain untouched.

Raises:

ValueError – If distance_threshold is not positive or if min_size is provided and 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.

This Page