phenotypic.grid.AutoGridFinder#

class phenotypic.grid.AutoGridFinder(nrows: int = 8, ncols: int = 12, residual_fraction: float = 0.25, *, tol: float | None = None, max_iter: int | None = None)[source]

Bases: GridFinder

Automatically determines grid row and column edges from detected object centers using a deterministic robust-fit algorithm.

Unlike histogram or optimizer-based approaches, this class fits a regular grid model directly to the per-object distance-transform maximum centers (deepest interior point of each object’s mask). These centers are anchored in the dense colony body and are unaffected by thin filamentous extensions (e.g., fungal hyphae) that would otherwise pull intensity-weighted centroids off-body and bias the grid fit. Outlier rejection further protects against atypical objects pulling boundaries away from the true positions.

Args:
nrows: Number of rows in the grid (default 8 for 96-well plates). ncols: Number of columns in the grid (default 12 for 96-well plates). residual_fraction: Outlier threshold as a fraction of pitch. Centers

whose fit residual exceeds pitch * residual_fraction are excluded from the refined fit (default 0.25).

tol: Deprecated. Accepted for backward compatibility but ignored. max_iter: Deprecated. Accepted for backward compatibility but ignored.

Category: **GRID**#
Name	Description
`RowNum`	The row idx of the object
`RowIntervalStart`	The start of the row interval of the object
`RowIntervalEnd`	The end of the row interval of the object
`ColNum`	The column idx of the object
`ColIntervalStart`	The start of the column interval of the object
`ColIntervalEnd`	The end of the column interval of the object
`RowMajorIdx`	The row-major index of the object. Row major is the standard in most programming and data science array libraries. Used for indexing into 2D arrays.
`ColMajorIdx`	The col-major index of the object in an array. Lab automation logic uses column-major (column-wise) indexing for well plate operations because 96-well plates are physically arranged with 8 rows (labeled A-H) and 12 columns (numbered 1-12), and this layout maps directly to how multichannel pipettes operate.

Methods

`__init__`
`get_col_edges`	Return column edge coordinates for image.
`get_row_edges`	Return row edge coordinates for image.
`inspect`	Interactive diagnostic dashboard for grid fitting.
`measure`	Compute grid edges and assign each detected object to a grid cell.

Parameters:

nrows (int)
ncols (int)
residual_fraction (float)
tol (float | None)
max_iter (int | None)

get_row_edges(image: Image) → np.ndarray[source]

Return row edge coordinates for image.

Parameters:: image (Image) – Image with detected objects (image.objects.info()).
Returns:: Integer array of length nrows + 1.
Return type:: np.ndarray

get_col_edges(image: Image) → np.ndarray[source]

Return column edge coordinates for image.

Parameters:: image (Image) – Image with detected objects (image.objects.info()).
Returns:: Integer array of length ncols + 1.
Return type:: np.ndarray

inspect(image: Image, show_progress: bool = True)[source]

Interactive diagnostic dashboard for grid fitting.

Profiles the grid-fitting pipeline and displays timing breakdown, object size distribution, centroid scatter with grid overlay, and summary statistics. Useful for identifying bottlenecks when grid.info() is slow (e.g., with filamentous fungi images).

Uses an ipywidgets progress bar in Jupyter, tqdm otherwise.

Parameters:

image (Image) – Image with detected objects (must have objmap).
show_progress (bool) – Whether to display a progress bar during profiling. Defaults to True.

Returns:

Panel Column layout with 4 diagnostic panels.

Examples

>>> from phenotypic.data import load_synth_yeast_plate
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.grid import AutoGridFinder
>>> image = load_synth_yeast_plate()
>>> image = OtsuDetector().apply(image)
>>> finder = AutoGridFinder(nrows=8, ncols=12)
>>> dashboard = finder.inspect(image)

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

measure(image)

Compute grid edges and assign each detected object to a grid cell.

Parameters:: image – Image with detected objects.
Returns:: DataFrame with grid assignments (ROW_NUM, COL_NUM, ROW_MAJOR_IDX).

phenotypic.grid.AutoGridFinder#

This Page