phenotypic.abc_.MeasureFeatures#

class phenotypic.abc_.MeasureFeatures[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.

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.enh_gray[:] - Enhanced grayscale (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:

This class provides 20+ static helper methods for common measurements on labeled objects:

  • Statistical: _calculate_mean(), _calculate_median(), _calculate_stddev(), _calculate_variance(), _calculate_sum(), _calculate_center_of_mass()

  • Extrema: _calculate_minimum(), _calculate_maximum(), _calculate_extrema()

  • Quantiles: _calculate_q1(), _calculate_q3(), _calculate_iqr()

  • Advanced: _calculate_coeff_variation(), _calculate_min_extrema(), _calculate_max_extrema()

  • Custom: _funcmap2objects() (apply arbitrary functions to labeled regions)

  • Utility: _ensure_array() (normalize scalar/array inputs)

All helpers accept an objmap parameter (labeled integer array). If None, the entire non-zero region is treated as a single object.

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.enh_gray[:]
        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.from_image_path('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.from_image_path('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)

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.from_image_path('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.