phenotypic.measure.MeasureShape#

class phenotypic.measure.MeasureShape(*args, **kwargs)[source]

Bases: MeasureFeatures

Measure comprehensive morphological characteristics of detected colonies.

Extract geometric metrics from each colony shape: area, perimeter, circularity, convex hull properties, width-based measures, Feret diameters, eccentricity, and best-fit ellipse parameters. The output DataFrame provides a full morphological profile for phenotypic classification and growth-pattern analysis.

Returns:
pd.DataFrame: Object-level morphological measurements with columns:

Label, Area, Perimeter, Circularity, Compactness, ConvexArea, Solidity, Extent, BboxArea.

MeanRadius, MedianRadius, MaxRadius (distance-transform based).

MinFeretDiameter, MaxFeretDiameter (caliper diameters).

MajorAxisLength, MinorAxisLength, Eccentricity, Orientation.

Best For:

Distinguishing colony morphotypes (smooth circular wild-type vs wrinkled, branching, or invasive mutants).

Assessing growth symmetry and directionality via eccentricity and orientation.

Detecting invasive or spreading growth through low solidity values.

Morphological clustering for automated strain identification.

Consider Also:

MeasureSize for a lightweight area-only measurement when full morphology is not needed.

MeasureTexture for surface roughness and pattern features that complement shape metrics.

MeasureBounds for bounding box and centroid data without shape statistics.

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

Category: **SHAPE**#
Name	Description
`Area`	Total number of pixels occupied by the microbial colony. Represents colony biomass and growth extent on agar plates. Larger areas typically indicate more robust growth or longer incubation times.
`Perimeter`	Total length of the colony’s outer boundary in pixels. Measures colony edge complexity and surface irregularity. Smooth, circular colonies have shorter perimeters relative to their area compared to irregular or filamentous colonies.
`Circularity`	Calculated as \(\frac{4\pi*\text{Area}}{\text{Perimeter}^2}\). Measures how closely a colony approximates a perfect circle (value = 1). Values < 1 indicate irregular colony morphology, which may result from genetic mutations, environmental stress, or mixed microbial populations on agar plates.
`ConvexArea`	Area of the smallest convex polygon that completely contains the colony. Represents the colony’s “filled-in” appearance if all indentations and holes were removed. Useful for detecting colony spreading patterns or invasive growth characteristics.
`MedianRadius`	Median distance from colony center to edge across all directions. Provides a robust measure of typical colony size that is less sensitive to outliers than mean width. Particularly useful for colonies with uneven growth or sectoring.
`MeanRadius`	Average distance from colony center to edge across all directions. Represents overall colony expansion rate. In arrayed growth assays, this correlates with microbial fitness and growth kinetics under controlled conditions.
`MaxRadius`	Maximum distance from colony center to edge across all directions. Represents the furthest extent of colony growth from its center. In arrayed microbial assays, this measurement helps identify asymmetric growth patterns or colonies extending toward neighboring positions.
`MinFeretDiameter`	Minimum caliper diameter - the shortest distance between two parallel tangent lines touching opposite sides of the colony. Represents the narrowest dimension of the colony regardless of orientation. Useful for detecting elongated or irregular colony morphologies and measuring colony width.
`MaxFeretDiameter`	Maximum caliper diameter - the longest distance between two parallel tangent lines touching opposite sides of the colony. Represents the maximum dimension of the colony regardless of orientation. Often exceeds major axis length for irregular shapes and helps quantify maximum colony extent.
`Eccentricity`	Measure of colony elongation, ranging from 0 (perfect circle) to 1 (highly elongated). Values near 0 indicate compact, radially symmetric growth typical of healthy bacterial colonies, while higher values may suggest directional growth, motility, or environmental gradients on the agar surface.
`Solidity`	Ratio of actual colony area to its convex hull area (Area/ConvexArea). Values near 1 indicate compact, solid colonies with minimal indentations. Lower values (< 0.9) may indicate invasive growth, colony spreading, or the presence of clearing zones around colonies.
`Extent`	Ratio of colony area to its bounding box area (ObjectArea/BboxArea). Measures how efficiently the colony fills its allocated space. Compact colonies have higher extent values, while spread-out or irregular colonies have lower values.
`BboxArea`	Area of the smallest rectangle that completely contains the colony. Represents the total spatial shape of the colony including any empty space. In high-throughput assays, this helps assess colony positioning and potential interference with neighboring colonies.
`MajorAxisLength`	Length of the longest axis of the ellipse that best fits the colony shape. Represents the maximum colony dimension. In arrayed microbial growth, this measurement helps identify colonies that have grown beyond their intended grid positions.
`MinorAxisLength`	Length of the shortest axis of the ellipse that best fits the colony shape. Represents the minimum colony dimension. Together with major axis length, this helps characterize colony aspect ratio and growth anisotropy.
`Compactness`	Calculated as \(\frac{\text{Perimeter}^2}{4\pi*\text{Area}}\). Inverse of circularity (ranges from 1 for perfect circles to higher values for irregular shapes). Measures colony shape complexity - compact, circular colonies have values near 1, while irregular or filamentous colonies have much higher values.
`Orientation`	Angle (in radians) between the colony’s major axis and the horizontal axis. Measures colony alignment and growth directionality. Random orientations are typical for most bacterial colonies, while consistent orientations may indicate environmental gradients or mechanical stresses during plating.

Methods

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

__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.MeasureShape#

This Page