phenotypic.grid#

Grid discovery for plated fungal colonies.

Provides tools to define the row/column layout of arrayed plates (e.g., 96- or 384-spot) so downstream detection and measurements align colonies to expected wells. Supports automatic grid inference and manual specification for challenging imaging conditions.

Classes

AutoGridFinder

Automatically adjusts and processes grid configurations for images based on

ManualGridFinder

A GridFinder implementation where users directly specify grid row and column coordinates.
class phenotypic.grid.AutoGridFinder(nrows: int = 8, ncols: int = 12, tol: float = 0.01, max_iter: int | None = None)[source]#

Bases: GridFinder

Automatically adjusts and processes grid configurations for images based on parameters like row and column counts, tolerance, and iteration constraints.

This class extends GridFinder and adds flexibility to define custom grid specifications, compute padding, manage convergence criteria, and optimize grid alignment for image processing tasks.

Attributes:

__iter_limit (float): Internal limit for the maximum number of iterations. nrows (int): Number of rows for the grid structure. ncols (int): Number of columns for the grid structure. tol (float): Tolerance level to assess convergence. max_iter (int): Maximum allowable iterations, capped by the internal limit.

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

SectionNum

The section number of the object. Ordered left to right, top to bottom
Parameters:
__del__()#

Automatically stop tracemalloc when the object is deleted.

__init__(nrows: int = 8, ncols: int = 12, tol: float = 0.01, max_iter: int | None = None)[source]#

Represents a configuration object for iterative computations with constraints on the number of nrows, columns, tolerance, and a maximum number of iterations. This provides a flexible structure enabling adjustments to the computation parameters such as matrix dimensions and convergence criteria.

Parameters:
nrows#

Number of nrows for the computation grid or array.

Type:

int

ncols#

Number of columns for the computation grid or array.

Type:

int

tol#

Tolerance level for the convergence criteria.

Type:

float

max_iter#

Maximum number of allowable iterations. Defaults to the predefined internal convergence limit if not provided.

Type:

int | None

get_col_edges(image: Image)[source]#

This method is to returns the column edges of the grid as numpy rgb. :param image:

Returns:

Column-edges of the grid.

Return type:

np.ndarray

Parameters:

image (Image)

get_row_edges(image: Image)[source]#

Extracts and returns the edges of nrows from the given image.

This method first calculates the optimal row padding for the provided image using an internal utility method and subsequently determines the row edges based on the calculated padding and metadata of the image.

Parameters:

image (Image) – The input image from which the row edges need to be identified.

Returns:

A list representing the edges of the nrows in the image.

Return type:

list

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

class phenotypic.grid.ManualGridFinder(row_edges: numpy.ndarray, col_edges: numpy.ndarray)[source]#

Bases: GridFinder

A GridFinder implementation where users directly specify grid row and column coordinates.

This class allows for complete manual control over grid placement by accepting explicit row and column edge coordinates. No optimization or automatic calculation is performed - the grid is defined exactly as specified by the user.

Parameters:

  • row_edges (np.ndarray)

  • col_edges (np.ndarray)

nrows#

Number of rows in the grid (derived from row_edges).

Type:

int

ncols#

Number of columns in the grid (derived from col_edges).

Type:

int

row_edges#

Array of row edge coordinates defining grid rows.

Type:

np.ndarray

col_edges#

Array of column edge coordinates defining grid columns.

Type:

np.ndarray

Example

Create a 3x4 grid with specific coordinates
>>> # Create a 3x4 grid with specific coordinates
>>> row_edges = np.array([0, 100, 200, 300])  # 3 rows
>>> col_edges = np.array([0, 80, 160, 240, 320])  # 4 columns
>>> finder = ManualGridFinder(row_edges=row_edges, col_edges=col_edges)
>>> grid_info = finder.measure(image)
__del__()#

Automatically stop tracemalloc when the object is deleted.

__init__(row_edges: numpy.ndarray, col_edges: numpy.ndarray)[source]#

Initialize a ManualGridFinder with explicit row and column edge coordinates.

Parameters:

  • row_edges (np.ndarray) – Array of row edge coordinates. Length should be nrows + 1. Example: [0, 100, 200, 300] defines 3 rows.

  • col_edges (np.ndarray) – Array of column edge coordinates. Length should be ncols + 1. Example: [0, 80, 160, 240, 320] defines 4 columns.

Raises:

ValueError – If row_edges or col_edges have fewer than 2 elements.

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

Returns the manually specified column edges.

Parameters:

image (Image) – The image (not used, but required by interface).

Returns:

Array of column edge coordinates.

Return type:

np.ndarray

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

Returns the manually specified row edges.

Parameters:

image (Image) – The image (not used, but required by interface).

Returns:

Array of row edge coordinates.

Return type:

np.ndarray

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