phenotypic.measure.MeasureColor

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

Bases: MeasureFeatures

Measure color characteristics of colonies across multiple perceptual color spaces.

This class extracts quantitative color statistics from segmented colonies using CIE XYZ, chromaticity (xy), CIE Lab (perceptually uniform), and HSV (hue-saturation-value) color spaces. For each color space, it computes intensity-independent statistical features (min, Q1, mean, median, Q3, max, standard deviation, coefficient of variation) per colony, plus chroma estimates in Lab space.

Intuition: Colony color provides phenotypic information about pigmentation, sporulation, metabolic products, and stress responses. Measuring color in multiple spaces captures different aspects: XYZ and xy are standardized for illuminant-independent comparisons, Lab is perceptually uniform (equal Euclidean distances reflect equal perceived color differences), and HSV separates hue (pigment type) from saturation and brightness. Colony-level color variation (e.g., std dev) indicates uneven growth, zonation, or heterogeneous populations.

Use cases (agar plates): - Distinguish pigmented colonies (e.g., red/yellow carotenoid-producing bacteria, dark melanin)

from colorless ones; stratify phenotypes by pigmentation profile.

• Detect sectoring and growth heterogeneity via high color variance within single colonies.

• Use chromaticity (xy) or hue to identify mixed cultures or secondary growth on a plate.

• Enable image-based selection of colonies with specific pigmentation traits (e.g., high-chroma red vs pale).

• Assess whether color measurements cluster by genotype or growth condition for cross-plate comparisons.

Caveats: - Color measurements are highly sensitive to illumination, camera white balance, and exposure settings;

normalize and calibrate your imaging setup before comparing colors across plates or experiments.

• Lab and HSV assume RGB input is correctly gamma-corrected and linearized; use image.gray or image.enh_gray if raw RGB is uncalibrated.

• High saturation and brightness variance within a colony can indicate shadow regions, uneven lighting, or non-uniform mycelial depth; interpret texture variance alongside color variance.

• Chroma estimates use simplified arithmetic; for critical applications, use reference color charts or spectrophotometry to validate color classifications.

• XYZ inclusion is optional and slow; enable only if standardized color space analysis is essential.

Args:

white_chroma_max (float, optional): Chroma threshold below which a colony is classified as

“white” (achromatic). Used to filter Lab chroma calculations. Defaults to 4.0.

chroma_min (float, optional): Minimum chroma value to retain in analysis; colonies below this

are sometimes treated as colorless. Defaults to 8.0.

include_XYZ (bool, optional): Whether to compute CIE XYZ measurements (slower, less common).

Defaults to False.

Returns:

pd.DataFrame: Object-level color statistics with columns organized by color space:

• ColorXYZ: X, Y, Z tristimulus values (if include_XYZ=True).

• Colorxy: Chromaticity coordinates x, y (perceptual color without brightness).

• ColorLab: L* (lightness), a* (green-red), b* (blue-yellow), and chroma estimates.

• ColorHSV: Hue (angle, color identity), Saturation (intensity of color), Brightness (luminosity).

For each channel: Min, Q1, Mean, Median, Q3, Max, StdDev, CoeffVar.

Examples:

Measure colony color to detect pigmented mutants

from phenotypic import Image
from phenotypic.detect import OtsuDetector
from phenotypic.measure import MeasureColor

# Load image of colonies (may include pigmented and non-pigmented strains)
image = Image.from_image_path("mixed_pigment_plate.jpg")
detector = OtsuDetector()
image = detector.operate(image)

# Measure color
measurer = MeasureColor(include_XYZ=False)
colors = measurer.operate(image)

# Identify pigmented colonies by hue and saturation
pigmented = colors[colors['ColorHSV_SaturationMean'] > 15]
print(f"Found {len(pigmented)} pigmented colonies")

Use Lab color space for perceptually uniform analysis

# Measure using Lab space (perceptually uniform)
measurer = MeasureColor()
colors = measurer.operate(image)

# Chroma estimates reflect perceived "colorfulness"
bright_red = colors[
    (colors['ColorLab_L*Mean'] > 50) &
    (colors['ColorLab_ChromaEstimatedMean'] > 20)
]
print(f"Bright red colonies: {len(bright_red)}")

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

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', ...]