phenotypic.abc_.MeasureFeatures#

class phenotypic.abc_.MeasureFeatures(*args, **kwargs)[source]

Bases: BaseOperation, ABC

Extract quantitative measurements from detected colony objects in images.

MeasureFeatures is the abstract base class for all feature extraction operations in PhenoTypic. Unlike ImageOperation classes that return modified images, MeasureFeatures subclasses extract numerical measurements from detected objects and return pandas DataFrames.

Quick Decision Guide:

Use MeasureFeatures when you need to extract numerical colony phenotypes from detected objects. Choose specific measurers based on your phenotype of interest:

  • Size/morphology: [MeasureSize](src/phenotypic/measure/_measure_size.py) for area, perimeter, circularity

  • Shape characteristics: [MeasureShape](src/phenotypic/measure/_measure_shape.py) for aspect ratio, eccentricity

  • Color/pigmentation: [MeasureColor](src/phenotypic/measure/_measure_color.py) for RGB, Lab, HSV measurements

  • Intensity distribution: [MeasureIntensity](src/phenotypic/measure/_measure_intensity.py) for brightness statistics

  • Surface texture: [MeasureTexture](src/phenotypic/measure/_measure_texture.py) for roughness, biofilm detection

  • Custom features: Subclass MeasureFeatures directly for novel measurements

Design Principles:

This class follows a strict pattern where subclasses implement minimal code:

  1. __init__: Define parameters and configuration for your measurement

  2. _operate(image: Image) -> pd.DataFrame: Implement your measurement logic

  3. Everything else (type validation, metadata handling, exception handling) is handled by the measure() method

This ensures consistent behavior, robust error handling, and automatic memory profiling across all measurement operations.

How It Works:

Users call the public API method measure(image, include_meta=False), which:

  1. Validates input (Image object with detected objects)

  2. Extracts operation parameters using introspection

  3. Calls _operate() with matched parameters

  4. Optionally merges image metadata into results

  5. Returns a pandas DataFrame with object labels in the first column

Subclasses only override _operate() and __init__(). The measure() method provides automatic validation, exception handling, and metadata merging.

Accessing Image Data in _operate():

Within your _operate() implementation, access image data through accessors (lazy-evaluated, cached):

  • image.gray[:] - Grayscale intensity values (weighted luminance)

  • image.detect_mat[:] - Detection matrix (preprocessed for analysis)

  • image.objmask[:] - Binary mask of detected objects (1 = object, 0 = background)

  • image.objmap[:] - Labeled integer array (label ID per object, 0 = background)

  • image.color.Lab[:] - CIE Lab color space (perceptually uniform)

  • image.color.XYZ[:] - CIE XYZ color space

  • image.color.HSV[:] - HSV color space (hue, saturation, value)

  • image.objects - High-level object interface (iterate with for loop)

  • image.num_objects - Count of detected objects

DataFrame Output Format:

Your _operate() method must return a pandas DataFrame with:

  • First column: OBJECT.LABEL (integer object IDs matching image.objmap[:])

  • Subsequent columns: Measurement results (numeric values)

  • One row per detected object

Example structure:

OBJECT.LABEL | Area | MeanIntensity | StdDev
-----------  |------|---------------|--------
1            | 1024 | 128.5         | 12.3
2            | 956  | 135.2         | 14.1
3            | 1101 | 120.8         | 11.9

Static Helper Methods for Common Measurements:

This class provides 20+ static helper methods to compute statistics on labeled objects:

  • Statistical: mean, median, stddev, variance, sum, center_of_mass

  • Extrema: minimum, maximum, min_extrema (position + value), max_extrema (position + value)

  • Quantiles: Q1 (25th percentile), Q3 (75th percentile), IQR (interquartile range)

  • Advanced: coefficient_of_variation (relative texture measure), custom function application

  • Custom computation: _funcmap2objects() to apply arbitrary Python functions to object regions

  • Utilities: _ensure_array() to normalize scalars and arrays uniformly

Helper Method Usage Pattern:

All helpers follow a consistent signature: _calculate_*(array, objmap=None) where array is your 2D data and objmap is the labeled integer array from image.objmap[:]. If objmap=None, the entire non-zero region is treated as one object. Returns 1D numpy array with one value per object (or scalar for single-object mode).

Example within _operate():

gray = image.detect_mat[:]
objmap = image.objmap[:]
area = self._calculate_sum(image.objmask[:], objmap)  # Pixel count
mean_int = self._calculate_mean(gray, objmap)  # Average brightness
stddev = self._calculate_stddev(gray, objmap)  # Texture uniformity
cv = self._calculate_coeff_variation(gray, objmap)  # Relative variation

Example: Creating a Custom Measurer for Bacterial Colonies

Implementing a custom colony measurement class:

>>> from phenotypic.abc_ import MeasureFeatures
>>> from phenotypic.tools\_.constants_ import OBJECT
>>> import pandas as pd
>>> import numpy as np
>>> class MeasureCustom(MeasureFeatures):
...     '''Measure custom morphology metrics for microbial colonies.'''
...
...     def __init__(self, intensity_threshold=100):
...         '''Initialize with intensity threshold for bright pixels.'''
...         self.intensity_threshold = intensity_threshold
...
...     def _operate(self, image):
...         '''Extract bright region area and mean intensity.'''
...         gray = image.detect_mat[:]
...         objmap = image.objmap[:]
...         # Identify bright pixels within each object
...         bright_mask = gray > self.intensity_threshold
...         # Count bright pixels per object
...         bright_area = self._calculate_sum(
...             array=bright_mask.astype(int),
...             objmap=objmap
...         )
...         # Mean intensity of bright pixels
...         bright_intensity = self._funcmap2objects(
...             func=lambda arr: np.mean(arr[arr > self.intensity_threshold]),
...             out_dtype=float,
...             array=gray,
...             objmap=objmap,
...             default=np.nan
...         )
...         # Create results DataFrame
...         results = pd.DataFrame({
...             'BrightArea': bright_area,
...             'BrightMeanIntensity': bright_intensity,
...         })
...         results.insert(0, OBJECT.LABEL, image.objects.labels2series())
...         return results
>>> # Usage:
>>> from phenotypic import Image
>>> image = Image('colony_plate.jpg')
>>> # (After detection...)
>>> measurer = MeasureCustom(intensity_threshold=150)
>>> measurements = measurer.measure(image)  # Returns DataFrame

When to Use MeasureFeatures vs ImageOperation:

Use MeasureFeatures when you want to extract numerical metrics from objects (returns DataFrame). Use ImageOperation (ImageEnhancer, ImageCorrector, ObjectDetector) when you want to modify the image (returns Image).

Microbe Phenotyping Context:

In arrayed microbial growth assays, measurements extract colony phenotypes: morphology (size, shape, compactness), color (pigmentation, growth medium binding), texture (biofilm formation, colony surface roughness), and intensity distribution (density variation, heterogeneity). These measurements feed into genetic and environmental association studies.

No public attributes. Configuration is passed through __init__() parameters.

Examples

Basic usage: measure colony area and intensity:

>>> from phenotypic import Image
>>> from phenotypic.measure import MeasureSize
>>> # Load and detect colonies
>>> image = Image('plate_image.jpg')
>>> from phenotypic.detect import OtsuDetector
>>> detector = OtsuDetector()
>>> image = detector.operate(image)
>>> # Extract size measurements
>>> measurer = MeasureSize()
>>> df = measurer.measure(image)
>>> print(df)
# Output:
#   OBJECT.LABEL  Area  IntegratedIntensity
# 0             1  1024                 128512
# 1             2   956                 121232
# 2             3  1101                 134232

Advanced: extract multiple measurement types with metadata:

>>> from phenotypic.measure import (
...     MeasureSize,
...     MeasureShape,
...     MeasureColor
... )
>>> from phenotypic._core import ImagePipeline
>>> # Create pipeline combining detectors and measurers
>>> pipeline = ImagePipeline(
...     detector=OtsuDetector(),
...     measurers=[
...         MeasureSize(),
...         MeasureShape(),
...         MeasureColor(include_XYZ=False)
...     ]
... )
>>> # Measure a single image with metadata
>>> results = pipeline.operate(image)
>>> # Combine measurements: merge multiple DataFrames by OBJECT.LABEL
>>> combined = results[0]
>>> for df in results[1:]:
...     combined = combined.merge(df, on=OBJECT.LABEL)

Custom feature engineering: growth density index:

>>> from phenotypic.abc_ import MeasureFeatures
>>> from phenotypic.tools\_.constants_ import OBJECT
>>> import pandas as pd
>>> import numpy as np
>>> class MeasureGrowthDensity(MeasureFeatures):
...     '''Custom measurer: compute colony compactness index.'''
...
...     def _operate(self, image):
...         '''Calculate area, perimeter, and density index.'''
...         objmap = image.objmap[:]
...         gray = image.detect_mat[:]
...         # Area and perimeter
...         area = self._calculate_sum(image.objmask[:], objmap)
...         perimeter = self._funcmap2objects(
...             func=lambda arr: np.sqrt(np.sum(arr > 0)) * 4,
...             out_dtype=float,
...             array=image.objmask[:],
...             objmap=objmap
...         )
...         # Mean intensity (growth density)
...         mean_intensity = self._calculate_mean(gray, objmap)
...         # Compactness = 4*pi*Area / Perimeter^2
...         compactness = (4 * np.pi * area) / (perimeter ** 2 + 1e-6)
...         results = pd.DataFrame({
...             'Area': area,
...             'Perimeter': perimeter,
...             'MeanIntensity': mean_intensity,
...             'CompactnessIndex': compactness,
...         })
...         results.insert(0, OBJECT.LABEL, image.objects.labels2series())
...         return results

Methods

__init__

measure

Execute the measurement operation on a detected-object image.
measure(image, include_meta=False)[source]

Execute the measurement operation on a detected-object image.

This is the main public API method for extracting measurements. It handles: input validation, parameter extraction via introspection, calling the subclass-specific _operate() method, optional metadata merging, and exception handling.

How it works (for users):

  1. Pass your processed Image (with detected objects) to measure()

  2. The method calls your subclass’s _operate() implementation

  3. Results are validated and returned as a pandas DataFrame

  4. If include_meta=True, image metadata (filename, grid info) is merged in

How it works (for developers):

When you subclass MeasureFeatures, you only implement _operate(). This measure() method automatically:

  • Extracts __init__ parameters from your instance (introspection)

  • Passes matched parameters to _operate() as keyword arguments

  • Validates the Image has detected objects (objmap)

  • Wraps exceptions in OperationFailedError with context

  • Merges grid/object metadata if requested

Parameters:

  • image (Image) – A PhenoTypic Image object with detected objects (must have non-empty objmap from a prior detection operation).

  • include_meta (bool, optional) – If True, merge image metadata columns (filename, grid position, etc.) into the results DataFrame. Defaults to False.

Returns:

Measurement results with structure:

  • First column: OBJECT.LABEL (integer IDs from image.objmap[:])

  • Remaining columns: Measurement values (float, int, or string)

  • One row per detected object

If include_meta=True, additional metadata columns are prepended before OBJECT.LABEL (e.g., Filename, GridRow, GridCol).

Return type:

pd.DataFrame

Raises:

OperationFailedError – If _operate() raises any exception, it is caught and re-raised as OperationFailedError with details including the original exception type, message, image name, and operation class. This provides consistent error handling across all measurers.

Notes

  • This method is the main entry point; do not override in subclasses

  • Subclasses implement _operate() only, not this method

  • Automatic memory profiling is available via logging configuration

  • Image must have detected objects (image.objmap should be non-empty)

Examples

Basic measurement extraction:

>>> from phenotypic import Image
>>> from phenotypic.measure import MeasureSize
>>> from phenotypic.detect import OtsuDetector
>>> # Load and detect
>>> image = Image('plate.jpg')
>>> image = OtsuDetector().operate(image)
>>> # Extract measurements
>>> measurer = MeasureSize()
>>> df = measurer.measure(image)
>>> print(df.head())

Include metadata in measurements:

>>> # With image metadata (filename, grid info)
>>> df_with_meta = measurer.measure(image, include_meta=True)
>>> print(df_with_meta.columns)
# Output: ['Filename', 'GridRow', 'GridCol', 'OBJECT.LABEL',
#          'Area', 'IntegratedIntensity', ...]
__del__()

Automatically stop tracemalloc when the object is deleted.

This Page