phenotypic.abc_.GridMeasureFeatures#

class phenotypic.abc_.GridMeasureFeatures[source]#

Bases: MeasureFeatures, ABC

Extract feature measurements from detected colonies in GridImage objects.

GridMeasureFeatures is a type-safe wrapper around MeasureFeatures that enforces GridImage input type. It is to MeasureFeatures what GridOperation is to ImageOperation: a specialization for grid-aware (arrayed plate) analysis.

Purpose

Use GridMeasureFeatures when implementing measurement operations that extract quantitative metrics from colonies in grid-structured agar plate images. Like MeasureFeatures, it returns pandas DataFrames with one row per detected colony. The only difference is that it requires GridImage input, making explicit that your measurement may leverage grid structure (well positions, row/column layout) if desired.

GridImage vs Image

  • Image: Generic image with optional, unvalidated grid information.

  • GridImage: Specialized Image subclass with validated grid structure (row/column layout, well positions, grid alignment). Suitable for 96-well, 384-well, or other arrayed plate formats.

When to use GridMeasureFeatures vs MeasureFeatures

  • MeasureFeatures: Measurement works equally well on any Image (with or without grid). Examples: colony size, color composition, morphology metrics that are computed globally. Use when grid structure is irrelevant.

  • GridMeasureFeatures: Measurement leverages grid structure or assumes well-level organization. Examples: per-well growth metrics, grid-aligned morphology, measurements that depend on row/column position. Use when grid structure is essential or enhances the measurement.

Implementation Pattern

Inherit from GridMeasureFeatures and implement _operate() as normal:

from phenotypic.abc_ import GridMeasureFeatures
import pandas as pd

class GridMeasureWellOccupancy(GridMeasureFeatures):
    '''Measure fraction of well area occupied by colonies.'''

    def _operate(self, image: GridImage) -> pd.DataFrame:
        # image is guaranteed to be GridImage with grid structure
        # Implement your grid-aware measurement here
        results = pd.DataFrame(...)
        return results

Typical Use Cases

  • Per-well phenotypic analysis where well position matters

  • Grid-based filtering (e.g., “measure only colonies in the center wells”)

  • Well-normalized metrics (e.g., colony area relative to well size)

  • Multi-well experiments where you need to track which well each measurement came from

Notes

  • The measure() method is inherited from MeasureFeatures; the only difference is input type validation.

  • Returns pandas.DataFrame with one row per detected object, first column is OBJECT.LABEL (matching image.objmap labels).

  • GridImage must have valid grid structure set before measuring. Typically set by GridFinder or GridCorrector operations in the pipeline.

  • All helper methods from MeasureFeatures (mean, median, sum, etc.) are available.

Examples

Grid-aware measurement of colony size per well
from phenotypic import GridImage
from phenotypic.abc_ import GridMeasureFeatures
from phenotypic.tools.constants_ import OBJECT
import pandas as pd

class MeasureWellOccupancy(GridMeasureFeatures):
    """Measure total area occupied in each well."""

    def _operate(self, image: GridImage) -> pd.DataFrame:
        # Use grid accessor to calculate per-well metrics
        area = self._calculate_sum(image.objmask[:], image.objmap[:])
        well_info = image.grid.info()  # Get well assignments

        # Combine area with well location
        results = pd.DataFrame({
            'WellArea': area,
        })
        results.insert(0, OBJECT.LABEL, image.objects.labels2series())
        return results

# Usage
from phenotypic import Image
from phenotypic.detect import OtsuDetector

image = Image.from_image_path('plate.jpg')
image = OtsuDetector().operate(image)

grid_image = GridImage(image)
grid_image.detect_grid()  # Establish grid structure

measurer = MeasureWellOccupancy()
df = measurer.measure(grid_image)  # Returns grid-aware measurements

Methods

__init__

measure

Processes an arr image to calculate and organize grid-based boundaries and centroids using coordinates.
measure(image)[source]#

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

__del__()#

Automatically stop tracemalloc when the object is deleted.