phenotypic.prefab.HeavyRoundPeaksPipeline#

class phenotypic.prefab.HeavyRoundPeaksPipeline(bm3d_sigma: float = 0.02, bm3d_stage_arg: Literal['all_stages', 'hard_thresholding'] = 'all_stages', clahe_kernel_size: int | None = None, median_shape: Literal['disk', 'square', 'diamond'] = 'diamond', median_radius: int = 5, detector_thresh_method: Literal['gitter', 'otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata'] = 'gitter', detector_subtract_background: bool = True, detector_remove_noise: bool = False, detector_fast_resize: int | None = 1000, detector_fixed_square: float = 2.0, detector_expf: float = 1.5, mask_opener_footprint: Literal['auto'] | ndarray | int | None = 'auto', border_remover_size: int = 1, small_object_min_size: int = 50, texture_scale: int = 5, texture_warn: bool = False, benchmark: bool = False, verbose: bool = False)[source]#

Bases: PrefabPipeline

Configures and initializes a robust image processing pipeline tailored for analyzing circular colonies grown on solid media agar. It incorporates preprocessing, detection, morphological refinement, and feature extraction stages, with customizable parameters to handle diverse experimental setups and imaging conditions. Adjusting attributes fine-tunes pipeline behavior and impacts colony detection and measurement accuracy.

Operations:

  1. BM3DDenoiser

  2. CLAHE

  3. MedianFilter

  4. RoundPeaksDetector

  5. MaskOpener

  6. BorderObjectRemover

  7. SmallObjectRemover

  8. MaskFill

  9. GridOversizedObjectRemover

  10. MinResidualRemover

  11. GridAligner

  12. RoundPeaksDetector (second pass since alignment might improve detection)

  13. MaskOpener

  14. BorderObjectRemover

  15. SmallObjectRemover

  16. MaskFill

  17. MinResidualReducer

Measurements:

  • MeasureShape

  • MeasureColor

  • MeasureIntensity

  • MeasureTexture

Methods

__init__

Represents an image processing pipeline for analyzing microbe colonies on solid media agar.

apply

The class provides an abc_ to process and apply a series of operations on an Image.

apply_and_measure

Applies processing to the given image and measures the results.

benchmark_results

Returns a table of execution times for operations and measurements.

dispose_widgets

Drop references to the UI widgets.

from_json

Deserialize a pipeline from JSON format.

measure

Measures properties of a given image and optionally includes metadata.

set_meas

Sets the measurements to be used for further computation.

set_ops

Sets the operations to be performed.

sync_widgets_from_state

Push internal state into widgets.

to_json

Serialize the pipeline configuration to JSON format.

widget

Return (and optionally display) the root widget.
Parameters:

  • bm3d_sigma (float)

  • bm3d_stage_arg (Literal['all_stages', 'hard_thresholding'])

  • clahe_kernel_size (int | None)

  • median_shape (Literal['disk', 'square', 'diamond'])

  • median_radius (int)

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

  • detector_subtract_background (bool)

  • detector_remove_noise (bool)

  • detector_fast_resize (int | None)

  • detector_fixed_square (float)

  • detector_expf (float)

  • mask_opener_footprint (Literal['auto'] | ~numpy.ndarray | int | None)

  • border_remover_size (int)

  • small_object_min_size (int)

  • texture_scale (int)

  • texture_warn (bool)

  • benchmark (bool)

  • verbose (bool)

__init__(bm3d_sigma: float = 0.02, bm3d_stage_arg: Literal['all_stages', 'hard_thresholding'] = 'all_stages', clahe_kernel_size: int | None = None, median_shape: Literal['disk', 'square', 'diamond'] = 'diamond', median_radius: int = 5, detector_thresh_method: Literal['gitter', 'otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata'] = 'gitter', detector_subtract_background: bool = True, detector_remove_noise: bool = False, detector_fast_resize: int | None = 1000, detector_fixed_square: float = 2.0, detector_expf: float = 1.5, mask_opener_footprint: Literal['auto'] | ndarray | int | None = 'auto', border_remover_size: int = 1, small_object_min_size: int = 50, texture_scale: int = 5, texture_warn: bool = False, benchmark: bool = False, verbose: bool = False) → None[source]#

Represents an image processing pipeline for analyzing microbe colonies on solid media agar. The pipeline includes preprocessing, detection, morphological refinement, and measurement steps.

Parameters:

  • bm3d_sigma (float)

  • bm3d_stage_arg (Literal['all_stages', 'hard_thresholding'])

  • clahe_kernel_size (int | None)

  • median_shape (Literal['disk', 'square', 'diamond'])

  • median_radius (int)

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

  • detector_subtract_background (bool)

  • detector_remove_noise (bool)

  • detector_fast_resize (int | None)

  • detector_fixed_square (float)

  • detector_expf (float)

  • mask_opener_footprint (Literal['auto'] | ~numpy.ndarray | int | None)

  • border_remover_size (int)

  • small_object_min_size (int)

  • texture_scale (int)

  • texture_warn (bool)

  • benchmark (bool)

  • verbose (bool)

Return type:

None

bm3d_sigma#

Controls the degree of noise reduction during BM3D denoising. Lower values retain more fine details, which might preserve subtle colony textures. Higher values remove more noise but may blur colony edges, affecting detection accuracy.

bm3d_stage_arg#

Specifies the stage of BM3D denoising. “all_stages” applies more comprehensive denoising, potentially enhancing signal uniformity but may result in detail loss. “hard_thresholding” retains more high-frequency details but may leave more background noise intact.

clahe_kernel_size#

Determines the size of the kernel used for local contrast enhancement via CLAHE. Larger sizes improve contrast over broader areas, but may over-amplify large background variations. Smaller sizes enhance localized details but may introduce noise.

median_shape#

Defines the morphological shape (“disk”, “square”, “diamond”) used for median filtering. The choice impacts how texture and artifacts are smoothed. For instance, “disk” may preserve radial features, whereas “square” provides edge-focused filtering.

median_radius#

Dictates the radius for median filtering. Smaller values enhance fine textural differences, whereas larger radii smooth broader regions, potentially affecting the precise detection of small colonies.

detector_thresh_method#

Specifies the thresholding method for binary segmentation. “gitter” uses iterative thresholding from the original algorithm, robust to uneven illumination. “otsu” or “triangle” focus on global thresholding, suitable for uniform backgrounds. “local” adapts to background variations but may increase runtime.

detector_subtract_background#

Toggles background normalization during the detection stage. Enabling this helps standardize varying lighting or agar density but may also obscure genuine gradients or subtle ring colonies.

detector_remove_noise#

Sets whether small noisy objects are removed during detection. True ensures a cleaner output but may falsely discard tiny colonies. False retains all details, which can increase false-positive noise levels.

detector_fast_resize#

Downsample height used during background correction; larger values better preserve small colonies at the cost of speed. None disables downsampling.

detector_fixed_square#

Fallback box multiplier when the center pixel is 0; raise for hollow or frayed colonies so bounding boxes still capture area.

detector_expf#

Expansion factor for rectangles around detected peaks; increase if colonies sprawl or have halos, decrease to reduce spillover into neighbors on dense plates.

mask_opener_footprint#

Describes the morphological footprint for noise removal or mask refinement. “auto” lets the system adapt, while specifying values allows control over the scale of mask cleanup or preservation of detailed structures.

border_remover_size#

Specifies the width of the border region to remove. Larger sizes eliminate edge artifacts and colonies cropped by image edges but may discard valid colonies near borders.

small_object_min_size#

Specifies the size threshold for considering objects as colonies. Increasing this parameter reduces false detection of small artifacts but risks ignoring small colonies.

texture_scale#

Defines the spatial scale at which texture features are measured. Larger scales focus on macro-textures; smaller scales enhance granular detail assessment.

texture_warn#

Boolean that enables warnings when texture measurements may not be reliable. Use this to flag potential inconsistencies in the captured texture data or image quality issues.

benchmark#

Enables time benchmarking for each pipeline step. Useful for performance debugging but adds overhead to the computation.

verbose#

Specifies whether to output detailed process information during execution. True provides step-by-step logs, which are useful for debugging, while False ensures silent execution suitable for batch processing.

__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: Image, inplace: bool = False, reset: bool = True) → GridImage | Image#

The class provides an abc_ to process and apply a series of operations on an Image. The operations are maintained in a queue and executed sequentially when applied to the given Image.

Parameters:

  • image (Image) – The arr Image to be processed. The type Image refers to an instance of the Image object to which transformations are applied.

  • inplace (bool, optional) – A flag indicating whether to apply the transformations directly on the provided Image (True) or create a copy of the Image before performing transformations (False). Defaults to False.

  • reset (bool) – Whether to reset the image before applying the pipeline

Return type:

Union[GridImage, Image]

apply_and_measure(image: Image, inplace: bool = False, reset: bool = True, include_metadata: bool = True) → pd.DataFrame#

Applies processing to the given image and measures the results.

This function first applies a processing method to the supplied image, adjusting it based on the given parameters. After processing, the resulting image is measured, and a DataFrame containing the measurement data is returned.

Parameters:

  • image (Image) – The image to process and measure.

  • inplace (bool) – Whether to modify the original image directly or work on a copy. Default is False.

  • reset (bool) – Whether to reset any previous processing on the image before applying the current method. Default is True.

  • include_metadata (bool) – Whether to include metadata in the measurement results. Default is True.

Returns:

A DataFrame containing measurement data for the processed image.

Return type:

pd.DataFrame

benchmark_results() → pandas.DataFrame#

Returns a table of execution times for operations and measurements.

This method should be called after applying the pipeline on an image to get the execution times of the different processes.

Returns:

A DataFrame containing execution times for each operation and measurement.

Return type:

pd.DataFrame

dispose_widgets() → None#

Drop references to the UI widgets.

Return type:

None

classmethod from_json(json_data: str | Path) → SerializablePipeline#

Deserialize a pipeline from JSON format.

This method reconstructs a pipeline from a JSON string or file, restoring all operations, measurements, and configuration flags. Classes are imported from the phenotypic namespace and instantiated with their saved parameters.

Parameters:

json_data (str | Path) – Either a JSON string or a path to a JSON file.

Returns:

A new pipeline instance with the loaded configuration.

Return type:

SerializablePipeline

Raises:

  • ValueError – If the JSON is invalid or cannot be parsed.

  • ImportError – If a required operation or measurement class cannot be imported.

  • AttributeError – If a class cannot be found in the phenotypic namespace.

Example

Deserialize a pipeline from JSON format
>>> from phenotypic import ImagePipeline
>>>
>>> # Load from file
>>> pipe = ImagePipeline.from_json('my_pipeline.json')
>>>
>>> # Load from string
>>> json_str = '{"ops": {...}, "meas": {...}}'
>>> pipe = ImagePipeline.from_json(json_str)
measure(image: Image, include_metadata=True) → pd.DataFrame#

Measures properties of a given image and optionally includes metadata. The method performs measurements using a set of predefined measurement operations. If benchmarking is enabled, the execution time of each measurement is recorded. When verbose mode is active, detailed logging of the measurement process is displayed. A progress bar is used to track progress if the tqdm library is available.

Parameters:

  • image (Image) – The image object for which measurements are performed. It must support the info method and optionally a grid or objects attribute.

  • include_metadata (bool, optional) – Indicates whether metadata should be included in the measurements. Defaults to True.

Returns:

A DataFrame containing the results of all performed measurements combined

on the same index.

Return type:

pd.DataFrame

Raises:

Exception – An exception is raised if a measurement operation fails while being applied to the image.

set_meas(measurements: List[MeasureFeatures] | Dict[str, MeasureFeatures])#

Sets the measurements to be used for further computation. The input can be either a list of MeasureFeatures objects or a dictionary with string keys and MeasureFeatures objects as values.

The method processes the given input to construct a dictionary mapping measurement names to MeasureFeatures instances. If a list is passed, unique class names of the MeasureFeatures instances in the list are used as keys.

Parameters:

measurements (List[MeasureFeatures] | Dict[str, MeasureFeatures]) – A collection of measurement features either as a list of MeasureFeatures objects, where class names are used as keys for dictionary creation, or as a dictionary where keys are predefined strings and values are MeasureFeatures objects.

Raises:

TypeError – If the measurements argument is neither a list nor a dictionary.

set_ops(ops: List[ImageOperation] | Dict[str, ImageOperation])#

Sets the operations to be performed. The operations can be passed as either a list of ImageOperation instances or a dictionary mapping operation names to ImageOperation instances. This method ensures that each operation in the list has a unique name. Raises a TypeError if the input is neither a list nor a dictionary.

Parameters:

ops (List[ImageOperation] | Dict[str, ImageOperation]) – A list of ImageOperation objects or a dictionary where keys are operation names and values are ImageOperation objects.

Raises:

TypeError – If the input is not a list or a dictionary.

sync_widgets_from_state() → None#

Push internal state into widgets.

Return type:

None

to_json(filepath: str | Path | None = None) → str#

Serialize the pipeline configuration to JSON format.

This method captures the pipeline’s operations, measurements, and configuration flags. It excludes internal state (attributes starting with ‘_’) and pandas DataFrames to keep the serialization clean and focused on reproducible configuration.

Parameters:

filepath (str | Path | None) – Optional path to save the JSON. If None, returns JSON string. Can be a string or Path object.

Returns:

JSON string representation of the pipeline configuration.

Return type:

str

Example

Serialize a pipeline to JSON format
>>> from phenotypic import ImagePipeline
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.measure import MeasureShape
>>>
>>> pipe = ImagePipeline(ops=[OtsuDetector()], meas=[MeasureShape()])
>>> json_str = pipe.to_json()
>>> pipe.to_json('my_pipeline.json')  # Save to file
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.