Source code for phenotypic.measure._measure_grid_spread
from __future__ import annotations
from typing import ClassVar, TYPE_CHECKING
if TYPE_CHECKING:
from phenotypic._core._grid_image import GridImage
from phenotypic.abc_ import GridMeasureFeatures
from phenotypic.schema import GRID_SPREAD
import pandas as pd
import numpy as np
from scipy.spatial.distance import pdist
from phenotypic.schema import BBOX, GRID, OBJECT
[docs]
class MeasureGridSpread(GridMeasureFeatures):
"""Quantify within-well colony dispersion using pairwise centroid distances.
Compute the sum of squared pairwise Euclidean distances between all
colony centroids in each grid section. High values indicate multiple
dispersed objects within a single well -- a sign of over-segmentation,
fragmented growth, or invasive spreading.
Returns:
pd.DataFrame: One row per object, keyed by ``Object_Label``. Each
object carries its grid section's spread and object count, so every
object in a section shares the same values.
Best For:
- Detecting over-segmented wells where multiple objects were
found instead of a single cohesive colony.
- Identifying invasive or spreading growth that extends beyond
the designated grid position.
- Flagging wells with questionable data quality for manual
review or exclusion from downstream analysis.
Consider Also:
- :class:`MeasureNeighborDist` for between-well neighbor
distances rather than within-well dispersion.
- :class:`MeasureGridLinRegStats` for positional accuracy
metrics based on linear regression.
- :class:`MeasureBounds` for raw centroid positions per colony.
See Also:
:doc:`/tutorials/notebooks/07_measuring_and_exporting` for a
walkthrough of grid-level measurements.
"""
_measurement_infoclass: ClassVar[type] = GRID_SPREAD
def _operate(self, image: GridImage) -> pd.DataFrame:
grid_info = image.grid.info(include_metadata=False)
section = grid_info.loc[:, str(GRID.ROW_MAJOR_IDX)]
section_spread = {}
for section_idx, section_table in grid_info.groupby(section, observed=True):
centers = section_table.loc[
:, [str(BBOX.CENTER_CC), str(BBOX.CENTER_RR)]
].to_numpy(dtype=float)
# pdist yields each unordered pair once, so distinct pairs at equal
# distances are all counted.
section_spread[section_idx] = float(np.sum(pdist(centers) ** 2))
# Section-level values are broadcast to every object in the section so
# the frame keys on Object_Label like every other measurer.
return pd.DataFrame(
{
OBJECT.LABEL: grid_info.loc[:, OBJECT.LABEL].to_numpy(),
str(GRID_SPREAD.OBJECT_SPREAD): section.map(section_spread).to_numpy(),
str(GRID_SPREAD.OBJECT_COUNT): section.map(section.value_counts()).to_numpy(),
}
)
MeasureGridSpread.__doc__ = GRID_SPREAD.append_rst_to_doc(MeasureGridSpread)