phenotypic.detect.RoundPeaksDetector#

class phenotypic.detect.RoundPeaksDetector(thresh_method: Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata'] = 'otsu', subtract_background: bool = True, remove_noise: bool = True, footprint_radius: int = 3, smoothing_sigma: float = 2.0, min_peak_distance: int | None = None, peak_prominence: float | None = None, edge_refinement: bool = True)[source]#

Bases: ObjectDetector

Class for detecting circular colonies in gridded plate images using the gitter algorithm.

The RoundPeaksDetector implements an improved Python version of the gitter colony detection algorithm originally developed for R. This method is specifically designed for quantifying pinned microbial cultures arranged in a regular grid pattern on agar plates. The algorithm works by:

  1. Thresholding the image to create a binary mask of colonies

  2. Analyzing row and column intensity profiles to detect periodic peaks

  3. Estimating grid edges based on peak positions

  4. Assigning pixels to grid cells and identifying dominant colonies

This approach is robust to irregular colonies, noise, variable illumination, and other common plate imaging artifacts.

Note

For best results, use preprocessing such as GaussianBlur or other enhancement techniques before detection. The detector works best with images where colonies are clearly visible against the background.

This detector works best for yeast-like growth where the colonies are circular and less likely to work on filamentous fungi.

Warning

Grid inference from the binary mask alone (when not using GridImage) may be less accurate than providing explicit grid information. For optimal results, use with GridImage when grid parameters are known.

Parameters:

  • thresh_method (Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata'])

  • subtract_background (bool)

  • remove_noise (bool)

  • footprint_radius (int)

  • smoothing_sigma (float)

  • min_peak_distance (int | None)

  • peak_prominence (float | None)

  • edge_refinement (bool)

thresh_method#

Thresholding method to use for binary mask creation. Options: ‘otsu’, ‘mean’, ‘local’, ‘triangle’, ‘minimum’, ‘isodata’. Default is ‘otsu’.

Type:

str

subtract_background#

Whether to apply white tophat background subtraction before thresholding. Helps with uneven illumination.

Type:

bool

remove_noise#

Whether to apply binary opening to remove small noise artifacts after thresholding.

Type:

bool

footprint_radius#

Radius for morphological operations (noise removal and background subtraction kernels).

Type:

int

smoothing_sigma#

Standard deviation for Gaussian smoothing of row/column sums before peak detection. Higher values increase robustness to noise but may merge nearby peaks. Set to 0 to disable.

Type:

float

min_peak_distance#

Minimum distance between peaks in pixels. If None, automatically estimated from grid dimensions. Prevents detection of spurious peaks too close together.

Type:

int | None

peak_prominence#

Minimum prominence of peaks for detection. If None, automatically estimated from signal statistics. Higher values are more selective.

Type:

float | None

edge_refinement#

Whether to refine grid edges using local intensity profiles. Improves accuracy but adds computational cost.

Type:

bool

References

Wagih, O. and Parts, L. (2014). gitter: a robust and accurate method for quantification of colony sizes from plate images. G3 (Bethesda), 4(3), 547-552. https://omarwagih.github.io/gitter/

Methods

__init__

Initialize the RoundPeaksDetector with specified parameters.

apply

Binarizes the given image gray using the Yen threshold method.

dispose_widgets

Drop references to the UI widgets.

sync_widgets_from_state

Push internal state into widgets.

widget

Return (and optionally display) the root widget.
__init__(thresh_method: Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata'] = 'otsu', subtract_background: bool = True, remove_noise: bool = True, footprint_radius: int = 3, smoothing_sigma: float = 2.0, min_peak_distance: int | None = None, peak_prominence: float | None = None, edge_refinement: bool = True)[source]#

Initialize the RoundPeaksDetector with specified parameters.

Parameters:

  • thresh_method (Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata']) – Method for thresholding the image. Options are: ‘otsu’ (default), ‘mean’, ‘local’, ‘triangle’, ‘minimum’, ‘isodata’.

  • subtract_background (bool) – If True, apply white tophat transform to remove background variations before thresholding.

  • remove_noise (bool) – If True, apply morphological opening to remove small noise artifacts from the binary mask.

  • footprint_radius (int) – Radius in pixels for morphological operations. Larger values remove larger noise but may erode colony edges.

  • smoothing_sigma (float) – Standard deviation for Gaussian smoothing of intensity profiles before peak detection. Set to 0 to disable smoothing.

  • min_peak_distance (int | None) – Minimum allowed distance between detected peaks. If None, automatically estimated from grid dimensions.

  • peak_prominence (float | None) – Minimum prominence required for peak detection. If None, automatically calculated as 0.1 * signal range.

  • edge_refinement (bool) – If True, refine grid edges using weighted intensity profiles for improved accuracy.

__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)#

Binarizes the given image gray using the Yen threshold method.

This function modifies the arr image by applying a binary mask to its enhanced gray (enh_gray). The binarization threshold is automatically determined using Yen’s method. The resulting binary mask is stored in the image’s objmask attribute.

Parameters:

image (Image) – The arr image object. It must have an enh_gray attribute, which is used as the basis for creating the binary mask.

Returns:

The arr image object with its objmask attribute updated

to the computed binary mask other_image.

Return type:

Image

dispose_widgets() → None#

Drop references to the UI widgets.

Return type:

None

sync_widgets_from_state() → None#

Push internal state into widgets.

Return type:

None

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.