phenotypic.prefab#
Prefab pipelines for fungal colony plate processing.
Ready-to-run chains of enhancement, detection, refinement, and measurement steps tuned for common agar plate scenarios. Includes watershed-heavy pipelines for clustered colonies, Otsu-based pipelines for clean backgrounds, grid-section pipelines for tiled inputs, and grid-aware Gitter-style processing for dense arrays.
Classes
Provides an image processing pipeline with robust preprocessing/post-processing and watershed segmentation. |
|
The HeavyWatershedPipeline class is a composite image processing pipeline that combines multiple layers of preprocessing, detection, and filtering steps that can will select the right colonies in most cases. |
|
Provides an image processing pipeline designed for grid-based section-level analysis. |
|
Configures and initializes a robust image processing pipeline tailored for analyzing circular colonies grown on solid media agar. |
|
Lightweight pipeline for circular colonies on solid media agar. |
- class phenotypic.prefab.GridSectionPipeline(gaussian_sigma: int = 10, gaussian_mode: str = 'reflect', gaussian_truncate: float = 4.0, clahe_kernel_size: int | None = None, clahe_clip_limit: float = 0.01, median_mode: str = 'nearest', median_cval: float = 0.0, otsu_ignore_zeros: bool = True, otsu_ignore_borders: bool = True, border_remover_size: int | float | None = 50, circularity_cutoff: float = 0.6, small_object_min_size: int = 100, outlier_axis: int | None = None, outlier_stddev_multiplier: float = 1.5, outlier_max_coeff_variance: int = 1, aligner_axis: int = 0, aligner_mode: str = 'edge', section_blur_sigma: int = 5, section_blur_mode: str = 'reflect', section_blur_truncate: float = 4.0, section_median_mode: str = 'nearest', section_median_cval: float = 0.0, section_contrast_lower_percentile: int = 2, section_contrast_upper_percentile: int = 98, section_otsu_ignore_zeros: bool = True, section_otsu_ignore_borders: bool = True, grid_apply_reset_enh_matrix: bool = True, small_object_min_size_2: int = 100, color_white_chroma_max: float = 4.0, color_chroma_min: float = 8.0, color_include_XYZ: bool = False, texture_scale: int | list[int] = 5, texture_quant_lvl: Literal[8, 16, 32, 64] = 32, texture_enhance: bool = False, texture_warn: bool = False, benchmark: bool = False, **kwargs)[source]#
Bases:
PrefabPipelineProvides an image processing pipeline designed for grid-based section-level analysis.
This class defines a sequence of operations and measurements optimized for processing gridded images where each section is analyzed independently. The pipeline includes multiple stages of preprocessing, detection, filtering, and alignment steps, followed by section-level detection and final measurements.
- Parameters:
gaussian_sigma (int)
gaussian_mode (str)
gaussian_truncate (float)
clahe_kernel_size (int | None)
clahe_clip_limit (float)
median_mode (str)
median_cval (float)
otsu_ignore_zeros (bool)
otsu_ignore_borders (bool)
circularity_cutoff (float)
small_object_min_size (int)
outlier_axis (int | None)
outlier_stddev_multiplier (float)
outlier_max_coeff_variance (int)
aligner_axis (int)
aligner_mode (str)
section_blur_sigma (int)
section_blur_mode (str)
section_blur_truncate (float)
section_median_mode (str)
section_median_cval (float)
section_contrast_lower_percentile (int)
section_contrast_upper_percentile (int)
section_otsu_ignore_zeros (bool)
section_otsu_ignore_borders (bool)
grid_apply_reset_enh_matrix (bool)
small_object_min_size_2 (int)
color_white_chroma_max (float)
color_chroma_min (float)
color_include_XYZ (bool)
texture_quant_lvl (Literal[8, 16, 32, 64])
texture_enhance (bool)
texture_warn (bool)
benchmark (bool)
- outlier_axis#
Axis for outlier analysis. None for both, 0 for rows, 1 for columns.
- Type:
Optional[int]
- grid_apply_reset_enh_matrix#
Whether to reset enh_gray before applying section-level pipeline.
- Type:
- texture_quant_lvl#
Quantization level for texture computation.
- Type:
Literal[8, 16, 32, 64]
- __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.
- __init__(gaussian_sigma: int = 10, gaussian_mode: str = 'reflect', gaussian_truncate: float = 4.0, clahe_kernel_size: int | None = None, clahe_clip_limit: float = 0.01, median_mode: str = 'nearest', median_cval: float = 0.0, otsu_ignore_zeros: bool = True, otsu_ignore_borders: bool = True, border_remover_size: int | float | None = 50, circularity_cutoff: float = 0.6, small_object_min_size: int = 100, outlier_axis: int | None = None, outlier_stddev_multiplier: float = 1.5, outlier_max_coeff_variance: int = 1, aligner_axis: int = 0, aligner_mode: str = 'edge', section_blur_sigma: int = 5, section_blur_mode: str = 'reflect', section_blur_truncate: float = 4.0, section_median_mode: str = 'nearest', section_median_cval: float = 0.0, section_contrast_lower_percentile: int = 2, section_contrast_upper_percentile: int = 98, section_otsu_ignore_zeros: bool = True, section_otsu_ignore_borders: bool = True, grid_apply_reset_enh_matrix: bool = True, small_object_min_size_2: int = 100, color_white_chroma_max: float = 4.0, color_chroma_min: float = 8.0, color_include_XYZ: bool = False, texture_scale: int | list[int] = 5, texture_quant_lvl: Literal[8, 16, 32, 64] = 32, texture_enhance: bool = False, texture_warn: bool = False, benchmark: bool = False, **kwargs)[source]#
Initializes the GridSectionPipeline with customizable operations and measurements.
- Parameters:
gaussian_sigma (int) – Standard deviation for Gaussian kernel in initial smoothing.
gaussian_mode (str) – Mode for handling image boundaries during Gaussian smoothing.
gaussian_truncate (float) – Truncate the Gaussian kernel at this many standard deviations.
clahe_kernel_size (int | None) – Size of kernel for CLAHE. If None, automatically calculated.
clahe_clip_limit (float) – Contrast limit for CLAHE.
median_mode (str) – Boundary mode for median filter.
median_cval (float) – Constant value for median filter when mode is ‘constant’.
otsu_ignore_zeros (bool) – Whether to ignore zero pixels in Otsu thresholding.
otsu_ignore_borders (bool) – Whether to ignore border objects in Otsu detection.
border_remover_size (int | float | None) – Size of border region where objects are removed.
circularity_cutoff (float) – Minimum circularity threshold for objects to be retained.
small_object_min_size (int) – Minimum size of objects to retain in first removal step.
outlier_axis (Optional[int]) – Axis for outlier analysis. None for both, 0 for rows, 1 for columns.
outlier_stddev_multiplier (float) – Multiplier for standard deviation in outlier detection.
outlier_max_coeff_variance (int) – Maximum coefficient of variance for outlier analysis.
aligner_axis (int) – Axis for grid alignment (0 for rows, 1 for columns).
aligner_mode (str) – Mode for grid alignment rotation.
section_blur_sigma (int) – Standard deviation for Gaussian kernel in section-level detection.
section_blur_mode (str) – Mode for Gaussian smoothing in section-level detection.
section_blur_truncate (float) – Truncate for Gaussian kernel in section-level detection.
section_median_mode (str) – Boundary mode for median filter in section-level detection.
section_median_cval (float) – Constant value for median filter in section-level detection.
section_contrast_lower_percentile (int) – Lower percentile for contrast stretching in sections.
section_contrast_upper_percentile (int) – Upper percentile for contrast stretching in sections.
section_otsu_ignore_zeros (bool) – Whether to ignore zeros in section-level Otsu detection.
section_otsu_ignore_borders (bool) – Whether to ignore borders in section-level Otsu detection.
grid_apply_reset_enh_matrix (bool) – Whether to reset enh_gray before applying section-level pipeline.
small_object_min_size_2 (int) – Minimum size of objects to retain in second removal step.
color_white_chroma_max (float) – Maximum white chroma value for color measurement.
color_chroma_min (float) – Minimum chroma value for color measurement.
color_include_XYZ (bool) – Whether to include XYZ color space measurements.
texture_scale (int | list[int]) – Scale parameter(s) for Haralick texture features.
texture_quant_lvl (Literal[8, 16, 32, 64]) – Quantization level for texture computation.
texture_enhance (bool) – Whether to enhance image before texture measurement.
texture_warn (bool) – Whether to warn on texture computation errors.
benchmark (bool) – Indicates whether benchmarking is enabled across the pipeline.
- 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:
- 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
- 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:
- 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.
- 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:
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:
- Returns:
The root widget.
- Return type:
ipywidgets.Widget
- Raises:
ImportError – If ipywidgets or IPython are not installed.
- class phenotypic.prefab.HeavyOtsuPipeline(gaussian_sigma: int = 5, gaussian_mode: str = 'reflect', gaussian_truncate: float = 4.0, otsu_ignore_zeros: bool = True, otsu_ignore_borders: bool = True, 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:
PrefabPipelineThe HeavyWatershedPipeline class is a composite image processing pipeline that combines multiple layers of preprocessing, detection, and filtering steps that can will select the right colonies in most cases. This comes at the cost of being a more computationally expensive pipeline.
- Pipeline Steps:
Gaussian Smoothing
CLAHE
Median Enhancement
Watershed Segmentation
Border Object Removal
Grid Oversized Object Removal
Minimum Residual Error Reduction
Grid Alignment
Repeat Watershed Segmentation
Repeat Border Object Removal
Repeat Minimum Residual Error Reduction
Mask Fill
- Measurements:
Shape
Color
Texture
Intensity
- Parameters:
gaussian_sigma (int)
gaussian_mode (str)
gaussian_truncate (float)
otsu_ignore_zeros (bool)
otsu_ignore_borders (bool)
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)
- __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.
- __init__(gaussian_sigma: int = 5, gaussian_mode: str = 'reflect', gaussian_truncate: float = 4.0, otsu_ignore_zeros: bool = True, otsu_ignore_borders: bool = True, 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]#
Initializes the object with a sequence of operations and measurements for image processing. The sequence includes smoothing, enhance, segmentation, border object removal, and various measurement steps for analyzing images. Customizable parameters allow for adjusting the processing pipeline for specific use cases such as image segmentation and feature extraction.
- Parameters:
gaussian_sigma (int) – Standard deviation for Gaussian kernel in smoothing.
gaussian_mode (str) – Mode for handling image boundaries in Gaussian smoothing.
gaussian_truncate (float) – Truncate filter at this many standard deviations.
otsu_ignore_zeros (bool) – Whether to ignore zero pixels in Otsu thresholding.
otsu_ignore_borders (bool) – Whether to ignore border objects in Otsu detection.
mask_opener_footprint (Literal['auto'] | ~numpy.ndarray | int | None) – Structuring element for morphological opening.
border_remover_size (int) – Size of border to remove objects from.
small_object_min_size (int) – Minimum size of objects to retain.
texture_scale (int) – Scale parameter for Haralick texture features.
texture_warn (bool) – Whether to warn on texture computation errors.
footprint – Deprecated, use mask_opener_footprint.
min_size – Deprecated, use small_object_min_size.
border_size – Deprecated, use border_remover_size.
benchmark (bool)
verbose (bool)
- 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:
- 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
- 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:
- 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.
- 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:
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:
- Returns:
The root widget.
- Return type:
ipywidgets.Widget
- Raises:
ImportError – If ipywidgets or IPython are not installed.
- 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:
PrefabPipelineConfigures 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:
BM3DDenoiser
CLAHE
MedianFilter
RoundPeaksDetector
MaskOpener
BorderObjectRemover
SmallObjectRemover
MaskFill
GridOversizedObjectRemover
MinResidualRemover
GridAligner
RoundPeaksDetector (second pass since alignment might improve detection)
MaskOpener
BorderObjectRemover
SmallObjectRemover
MaskFill
MinResidualReducer
- Measurements:
MeasureShape
MeasureColor
MeasureIntensity
MeasureTexture
- 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)
- __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.
- __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.
- 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:
- 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
- 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:
- 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.
- 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:
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:
- Returns:
The root widget.
- Return type:
ipywidgets.Widget
- Raises:
ImportError – If ipywidgets or IPython are not installed.
- class phenotypic.prefab.HeavyWatershedPipeline(gaussian_sigma: int = 5, gaussian_mode: str = 'reflect', gaussian_truncate: float = 4.0, watershed_footprint: Literal['auto'] | ndarray | int | None = None, watershed_min_size: int = 50, watershed_compactness: float = 0.001, watershed_connectivity: int = 1, watershed_relabel: bool = True, watershed_ignore_zeros: bool = True, border_remover_size: int = 25, circularity_cutoff: float = 0.5, texture_scale: int = 5, texture_warn: bool = False, benchmark: bool = False, **kwargs)[source]#
Bases:
PrefabPipelineProvides an image processing pipeline with robust preprocessing/post-processing and watershed segmentation.
This class defines a sequence of operations and measurements designed for image analysis. It includes smoothing, enhancement, segmentation, border object removal, and various analysis steps. The pipeline is highly customizable for tasks such as image segmentation and feature extraction, making it suitable for applications involving image quantification and preprocessing.
Note
This pipeline uses computationally intensive operations aimed at cases where there is heavy background noise
- Parameters:
gaussian_sigma (int)
gaussian_mode (str)
gaussian_truncate (float)
watershed_footprint (Literal['auto'] | ~numpy.ndarray | int | None)
watershed_min_size (int)
watershed_compactness (float)
watershed_connectivity (int)
watershed_relabel (bool)
watershed_ignore_zeros (bool)
border_remover_size (int)
circularity_cutoff (float)
texture_scale (int)
texture_warn (bool)
benchmark (bool)
- __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.
- __init__(gaussian_sigma: int = 5, gaussian_mode: str = 'reflect', gaussian_truncate: float = 4.0, watershed_footprint: Literal['auto'] | ndarray | int | None = None, watershed_min_size: int = 50, watershed_compactness: float = 0.001, watershed_connectivity: int = 1, watershed_relabel: bool = True, watershed_ignore_zeros: bool = True, border_remover_size: int = 25, circularity_cutoff: float = 0.5, texture_scale: int = 5, texture_warn: bool = False, benchmark: bool = False, **kwargs)[source]#
Initializes an image processing pipeline for various image analysis tasks such as object detection, segmentation, and measurement. This pipeline uses a combination of operations, including filtering, segmentation, and morphological processing, followed by shape, intensity, texture, and color measurements.
- Parameters:
gaussian_sigma (int, optional) – Standard deviation for Gaussian blur filter. Defaults to 5.
gaussian_mode (str, optional) – Mode parameter for Gaussian blur filter (e.g., ‘reflect’). Defaults to ‘reflect’.
gaussian_truncate (float, optional) – Truncate value for Gaussian kernel to limit its size. Defaults to 4.0.
watershed_footprint (Literal['auto'] | np.ndarray | int | None, optional) – Footprint size or structure for the watershed algorithm. Defaults to None.
watershed_min_size (int, optional) – Minimum size of the objects to be retained after watershed segmentation. Defaults to 50.
watershed_compactness (float, optional) – Compactness parameter for the watershed algorithm to control how tightly regions are formed. Defaults to 0.001.
watershed_connectivity (int, optional) – Connectivity parameter for region connectivity in watershed segmentation. Defaults to 1.
watershed_relabel (bool, optional) – Whether to relabel the regions after watershed segmentation. Defaults to True.
watershed_ignore_zeros (bool, optional) – Whether to ignore zero-valued regions in the watershed algorithm. Defaults to True.
border_remover_size (int, optional) – Size of the border in pixels to be removed during border object removal. Defaults to 25.
circularity_cutoff (float, optional) – Threshold for object circularity below which objects will be removed. Defaults to 0.5.
texture_scale (int, optional) – Scale parameter for texture measurement. Defaults to 5.
texture_warn (bool, optional) – Whether to issue warnings for invalid texture measurements. Defaults to False.
benchmark (bool, optional) – Whether to enable benchmarking of pipeline performance. Defaults to False.
**kwargs – Additional keyword arguments for parent class initialization.
- 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:
- 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
- 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:
- 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.
- 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:
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:
- Returns:
The root widget.
- Return type:
ipywidgets.Widget
- Raises:
ImportError – If ipywidgets or IPython are not installed.
- class phenotypic.prefab.RoundPeaksPipeline(*, blur_sigma: int = 5, blur_mode: str = 'reflect', blur_cval: float = 0.0, blur_truncate: float = 4.0, detector_thresh_method: Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata'] = 'otsu', detector_subtract_background: bool = True, detector_remove_noise: bool = True, detector_footprint_radius: int = 5, detector_smoothing_sigma: float = 2.0, detector_min_peak_distance: int | None = None, detector_peak_prominence: float | None = None, detector_edge_refinement: bool = True, texture_scale: int | List[int] = 5, texture_quant_lvl: Literal[8, 16, 32, 64] = 32, texture_enhance: bool = False, texture_warn: bool = False, benchmark: bool = False, verbose: bool = False)[source]#
Bases:
PrefabPipelineLightweight pipeline for circular colonies on solid media agar.
This prefab pipeline provides a streamlined sequence of operations tailored for imaging pinned or arrayed fungal colonies on solid media agar. It performs a gentle Gaussian blur to suppress scanner and agar noise, followed by a grid-aware circular colony detector and a compact set of measurement modules. Compared with
HeavyRoundPeaksPipeline, this variant exposes a smaller number of stages and parameters but still allows fine control over blur strength, thresholding, grid refinement, and texture scale.- Operations:
GaussianBlurRoundPeaksDetector
- Measurements:
MeasureShapeMeasureIntensityMeasureTextureMeasureColor
Parameters#
- blur_sigmaint, optional
Standard deviation (in pixels) of the Gaussian blur kernel. Lower values preserve sharp edges and small colonies, which is useful when pins produce tight colonies with fine boundaries. Higher values smooth away scanner grain and agar micro-texture but can merge neighboring colonies or wash out tiny satellite growth.
- blur_mode{“reflect”, “constant”, “nearest”}, optional
Boundary handling strategy for the blur.
"reflect"(default) mirrors intensities at the plate edge and avoids artificial halos, which is helpful for colonies close to the border of an agar image."constant"and"nearest"can be used for cropped regions but may introduce rim artifacts that slightly bias edge intensity and downstream detection.- blur_cvalfloat, optional
Constant fill value used when
blur_mode="constant". Setting this close to the background agar intensity can stabilize blur at cut edges of the plate. A value too bright or too dark may create spurious rims that either look like faint colonies or mask real colonies near the image boundary.- blur_truncatefloat, optional
Radius of the Gaussian kernel in standard deviations. Increasing this slightly widens the effective blur footprint and further smooths broad illumination gradients on the plate, at the cost of speed. For typical pinned fungal colonies, the default is usually sufficient; very large values can over-smooth diffuse halos or ring-like growth.
- detector_thresh_method{“otsu”, “mean”, “local”, “triangle”, “minimum”, “isodata”}, optional
Thresholding method used inside
RoundPeaksDetector."otsu"works well for plates with reasonably uniform agar and clear contrast between colonies and background."local"can cope with strong gradients or condensation streaks but may be slower."mean","triangle","minimum", and"isodata"offer alternative trade-offs and can be useful when colonies are very pale or when agar pigmentation varies strongly across the plate.- detector_subtract_backgroundbool, optional
Whether to normalize background intensity before thresholding. Enabling this (default) helps make colonies more comparable across plates with different agar batches or scanner settings. If disabled, very faint colonies on bright agar may be missed, but native shading patterns or radial nutrient gradients remain more faithful.
- detector_remove_noisebool, optional
Whether to remove small specks using a morphological opening before grid inference. This is often beneficial for fungal plates with dust, bubbles, or condensation droplets, but if colonies are extremely small (early time points or slow-growing strains) an aggressive noise removal may erase real colonies.
- detector_footprint_radiusint, optional
Radius in pixels used for morphological operations in the detector. Larger values clean up bigger spurious regions and slightly shrink detected colonies. For tightly pinned arrays, too large a radius can erode narrow colonies or disconnect wispy hyphal fronts, under- estimating colony size.
- detector_smoothing_sigmafloat, optional
Standard deviation of the 1D Gaussian smoothing used when estimating row/column intensity profiles for grid detection. Increasing this makes grid inference more robust to noisy or streaky agar images but may blur subtle deviations in grid regularity (e.g., warped pinning patterns) so that mispinned colonies are forced into a regular grid.
- detector_min_peak_distanceint or None, optional
Minimum allowed distance between inferred grid lines (peaks). When set explicitly, this constrains the expected spacing between pinned colony rows/columns, helping reject spurious peaks caused by glare or edge artifacts. If
None(default), the distance is estimated from the data, which is more flexible but can be unstable for plates with many missing colonies.- detector_peak_prominencefloat or None, optional
Minimum prominence required for peaks in the row/column profiles. Higher values make the detector ignore weak structures such as barely growing colonies or diffuse halos, focusing instead on strong, dense colonies. Lower values are more sensitive to early growth but can be confused by agar texture or illumination bands.
- detector_edge_refinementbool, optional
If
True, refines estimated grid edges using local intensity profiles. This improves alignment of each pinned colony to its grid cell, especially when colonies expand asymmetrically or when the plate is slightly shifted during imaging. Disabling refinement speeds up analysis but may misplace colonies at the edge of their wells.- texture_scaleint or list[int], optional
Spatial scale(s) in pixels at which texture is measured by
MeasureTexture. Smaller values emphasize fine-scale surface roughness (e.g., wrinkling or concentric ring patterns on filamentous colonies). Larger values summarize broader patterns such as coarse colony zoning or radial banding. Using multiple scales (by passing a list) increases feature richness but also computation time.- texture_quant_lvl{8, 16, 32, 64}, optional
Intensity quantization level for texture computation. Higher values capture subtler differences in pigmentation and surface texture but require more data and are more sensitive to noise. For images of fungal colonies with smooth agar backgrounds, 32 is a good balance; 8 or 16 may be preferable for very low-contrast plates.
- texture_enhancebool, optional
If
True, enhances contrast before measuring texture. This can make faint radial structures or sectoring within colonies more detectable, which is useful when subtle phenotypes matter. However, enhancement may exaggerate scanner artifacts or agar imperfections, so enabling it can bias texture metrics on marginal images.- texture_warnbool, optional
If
True, emits warnings when texture measurements may be unreliable (for example, very small colonies or extreme intensity clipping). This can help identify pins where scanner saturation, agar contamination, or segmentation artifacts distort morphology.- benchmarkbool, optional
If
True, records timing information for each pipeline stage. This is primarily useful when optimizing throughput for large plate series but adds minor overhead.- verbosebool, optional
If
True, logs additional information during pipeline execution. This can help debug unexpected detection behavior (e.g., missing rows of colonies) or confirm that grid inference behaves sensibly on new imaging setups.
Notes#
This pipeline is intended for relatively clean, well-aligned images of pinned or arrayed circular colonies on agar where only a modest amount of preprocessing is needed. For plates with severe background gradients, strong vignetting, or highly irregular grids, consider using
HeavyRoundPeaksPipeline, which exposes additional refinement and alignment stages.- __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:
- 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
- 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:
- 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.
- 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:
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:
- Returns:
The root widget.
- Return type:
ipywidgets.Widget
- Raises:
ImportError – If ipywidgets or IPython are not installed.
- Parameters:
blur_sigma (int)
blur_mode (str)
blur_cval (float)
blur_truncate (float)
detector_thresh_method (Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata'])
detector_subtract_background (bool)
detector_remove_noise (bool)
detector_footprint_radius (int)
detector_smoothing_sigma (float)
detector_min_peak_distance (int | None)
detector_peak_prominence (float | None)
detector_edge_refinement (bool)
texture_quant_lvl (Literal[8, 16, 32, 64])
texture_enhance (bool)
texture_warn (bool)
benchmark (bool)
verbose (bool)