phenotypic.measure.MeasureColor#

class phenotypic.measure.MeasureColor(white_chroma_max: float = 4.0, chroma_min: float = 8.0, include_XYZ: bool = False)[source]

Bases: MeasureFeatures

Measure colony color statistics across multiple perceptual color spaces.

Extract per-colony color features from CIE XYZ, chromaticity (xy), CIE Lab (perceptually uniform), and HSV color spaces. For each channel the standard statistical suite is computed (min, Q1, mean, median, Q3, max, std dev, coefficient of variation), plus Lab chroma estimates.

Args:

white_chroma_max: Lab chroma threshold below which a colony is
classified as achromatic (white). Default: 4.0.

chroma_min: Minimum chroma value retained in analysis; colonies
below this are treated as colorless. Default: 8.0.

include_XYZ: Compute CIE XYZ tristimulus statistics (slower).
Default: False.

Returns:
pd.DataFrame: Object-level color statistics with column groups:

ColorXYZ (X, Y, Z) – only when include_XYZ=True.

Colorxy (x, y chromaticity).

ColorLab (L*, a*, b*, ChromaEstimated).

ColorHSV (Hue, Saturation, Brightness).

Each channel has Min, Q1, Mean, Median, Q3, Max, StdDev, CoeffVar sub-columns.

Best For:

Distinguishing pigmented colonies (carotenoid, melanin) from colorless ones to stratify phenotypes by pigmentation profile.

Detecting sectoring and growth heterogeneity via high within-colony color variance.

Cross-plate comparison of colony pigmentation using perceptually uniform Lab distances.

Consider Also:

MeasureIntensity for grayscale-only brightness and variability statistics.

MeasureColorComposition for proportion-based color classification of colony pixels.

MeasureTexture for surface-roughness features that complement color metrics.

See Also:
Tutorial 7: Measuring and Exporting for a walkthrough of measuring and exporting colony data. Measurement Metrics and Their Biological Meaning for interpreting color metrics in a biological context.

Category: **ColorXYZ**#
Name	Description
`CieXMin`	The minimum X value of the object in CIE XYZ color space
`CieXQ1`	The lower quartile (Q1) X value of the object in CIE XYZ color space
`CieXMean`	The mean X value of the object in CIE XYZ color space
`CieXMedian`	The median X value of the object in CIE XYZ color space
`CieXQ3`	The upper quartile (Q3) X value of the object in CIE XYZ color space
`CieXMax`	The maximum X value of the object in CIE XYZ color space
`CieXStdDev`	The standard deviation of the X value of the object in CIE XYZ color space
`CieXCoeffVar`	The coefficient of variation of the X value of the object in CIE XYZ color space
`CieYMin`	The minimum Y value of the object in CIE XYZ color space
`CieYQ1`	The lower quartile (Q1) Y value of the object in CIE XYZ color space
`CieYMean`	The mean Y value of the object in CIE XYZ color space
`CieYMedian`	The median Y value of the object in CIE XYZ color space
`CieYQ3`	The upper quartile (Q3) Y value of the object in CIE XYZ color space
`CieYMax`	The maximum Y value of the object in CIE XYZ color space
`CieYStdDev`	The standard deviation of the Y value of the object in CIE XYZ color space
`CieYCoeffVar`	The coefficient of variation of the Y value of the object in CIE XYZ color space
`CieZMin`	The minimum Z value of the object in CIE XYZ color space
`CieZQ1`	The lower quartile (Q1) Z value of the object in CIE XYZ color space
`CieZMean`	The mean Z value of the object in CIE XYZ color space
`CieZMedian`	The median Z value of the object in CIE XYZ color space
`CieZQ3`	The upper quartile (Q3) Z value of the object in CIE XYZ color space
`CieZMax`	The maximum Z value of the object in CIE XYZ color space
`CieZStdDev`	The standard deviation of the Z value of the object in CIE XYZ color space
`CieZCoeffVar`	The coefficient of variation of the Z value of the object in CIE XYZ color space

Category: **Colorxy**#
Name	Description
`xMin`	The minimum chromaticity x coordinate of the object
`xQ1`	The lower quartile (Q1) chromaticity x coordinate of the object
`xMean`	The mean chromaticity x coordinate of the object
`xMedian`	The median chromaticity x coordinate of the object
`xQ3`	The upper quartile (Q3) chromaticity x coordinate of the object
`xMax`	The maximum chromaticity x coordinate of the object
`xStdDev`	The standard deviation of the chromaticity x coordinate of the object
`xCoeffVar`	The coefficient of variation of the chromaticity x coordinate of the object
`yMin`	The minimum chromaticity y coordinate of the object
`yQ1`	The lower quartile (Q1) chromaticity y coordinate of the object
`yMean`	The mean chromaticity y coordinate of the object
`yMedian`	The median chromaticity y coordinate of the object
`yQ3`	The upper quartile (Q3) chromaticity y coordinate of the object
`yMax`	The maximum chromaticity y coordinate of the object
`yStdDev`	The standard deviation of the chromaticity y coordinate of the object
`yCoeffVar`	The coefficient of variation of the chromaticity y coordinate of the object

Category: **ColorLab**#
Name	Description
`L*Min`	The minimum L* value of the object
`L*Q1`	The lower quartile (Q1) L* value of the object
`L*Mean`	The mean L* value of the object
`L*Median`	The median L* value of the object
`L*Q3`	The upper quartile (Q3) L* value of the object
`L*Max`	The maximum L* value of the object
`L*StdDev`	The standard deviation of the L* value of the object
`L*CoeffVar`	The coefficient of variation of the L* value of the object
`a*Min`	The minimum a* value of the object
`a*Q1`	The lower quartile (Q1) a* value of the object
`a*Mean`	The mean a* value of the object
`a*Median`	The median a* value of the object
`a*Q3`	The upper quartile (Q3) a* value of the object
`a*Max`	The maximum a* value of the object
`a*StdDev`	The standard deviation of the a* value of the object
`a*CoeffVar`	The coefficient of variation of the a* value of the object
`b*Min`	The minimum b* value of the object
`b*Q1`	The lower quartile (Q1) b* value of the object
`b*Mean`	The mean b* value of the object
`b*Median`	The median b* value of the object
`b*Q3`	The upper quartile (Q3) b* value of the object
`b*Max`	The maximum b* value of the object
`b*StdDev`	The standard deviation of the b* value of the object
`b*CoeffVar`	The coefficient of variation of the b* value of the object
`ChromaEstimatedMean`	The mean chroma estimation of the object calculated using \(\(sqrt(a^{}_{mean}^2 + b^{}_{mean})^2}\)
`ChromaEstimatedMedian`	The median chroma estimation of the object using \(\sqrt({a_{median}^2 + b_{median})^2}\)

Category: **ColorHSV**#
Name	Description
`HueMin`	The minimum hue of the object
`HueQ1`	The lower quartile (Q1) hue of the object
`HueMean`	The mean hue of the object
`HueMedian`	The median hue of the object
`HueQ3`	The upper quartile (Q3) hue of the object
`HueMax`	The maximum hue of the object
`HueStdDev`	The standard deviation of the hue of the object
`HueCoeffVar`	The coefficient of variation of the hue of the object
`SaturationMin`	The minimum saturation of the object
`SaturationQ1`	The lower quartile (Q1) saturation of the object
`SaturationMean`	The mean saturation of the object
`SaturationMedian`	The median saturation of the object
`SaturationQ3`	The upper quartile (Q3) saturation of the object
`SaturationMax`	The maximum saturation of the object
`SaturationStdDev`	The standard deviation of the saturation of the object
`SaturationCoeffVar`	The coefficient of variation of the saturation of the object
`BrightnessMin`	The minimum brightness of the object
`BrightnessQ1`	The lower quartile (Q1) brightness of the object
`BrightnessMean`	The mean brightness of the object
`BrightnessMedian`	The median brightness of the object
`BrightnessQ3`	The upper quartile (Q3) brightness of the object
`BrightnessMax`	The maximum brightness of the object
`BrightnessStdDev`	The standard deviation of the brightness of the object
`BrightnessCoeffVar`	The coefficient of variation of the brightness of the object

Methods

`__init__`
`measure`	Execute the measurement operation on a detected-object image.

Parameters:

white_chroma_max (float)
chroma_min (float)
include_XYZ (bool)

__del__(): Automatically stop tracemalloc when the object is deleted.

measure(image, include_meta=False)

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):

Pass your processed Image (with detected objects) to measure()
The method calls your subclass’s _operate() implementation
Results are validated and returned as a pandas DataFrame
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', ...]

phenotypic.measure.MeasureColor#

This Page