phenotypic.measure.MeasureSize#

class phenotypic.measure.MeasureSize(*, angular_bins: Annotated[int, Ge(ge=8), Le(le=3600)] = 360, trim_proportion: Annotated[float, Ge(ge=0.0), Lt(lt=0.5)] = 0.2, plateau_tolerance: Annotated[float, Gt(gt=0.0), Lt(lt=1.0)] = 0.01)[source]#

Bases: MeasureFeatures

Measure the key size magnitudes of each detected colony.

The single source of colony size: area, integrated intensity, perimeter, convex-hull and bounding-box areas, best-fit-ellipse axis lengths, the Feret (caliper) diameters, the inscribed radius, and four radii (median, mean, robust mean and maximum) measured from one center, the centroid of the distance-transform peak. These are the starting measurements for growth and fitness comparisons; see the SIZE table below for what each column means.

The four radii come from the colony’s radial signature: the distance from the center to the boundary, sampled in angular_bins equal directions. Sampling by angle rather than along the boundary gives a runner or spur only its true angular width, so the trimmed RobustMeanRadius stays on the compact body while MeanRadius and MaxRadius show the reach.

Args:
angular_bins: Number of equal angular directions sampled. A

protrusion narrower than one bin still fills a whole bin, so more bins weight a thin runner closer to its true angular width. The outline of a colony of radius R has only about 8R vertices, so on a small colony extra bins are left empty and interpolated.

trim_proportion: Fraction trimmed from each end of the radial

signature for RobustMeanRadius. It tolerates a runner or spur covering up to this fraction of all directions; 0 makes RobustMeanRadius equal MeanRadius.

plateau_tolerance: Relative tolerance defining the distance-transform

peak plateau whose centroid is the colony center. The default (1%) merges the exact ties that integer pixel geometry produces.

Returns:

pd.DataFrame: One row per colony with Object_Label and every Size_* column.

Best For:
  • Growth and fitness comparisons across strains and conditions (area and the radius family).

  • Separating compact growth from runners or spreading (MaxRadius against RobustMeanRadius).

  • Filtering debris or aborted growth by minimum size before downstream measurement.

Consider Also:
See Also:

Tutorial 7: Measuring and Exporting for a walkthrough of measuring and exporting colony data. Measurement Metrics and Their Biological Meaning for interpreting size metrics in a biological context.

Changed in version 0.20.0: Colony size magnitudes moved from SHAPE to SIZE: MeasureSize is now their only source, and MeasureShape emits form descriptors only. The radius columns were rebuilt so each name matches its value. Retired columns are not aliased, and stores written by earlier versions keep their old column names. A run started before 0.20.0 must be re-run with --overwrite, not resumed. Resuming reuses the images it already finished, with their old column names.

Retired column

Successor

Shape_Area

Size_Area

Shape_Perimeter

Size_Perimeter

Shape_ConvexArea

Size_ConvexArea

Shape_BboxArea

Size_BboxArea

Shape_MajorAxisLength

Size_MajorAxisLength

Shape_MinorAxisLength

Size_MinorAxisLength

Shape_MinFeretDiameter

Size_MinFeretDiameter

Shape_MaxFeretDiameter

Size_MaxFeretDiameter

Shape_MaxRadius

Size_InscribedRadius

Shape_MeanRadius

Shape_MeanBoundaryDist

Shape_MedianRadius

Shape_MedianBoundaryDist

New columns: Size_MedianRadius, Size_MeanRadius, Size_RobustMeanRadius and Size_MaxRadius, all measured from one center, the centroid of the distance-transform peak.

Same name, different value: Size_MedianRadius, Size_MeanRadius and Size_MaxRadius are not the retired Shape_MedianRadius, Shape_MeanRadius and Shape_MaxRadius. Compare old data against the successor in the table above (identical except for colonies touching another colony or the image border, which now measure to that edge), never against the same-named Size_ column. Model outputs are named by the stripped label, so <Model>_MaxRadius_*, <Model>_MeanRadius_* and <Model>_MedianRadius_* fitted before and after 0.20.0 share a name but not a meaning.

Metric family: Size#

Name

Description

Type

Categories

Biology

Image

Area

Total number of pixels occupied by the microbial colony. Represents colony biomass and growth extent on agar plates. Larger areas typically indicate more robust growth or longer incubation times.

Tier 1 · Direct phenotype

Starting Metrics

Projected 2D footprint of the colony in pixels — a common proxy for colony size and overall growth in arrayed plate assays. With matched imaging and incubation, larger area generally reflects greater proliferation or spreading; it captures only the 2D footprint, not colony height or cell density.

../../_images/area.png

IntegratedIntensity

The sum of the object’s grayscale pixels. Calculated as \(\sum{\text{pixel values}} \times \text{area}\).

Tier 1 · Direct phenotype

Starting Metrics

Perimeter

Total length of the colony’s outer boundary in pixels. Measures colony edge complexity and surface irregularity. Smooth, circular colonies have shorter perimeters relative to their area compared to irregular or filamentous colonies.

Tier 1 · Direct phenotype

Starting Metrics

ConvexArea

Area of the smallest convex polygon that completely contains the colony, computed from the convex hull of its pixel centers. Represents the colony’s “filled-in” appearance if all indentations and holes were removed. Because the hull passes through pixel centers it is slightly smaller than the pixel count of a convex colony. Useful for detecting colony spreading patterns or invasive growth characteristics.

Tier 1 · Direct phenotype

Starting Metrics

BboxArea

Area of the smallest rectangle that completely contains the colony. Represents the total spatial shape of the colony including any empty space. In high-throughput assays, this helps assess colony positioning and potential interference with neighboring colonies.

Tier 1 · Direct phenotype

Starting Metrics

MajorAxisLength

Length of the longest axis of the ellipse that best fits the colony shape. Represents the maximum colony dimension. In arrayed microbial growth, this measurement helps identify colonies that have grown beyond their intended grid positions.

Tier 1 · Direct phenotype

Starting Metrics

MinorAxisLength

Length of the shortest axis of the ellipse that best fits the colony shape. Represents the minimum colony dimension. Together with major axis length, this helps characterize colony aspect ratio and growth anisotropy.

Tier 1 · Direct phenotype

Starting Metrics

MinFeretDiameter

Minimum caliper diameter - the shortest distance between two parallel tangent lines touching opposite sides of the colony. Represents the narrowest dimension of the colony regardless of orientation. Useful for detecting elongated or irregular colony morphologies and measuring colony width.

Tier 1 · Direct phenotype

Starting Metrics

MaxFeretDiameter

Maximum caliper diameter - the longest distance between two parallel tangent lines touching opposite sides of the colony. Represents the maximum dimension of the colony regardless of orientation. Often exceeds major axis length for irregular shapes and helps quantify maximum colony extent.

Tier 1 · Direct phenotype

Starting Metrics

InscribedRadius

Radius of the largest circle that fits entirely inside the colony, equal to the maximum of the colony’s Euclidean distance transform: the distance from the colony’s deepest interior point to its nearest edge. For an ideal disk it equals the disk radius. It reflects the colony’s narrowest dimension, not its overall extent: an elongated colony reports half its width whatever its length (a 100 x 20 pixel colony reports 10), and a runner or spur leaves it unchanged. Use MaxRadius for overall extent. The image border counts as an edge.

Tier 1 · Direct phenotype

Starting Metrics

MedianRadius

Median distance from the colony center to its boundary over the radial signature: the boundary distance sampled in equal angular directions (360 by default), keeping the outermost boundary crossing in each. The outer outline of every piece of the colony is sampled and holes are ignored, so a colony made of several pieces (a runner joined only at a corner, or fragments merged into one colony) is measured whole, and MaxRadius reaches its farthest piece. The center is the centroid of the distance-transform peak plateau; it lies inside compact colonies, but for a ring-shaped colony it can fall in the central hole. For an ideal disk it equals the disk radius; for an ideal 100 x 20 pixel rectangle it is 14.1 pixels. This is not the value the retired Shape_MedianRadius carried (a median distance to the nearest edge, now Shape_MedianBoundaryDist).

Tier 1 · Direct phenotype

Starting Metrics

MeanRadius

Mean distance from the colony center to its boundary over the radial signature (see MedianRadius for the center and sampling). For an ideal disk it equals the disk radius; for an ideal 100 x 20 pixel rectangle it is 21.0 pixels. A runner or spur pulls it upward in proportion to its angular width; use RobustMeanRadius for the compact body. This is not the value the retired Shape_MeanRadius carried (a mean distance to the nearest edge, now Shape_MeanBoundaryDist).

Tier 1 · Direct phenotype

Starting Metrics

RobustMeanRadius

Symmetrically trimmed mean (20% from each end by default) of the radial signature (see MedianRadius). Because the signature is sampled by angle, a narrow runner contributes only its angular width and is trimmed away, so this estimates the typical radius of the colony’s compact body. The trim treats genuine elongation the same way: an ideal 100 x 20 pixel rectangle gives 16.2 pixels against a MeanRadius of 21.0 pixels. For an ideal disk it equals the disk radius.

Tier 1 · Direct phenotype

Starting Metrics

MaxRadius

Largest distance from the colony center to its boundary over the radial signature (see MedianRadius): the colony’s furthest reach. For an ideal disk it equals the disk radius; for an ideal 100 x 20 pixel rectangle it is 50.9 pixels. A MaxRadius far above RobustMeanRadius indicates a protrusion, spur, or runner. This is not the value the retired Shape_MaxRadius carried (the inscribed radius, now Size_InscribedRadius).

Tier 1 · Direct phenotype

Starting Metrics

Methods

__init__

Create a new model by parsing and validating input data from keyword arguments.

construct

copy

Returns a copy of the model.

dict

from_json

Reconstruct an operation from JSON written by to_json().

from_orm

get_measurement_infoclasses

Return the measurement schemas active for this operation.

json

measure

Execute the measurement operation on a detected-object image.

model_construct

Creates a new instance of the Model class with validated data.

model_copy

!!! abstract "Usage Documentation"

model_dump

!!! abstract "Usage Documentation"

model_dump_json

!!! abstract "Usage Documentation"

model_json_schema

Generates a JSON schema for a model class.

model_parametrized_name

Compute the class name for parametrizations of generic classes.

model_post_init

Initialize logging and memory tracking after model construction.

model_rebuild

Try to rebuild the pydantic-core schema for the model.

model_validate

Validate a pydantic model instance.

model_validate_json

!!! abstract "Usage Documentation"

model_validate_strings

Validate the given object with string data against the Pydantic model.

output_header

Return the column header measure() writes for member.

output_header_placeholders

Define the placeholders in this operation's output_header() patterns.

parse_file

parse_obj

parse_raw

preflight_requirements

What this operation needs from the run that executes it.

schema

schema_json

to_json

Serialize this operation to JSON.

update_forward_refs

validate

Attributes

model_computed_fields

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_extra

Get extra fields set during validation.

model_fields

model_fields_set

Returns the set of fields that have been explicitly set on this model instance.

angular_bins

trim_proportion

plateau_tolerance

Parameters:
angular_bins: int#
trim_proportion: float#
plateau_tolerance: float#
__copy__() → Self#

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self#

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()#

Automatically stop tracemalloc when the object is deleted.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue#

Hook into generating the model’s JSON schema.

Parameters:
  • core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

  • handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

__init__(**data: Any) → None#

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]#

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]#

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:
Return type:

Generator[Any]

classmethod __pydantic_init_subclass__(**kwargs: Any) → None#

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None#

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

__repr_name__() → str#

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str#

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult#

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self#
Parameters:
Return type:

Self

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self#

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:
  • include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

  • exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

  • update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

  • deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]#
Parameters:
Return type:

Dict[str, Any]

classmethod from_json(json_data: str | Path | dict) → BaseOperation#

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:
  • AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

  • TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'
classmethod from_orm(obj: Any) → Self#
Parameters:

obj (Any)

Return type:

Self

get_measurement_infoclasses() → tuple[type[MeasurementInfo], ...]#

Return the measurement schemas active for this operation.

The default implementation discovers the singular _measurement_infoclass and plural _measurement_infoclasses declarations used by measurement operations. Subclasses only need to override this method when operation parameters enable or disable individual schemas.

Returns:

Ordered, deduplicated measurement schema classes emitted by this operation instance.

Return type:

tuple[type[MeasurementInfo], …]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str#
Parameters:
Return type:

str

measure(image, include_meta=False)#

Execute the measurement operation on a detected-object image.

This is the main public API method for extracting measurements. It handles: input validation, parameter extraction via introspection, calling the subclass-specific _operate() method, optional metadata merging, and exception handling.

How it works (for users):

  1. Pass your processed Image (with detected objects) to measure()

  2. The method calls your subclass’s _operate() implementation

  3. Results are validated and returned as a pandas DataFrame

  4. If include_meta=True, image metadata (filename, grid info) is merged in

How it works (for developers):

When you subclass MeasureFeatures, you only implement _operate(). This measure() method automatically:

  • Calls _operate(), which reads its parameters from self

  • Validates the Image has detected objects (objmap)

  • Wraps exceptions in OperationFailedError with context

  • Merges grid/object metadata if requested

Parameters:
  • image (Image) – A PhenoTypic Image object with detected objects (must have non-empty objmap from a prior detection operation).

  • include_meta (bool, optional) – If True, merge image metadata columns (filename, grid position, etc.) into the results DataFrame. Defaults to False.

Returns:

Measurement results with structure:

  • First column: OBJECT.LABEL (integer IDs from image.objmap[:])

  • Remaining columns: Measurement values (float, int, or string)

  • One row per detected object

If include_meta=True, additional metadata columns are prepended before OBJECT.LABEL (e.g., Filename, GridRow, GridCol).

Return type:

pd.DataFrame

Raises:

OperationFailedError – If _operate() raises any exception, it is caught and re-raised as OperationFailedError with details including the original exception type, message, image name, and operation class. This provides consistent error handling across all measurers.

Notes

  • This method is the main entry point; do not override in subclasses

  • Subclasses implement _operate() only, not this method

  • Automatic memory profiling is available via logging configuration

  • Image must have detected objects (image.objmap should be non-empty)

Examples

Basic measurement extraction:

>>> from phenotypic import Image
>>> from phenotypic.measure import MeasureSize
>>> from phenotypic.detect import OtsuDetector
>>> # Load and detect
>>> image = Image('plate.jpg')
>>> image = OtsuDetector().operate(image)
>>> # Extract measurements
>>> measurer = MeasureSize()
>>> df = measurer.measure(image)
>>> print(df.head())

Include metadata in measurements:

>>> # With image metadata (filename, grid info)
>>> df_with_meta = measurer.measure(image, include_meta=True)
>>> print(df_with_meta.columns)
# Output: ['Filename', 'GridRow', 'GridCol', 'OBJECT.LABEL',
#          'Area', 'IntegratedIntensity', 'Perimeter', ..., 'MaxRadius']
model_computed_fields = {}#
model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self#

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:
  • _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

  • values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self#
!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:
  • update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

  • deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]#
!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:
  • mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

  • include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

  • exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

  • context (Any | None) – Additional context to pass to the serializer.

  • by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

  • exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

  • exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

  • exclude_none (bool) – Whether to exclude fields that have a value of None.

  • exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

  • round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

  • warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

  • fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

  • serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str#
!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:
  • indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

  • ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

  • include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

  • exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

  • context (Any | None) – Additional context to pass to the serializer.

  • by_alias (bool | None) – Whether to serialize using field aliases.

  • exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

  • exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

  • exclude_none (bool) – Whether to exclude fields that have a value of None.

  • exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

  • round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

  • warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

  • fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

  • serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

property model_extra: dict[str, Any] | None#

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'angular_bins': FieldInfo(annotation=int, required=False, default=360, description='Number of equal angular directions sampled. A protrusion narrower than one bin still fills a whole bin, so more bins weight a thin runner closer to its true angular width. The outline of a colony of radius R has only about 8R vertices, so on a small colony extra bins are left empty and interpolated.', metadata=[Ge(ge=8), Le(le=3600)]), 'plateau_tolerance': FieldInfo(annotation=float, required=False, default=0.01, description='Relative tolerance defining the distance-transform peak plateau whose centroid is the colony center. The default (1%) merges the exact ties that integer pixel geometry produces.', metadata=[Gt(gt=0.0), Lt(lt=1.0)]), 'trim_proportion': FieldInfo(annotation=float, required=False, default=0.2, description='Fraction trimmed from each end of the radial signature for ``RobustMeanRadius``. It tolerates a runner or spur covering up to this fraction of all directions; 0 makes ``RobustMeanRadius`` equal ``MeanRadius``.', metadata=[Ge(ge=0.0), Lt(lt=0.5)])}#
property model_fields_set: set[str]#

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]#

Generates a JSON schema for a model class.

Parameters:
  • by_alias (bool) – Whether to use attribute aliases or not.

  • ref_template (str) – The reference template.

  • union_format (Literal['any_of', 'primitive_type_array']) –

    The format to use when combining schemas from unions together. Can be one of:

    keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

  • schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

  • mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str#

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None#

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:
  • __context – Pydantic post-init context (unused).

  • _BaseOperation__context (Any)

Return type:

None

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None#

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:
  • force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

  • raise_errors (bool) – Whether to raise errors, defaults to True.

  • _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

  • _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self#

Validate a pydantic model instance.

Parameters:
  • obj (Any) – The object to validate.

  • strict (bool | None) – Whether to enforce types strictly.

  • extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

  • from_attributes (bool | None) – Whether to extract data from object attributes.

  • context (Any | None) – Additional context to pass to the validator.

  • by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

  • by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self#
!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:
  • json_data (str | bytes | bytearray) – The JSON data to validate.

  • strict (bool | None) – Whether to enforce types strictly.

  • extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

  • context (Any | None) – Extra variables to pass to the validator.

  • by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

  • by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self#

Validate the given object with string data against the Pydantic model.

Parameters:
  • obj (Any) – The object containing string data to validate.

  • strict (bool | None) – Whether to enforce types strictly.

  • extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

  • context (Any | None) – Extra variables to pass to the validator.

  • by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

  • by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod output_header(member: MeasurementInfo, on: str | None = None) → str#

Return the column header measure() writes for member.

Measurement operations write every member under its own value (Size_Area). The method exists so the Measurements reference can ask every table producer the same question; see phenotypic.analysis.abc_.SetAnalyzer.output_header().

Parameters:
  • member (MeasurementInfo) – A member of a schema this operation declares.

  • on (str | None) – Unused; accepted for the shared output_header signature.

Returns:

The emitted header.

Return type:

str

classmethod output_header_placeholders() → dict[str, str]#

Define the placeholders in this operation’s output_header() patterns.

Returns:

Placeholder (<x>) to an RST sentence saying what it stands for, with an example. Empty when every header is fixed.

Return type:

dict[str, str]

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self#
Parameters:
  • path (str | Path)

  • content_type (str | None)

  • encoding (str)

  • proto (DeprecatedParseProtocol | None)

  • allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self#
Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self#
Parameters:
  • b (str | bytes)

  • content_type (str | None)

  • encoding (str)

  • proto (DeprecatedParseProtocol | None)

  • allow_pickle (bool)

Return type:

Self

preflight_requirements() → OperationRequirements#

What this operation needs from the run that executes it.

Read by the CLI’s run preflight, which refuses an incompatible run before any image is processed (spec 2026-09-24-cli-preflight §3). grid_image is derived from the type: every operation that rejects a plain Image derives from GridOperation or GridMeasureFeatures. The rest come from the _requires_* class variables. Override, calling super(), when a requirement depends on a field.

Returns:

The operation’s requirements.

Return type:

OperationRequirements

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]#
Parameters:
  • by_alias (bool)

  • ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str#
Parameters:
  • by_alias (bool)

  • ref_template (str)

  • dumps_kwargs (Any)

Return type:

str

to_json(filepath: str | Path | None = None) → str | None#

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True
classmethod update_forward_refs(**localns: Any) → None#
Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self#
Parameters:

value (Any)

Return type:

Self