phenotypic.measure.MeasureGridLinRegStats

class phenotypic.measure.MeasureGridLinRegStats(section_num: int | None = None)

Bases: GridMeasureFeatures

Evaluate grid alignment quality for arrayed microbial colonies using linear regression.

This class measures how well detected colonies align to expected grid positions in arrayed phenotyping assays. It computes row-wise and column-wise linear regression fits across the grid, then quantifies each colony’s deviation from the predicted position using residual error.

Intuition: In high-throughput microbial phenotyping, 96-well and 384-well plates have expected regular grid patterns. Deviations indicate off-grid growth, misdetections, plate warping, or imaging artifacts. High residual errors flag problematic detections that may need refinement or filtering before downstream analysis.

Use cases (agar plates): - Identify colonies that grew outside their designated grid position (e.g., spreading into

adjacent wells on a plate).

• Detect systematic alignment issues (e.g., rotation, shear) across the plate to validate grid detection quality.

• Filter or weight colonies by detection confidence based on deviation from expected position (used by refinement operations to select most plausible colony per grid cell).

• Quantify plate warping or uneven agar surface by analyzing residual error patterns across rows/columns.

Caveats: - Regression assumes a linear relationship; severely warped plates may not fit the linear model well. - Residual errors are sensitive to grid detection accuracy; incorrect grid estimates propagate to

inflated residuals for correctly detected colonies.

• Threshold selection for outlier filtering is application-dependent; conservatively use the 95th percentile residual error within a plate for robust quality control.

Args:

section_num (Optional[int], optional): Grid section number to restrict measurements to.

If None, measurements are computed across the entire grid. Defaults to None.

Attributes:

section_num (Optional[int]): Section number for targeted grid region analysis.

Returns:

pd.DataFrame: Measurement results indexed by object label. Includes per-object metrics:

• RowM, RowB: Row regression slope and intercept (1 value per row).

• ColM, ColB: Column regression slope and intercept (1 value per column).

• PredRR, PredCC: Predicted row and column centroids from regression.

• ResidualError: Euclidean distance between actual and predicted centroid.

Examples:

Measure grid alignment for an arrayed plate

from phenotypic import GridImage
from phenotypic.detect import OtsuDetector
from phenotypic.measure import MeasureGridLinRegStats

# Load a plate image with grid information
grid_image = GridImage.from_image_path("plate_96well.jpg", grid_shape=(8, 12))

# Detect colonies
detector = OtsuDetector()
grid_image = detector.operate(grid_image)

# Measure grid alignment quality
measurer = MeasureGridLinRegStats()
results = measurer.operate(grid_image)

# Identify off-grid colonies
outliers = results[results['GridLinReg_ResidualError'] > 10.0]
print(f"Found {len(outliers)} colonies with high misalignment")

Measure alignment within a single section/well

# Measure only colonies in section 5 (useful for troubleshooting
# a specific well or region)
measurer = MeasureGridLinRegStats(section_num=5)
section_results = measurer.operate(grid_image)
# Results contain grid stats and residual errors only for section 5

Category: GRID_LINREG_STATS

Name	Description
RowM	Slope of row-wise linear regression fit across column positions. Measures systematic drift in row alignment. Values near 0 indicate horizontal rows; non-zero values suggest rotational misalignment or systematic row curvature across the plate.
RowB	Intercept of row-wise linear regression fit. Represents the expected row coordinate when column position is 0. Combined with slope, defines the expected row trend line for quality assessment and position prediction.
ColM	Slope of column-wise linear regression fit across row positions. Measures systematic drift in column alignment. Values near 0 indicate vertical columns; non-zero values suggest rotational misalignment or systematic column curvature across the plate.
ColB	Intercept of column-wise linear regression fit. Represents the expected column coordinate when row position is 0. Combined with slope, defines the expected column trend line for quality assessment and position prediction.
PredRR	Predicted row coordinate from column-wise linear regression. Uses the column position and column regression parameters (ColM, ColB) to estimate where the row coordinate should be if the grid were perfectly aligned. Used for calculating residual errors and detecting misaligned colonies.
PredCC	Predicted column coordinate from row-wise linear regression. Uses the row position and row regression parameters (RowM, RowB) to estimate where the column coordinate should be if the grid were perfectly aligned. Used for calculating residual errors and detecting misaligned colonies.
ResidualError	Euclidean distance between the actual colony centroid and the predicted position from linear regression. Quantifies how far each colony deviates from the expected grid pattern. High values indicate misdetections, off-grid growth, or local plate warping. Used by refinement operations to filter outliers and select the most plausible colony per grid cell.

Methods

__init__
measure	Processes an arr image to calculate and organize grid-based boundaries and centroids using coordinates.

Parameters:

section_num (Optional[int])

__del__()

Automatically stop tracemalloc when the object is deleted.

measure(image)

Processes an arr image to calculate and organize grid-based boundaries and centroids using coordinates. This function implements a two-pass approach to refine row and column boundaries with exact precision, ensuring accurate grid labeling and indexing. The function dynamically computes boundary intervals and optimally segments the arr space into grids based on specified nrows and columns.

Parameters:

image (Image) – The arr image to be analyzed and processed.

Returns:

A DataFrame containing the grid results including boundary intervals, grid indices, and section numbers corresponding to the segmented arr image.

Return type:

pd.DataFrame