phenotypic.detect package

Colony/object detectors for agar plate images.

Implements thresholding- and edge-based approaches to turn detection matrix images into binary colony masks, with options suited to faint growth, uneven agar, or dense plates. Includes global histogram methods (Otsu, Li, Yen, Isodata, Triangle, Mean, Minimum, Manual), edge-aware variants (Canny), grid-aware detection (Gitter), and watershed-based segmentation for clustered colonies.

class phenotypic.detect.CannyDetector(*, sigma: Annotated[float, Gt(gt=0.0), TuneSpec(low=0.5, high=3.0, step=None, log=False, categories=None, tunable=True)] = 1.0, low_threshold: Annotated[float, TuneSpec(low=0.05, high=0.2, step=None, log=False, categories=None, tunable=True)] = 0.1, high_threshold: Annotated[float, TuneSpec(low=0.2, high=0.4, step=None, log=False, categories=None, tunable=True)] = 0.2, use_quantiles: bool = True, min_size: Annotated[int, Ge(ge=1), TuneSpec(low=20, high=500, step=None, log=False, categories=None, tunable=True)] = 50, invert_edges: bool = True, connectivity: Annotated[int, Ge(ge=1), Le(le=2), TuneSpec(low=None, high=None, step=None, log=False, categories=1, 2, tunable=True)] = 2)

Bases: ThresholdDetector

Detect colonies by tracing edges and labelling connected regions.

Applies multi-stage Canny edge detection — Gaussian smoothing, gradient estimation, non-maximum suppression, and dual-threshold hysteresis — to produce thin edge pixels, then labels connected components of either the inverted edge map or the edge map itself. This does not explicitly close contours or fill interiors; colony-sized regions are recovered only when edges form useful barriers and size filtering removes background regions. Because detection relies on boundary contrast rather than absolute intensity, it can remain useful on plates with uneven illumination or translucent colonies. For a full comparison of detection strategies, see Detection Strategies Compared.

Best For:

• Well-separated colonies on solid media where colony edges are sharper than the intensity difference relative to background.

• Translucent or lightly pigmented colonies that lack sufficient intensity contrast for threshold-based methods.

• Plates with heterogeneous colony texture or pigmentation that cause intensity-based methods to fragment objects.

• Images with moderate vignetting where edge contrast is preserved even though absolute intensity varies across the plate.

Consider Also:

• OtsuDetector when colonies differ from background primarily in brightness rather than edge contrast.

• WatershedDetector when touching colonies must be separated by region-growing from interior distance-transform seeds.

• HysteresisDetector when dual-threshold intensity segmentation is preferred over edge-based detection.

Parameters:

• sigma (Annotated[float, Gt(gt=0.0), TuneSpec(low=0.5, high=3.0, step=None, log=False, categories=None, tunable=True)]) – Standard deviation of the Gaussian pre-smoothing kernel in pixels. Larger values suppress high-frequency noise but broaden edge profiles and may merge boundaries of closely spaced colonies. Typical range: 0.5–3.0. Default: 1.0. A reasonable starting point for noisy CCD images or plates with fine colony texture is 2.0–3.0.

• low_threshold (Annotated[float, TuneSpec(low=0.05, high=0.2, step=None, log=False, categories=None, tunable=True)]) – Lower hysteresis gate. When use_quantiles is True, interpreted as a fractional rank of gradient magnitudes (0.1 retains edges stronger than 10 % of all measured gradients). When False, an absolute gradient value requiring per-setup calibration. Raise to prune weak noise-driven edge fragments; lower to recover faint boundaries on low-contrast colonies. Typical quantile range: 0.05–0.2. Default: 0.1.

• high_threshold (Annotated[float, TuneSpec(low=0.2, high=0.4, step=None, log=False, categories=None, tunable=True)]) – Upper hysteresis gate that seeds new edge chains. Must exceed low_threshold. A higher value seeds fewer but more confident edge segments; a lower value seeds more chains at the risk of noise-seeded spurious regions. A 2:1 to 3:1 high-to-low ratio is effective for moderately noisy images. Typical quantile range: 0.1–0.4. Default: 0.2.

• use_quantiles (bool) – When True (default), thresholds are interpreted as gradient-magnitude percentile ranks, adapting automatically to image contrast across batches with variable scanner gain or illumination. When False, thresholds are absolute gradient values for tightly controlled imaging conditions. Default: True.

• min_size (Annotated[int, Ge(ge=1), TuneSpec(low=20, high=500, step=None, log=False, categories=None, tunable=True)]) – Minimum connected-region area in pixels. Regions smaller than this are discarded as dust, debris, or condensation droplets after labelling. Typical range: 20–500 px, scaling with image resolution. Default: 50.

• invert_edges (bool) – When True (default), the binary edge map is inverted before labelling so that non-edge regions can become colony objects. Set to False to label the edge pixels themselves, which is useful for inspecting edge closure and gap locations during parameter tuning. Default: True.

• connectivity (Annotated[int, Ge(ge=1), Le(le=2), TuneSpec(low=None, high=None, step=None, log=False, categories=(1, 2), tunable=True)]) – Pixel connectivity for connected-component labelling. 1 for 4-connectivity; 2 for 8-connectivity. Use 2 (default) to bridge single-pixel diagonal gaps in Canny edge contours, preventing spurious region splits at diagonal steps. Default: 2.

Returns:

Input image with objmap set to a labelled colony map where each retained connected region receives a unique integer label, and objmask derived from the non-zero entries of that map.

Return type:

Image

Raises:

ValueError – If high_threshold is less than low_threshold.

References

[1] J. Canny, “A computational approach to edge detection,” IEEE Trans. Pattern Anal. Mach. Intell., vol. 8, no. 6, pp. 679–698, Nov. 1986.

See also

Tutorial 2: Detecting Colonies for a step-by-step tutorial demonstrating colony detection on real plate images. How To: Choose a Detection Algorithm for a guide to selecting the right detector for your plate images. Detection Strategies Compared for an in-depth comparison of all detection strategies and their failure modes.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

connectivity: Annotated[int, TuneSpec(categories=[1, 2])]

high_threshold: Annotated[float, TuneSpec(0.2, 0.4)]

invert_edges: bool

low_threshold: Annotated[float, TuneSpec(0.05, 0.2)]

min_size: Annotated[int, TuneSpec(20, 500)]

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].

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 = {'connectivity': FieldInfo(annotation=int, required=False, default=2, description='Pixel connectivity for connected-component labelling. ``1`` for 4-connectivity; ``2`` for 8-connectivity. Use ``2`` (default) to bridge single-pixel diagonal gaps in Canny edge contours, preventing spurious region splits at diagonal steps.', metadata=[Ge(ge=1), Le(le=2), TuneSpec(low=None, high=None, step=None, log=False, categories=(1, 2), tunable=True)]), 'high_threshold': FieldInfo(annotation=float, required=False, default=0.2, description='Upper hysteresis gate that seeds new edge chains. Must exceed ``low_threshold``. A higher value seeds fewer but more confident edge segments; a lower value seeds more chains at the risk of noise-seeded spurious regions. A 2:1 to 3:1 high-to-low ratio is effective for moderately noisy images. Typical quantile', metadata=[TuneSpec(low=0.2, high=0.4, step=None, log=False, categories=None, tunable=True)]), 'invert_edges': FieldInfo(annotation=bool, required=False, default=True, description='When ``True`` (default), the binary edge map is inverted before labelling so that non-edge regions can become colony objects. Set to ``False`` to label the edge pixels themselves, which is useful for inspecting edge closure and gap locations during parameter tuning. Default: True.'), 'low_threshold': FieldInfo(annotation=float, required=False, default=0.1, description='Lower hysteresis gate. When ``use_quantiles`` is ``True``, interpreted as a fractional rank of gradient magnitudes (0.1 retains edges stronger than 10 % of all measured gradients). When ``False``, an absolute gradient value requiring per-setup calibration. Raise to prune weak noise-driven edge fragments; lower to recover faint boundaries on low-contrast colonies. Typical quantile range: 0.05--0.2. Default: 0.1.', metadata=[TuneSpec(low=0.05, high=0.2, step=None, log=False, categories=None, tunable=True)]), 'min_size': FieldInfo(annotation=int, required=False, default=50, description='Minimum connected-region area in pixels. Regions smaller than this are discarded as dust, debris, or condensation droplets after labelling. Typical range: 20--500 px, scaling with image resolution. Default: 50.', metadata=[Ge(ge=1), TuneSpec(low=20, high=500, step=None, log=False, categories=None, tunable=True)]), 'sigma': FieldInfo(annotation=float, required=False, default=1.0, description='Standard deviation of the Gaussian pre-smoothing kernel in pixels. Larger values suppress high-frequency noise but broaden edge profiles and may merge boundaries of closely spaced colonies. Typical range: 0.5--3.0. Default: 1.0. A reasonable starting point for noisy CCD images or plates with fine colony texture is 2.0--3.0.', metadata=[Gt(gt=0.0), TuneSpec(low=0.5, high=3.0, step=None, log=False, categories=None, tunable=True)]), 'use_quantiles': FieldInfo(annotation=bool, required=False, default=True, description='When ``True`` (default), thresholds are interpreted as gradient-magnitude percentile ranks, adapting automatically to image contrast across batches with variable scanner gain or illumination. When ``False``, thresholds are absolute gradient values for tightly controlled imaging conditions. Default: True.')}

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.

sigma: Annotated[float, TuneSpec(0.5, 3.0)]

use_quantiles: bool

class phenotypic.detect.ChanVeseDetector(*, mu: Annotated[float, TuneSpec(low=0.0, high=1.0, step=None, log=False, categories=None, tunable=True)] = 0.25, lambda1: Annotated[float, TuneSpec(low=0.5, high=2.0, step=None, log=False, categories=None, tunable=True)] = 1.0, lambda2: Annotated[float, TuneSpec(low=0.5, high=2.0, step=None, log=False, categories=None, tunable=True)] = 1.0, max_num_iter: Annotated[int, TuneSpec(low=100, high=1000, step=None, log=False, categories=None, tunable=True)] = 500, tol: Annotated[float, TuneSpec(low=1e-05, high=0.01, step=None, log=True, categories=None, tunable=True)] = 0.001, dt: Annotated[float, TuneSpec(low=0.1, high=1.0, step=None, log=False, categories=None, tunable=True)] = 0.5, init_level_set: str = 'checkerboard', min_size: Annotated[int, TuneSpec(low=10, high=500, step=None, log=True, categories=None, tunable=True)] = 50, connectivity: Annotated[int, Ge(ge=1), Le(le=2), TuneSpec(low=None, high=None, step=None, log=False, categories=1, 2, tunable=True)] = 2)

Bases: ObjectDetector

Detect colonies by evolving a level-set contour that minimises region-intensity variance via the Chan-Vese method.

Partition detect_mat into foreground and background by iterating a level-set that minimises the summed intensity variance inside and outside the detected regions. Because the energy is driven by region statistics rather than edge gradients, colonies with diffuse boundaries, gradual transitions into agar, or heterogeneous surface texture are captured cleanly as smooth, well-regularised outlines. The contour is initialised and evolved until the per-pixel change falls below tol or max_num_iter is reached, after which the binary mask is labelled into individual connected-component colonies.

For a comparison of region-based and edge-based detection strategies, see Detection Strategies Compared.

Best For:

• Mucoid or spreading colonies whose boundaries lack sharp intensity gradients.

• Plates with uneven colony pigmentation or sector-variant morphology that fragments threshold-based masks.

• Low-contrast imaging conditions where colony and agar intensities overlap in the histogram.

• Morphology studies requiring smooth, well-regularised colony outlines rather than jagged threshold masks.

Consider Also:

• OtsuDetector when colonies and background form two distinct histogram peaks and a fast global threshold suffices.

• HysteresisDetector when colony brightness varies but edges remain reasonably sharp.

• CannyDetector when colonies are best delineated by edge contrast rather than interior region homogeneity.

• WatershedDetector when touching, compact colonies must be separated after an initial binary detection.

Parameters:

• mu (Annotated[float, TuneSpec(low=0.0, high=1.0, step=None, log=False, categories=None, tunable=True)]) – Contour-length penalty weight in the Chan-Vese energy functional. Higher values produce shorter, smoother outlines and merge nearby colonies; lower values allow the contour to track fine boundary detail at the cost of noise sensitivity. Typical range: 0–1 (lower for diffuse mucoid edges, higher for noisy plates). Default: 0.25.

• lambda1 (Annotated[float, TuneSpec(low=0.5, high=2.0, step=None, log=False, categories=None, tunable=True)]) – Fidelity weight for intensity deviation inside detected regions. Increasing lambda1 forces the contour to enclose pixels whose intensity matches the estimated colony mean more tightly. Equal weights (lambda1 = lambda2 = 1.0) are the standard default recommended by Chan & Vese (2001); use asymmetric weights when colony and agar intensity distributions differ strongly. Default: 1.0.

• lambda2 (Annotated[float, TuneSpec(low=0.5, high=2.0, step=None, log=False, categories=None, tunable=True)]) – Fidelity weight for intensity deviation outside detected regions (background). Increasing lambda2 relative to lambda1 penalises background heterogeneity more strongly (follows directly from the energy functional); useful when agar is uniform but colony texture is heterogeneous. Default: 1.0.

• max_num_iter (Annotated[int, TuneSpec(low=100, high=1000, step=None, log=False, categories=None, tunable=True)]) – Hard cap on level-set evolution iterations. The algorithm stops early if tol is satisfied. Increase for complex or slowly converging shapes (mucoid, low-contrast); decrease to trade boundary accuracy for speed. Typical range: 100–1000. Default: 500.

• tol (Annotated[float, TuneSpec(low=1e-05, high=0.01, step=None, log=True, categories=None, tunable=True)]) – Early-stopping criterion: per-pixel level-set change normalised by image area. Smaller values give more precise convergence but require more iterations; values below the noise floor exhaust max_num_iter without improving results. Typical range: 1e-5–1e-2. Default: 1e-3.

• dt (Annotated[float, TuneSpec(low=0.1, high=1.0, step=None, log=False, categories=None, tunable=True)]) – Step-size multiplier for each level-set iteration. Larger values converge faster but may lead to convergence problems on complex or low-contrast shapes; keep within 0.1–1.0 on real plate images. Default: 0.5.

• init_level_set (str) – Shape used to initialise the level-set function before evolution. Accepted values: "checkerboard" (sin × sin pattern; fast multi-front convergence, well-suited to arrayed plates with spatially distributed colonies), "disk" (large circle shrinking inward; slower but more likely to detect implicit edges), "small disk" (small expanding circle at the image centre). Default: "checkerboard".

• min_size (Annotated[int, TuneSpec(low=10, high=500, step=None, log=True, categories=None, tunable=True)]) – Minimum connected-component area in pixels. Components smaller than this are discarded after labelling. Increase to remove condensation droplets, debris, or noise fragments; decrease for high-density formats where each colony occupies few pixels. Typical range: 10–500. Default: 50.

• connectivity (Annotated[int, Ge(ge=1), Le(le=2), TuneSpec(low=None, high=None, step=None, log=False, categories=(1, 2), tunable=True)]) – Pixel connectivity for connected-component labelling. 1 uses 4-connectivity (orthogonal neighbours only; keeps colonies that touch only at corners separate); 2 uses 8-connectivity (all neighbours including diagonals; merges corner-touching regions). Default: 2.

Returns:

Input image with objmask set to the binary segmentation mask and objmap set to consecutively labelled connected components.

Return type:

Image

Raises:

ValueError – If init_level_set is not one of the recognised initialisation strings.

References

[1] T. F. Chan and L. A. Vese, “Active contours without edges,” IEEE Trans. Image Process., vol. 10, no. 2, pp. 266–277, Feb. 2001.

[2] P. Getreuer, “Chan-Vese segmentation,” Image Process. On Line, vol. 2, pp. 214–224, 2012.

See also

Tutorial 2: Detecting Colonies

Step-by-step tutorial for basic colony detection on plate images.

How To: Choose a Detection Algorithm

Guide for selecting the right detector for your imaging conditions.

Detection Strategies Compared

In-depth comparison of all detection strategies and their failure modes.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

connectivity: Annotated[int, TuneSpec(categories=[1, 2])]

dt: Annotated[float, TuneSpec(0.1, 1.0)]

init_level_set: str

lambda1: Annotated[float, TuneSpec(0.5, 2.0)]

lambda2: Annotated[float, TuneSpec(0.5, 2.0)]

max_num_iter: Annotated[int, TuneSpec(100, 1000)]

min_size: Annotated[int, TuneSpec(10, 500, log=True)]

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].

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 = {'connectivity': FieldInfo(annotation=int, required=False, default=2, description='Pixel connectivity for connected-component labelling. ``1`` uses 4-connectivity (orthogonal neighbours only; keeps colonies that touch only at corners separate); ``2`` uses 8-connectivity (all neighbours including diagonals; merges corner-touching regions). Default: 2.', metadata=[Ge(ge=1), Le(le=2), TuneSpec(low=None, high=None, step=None, log=False, categories=(1, 2), tunable=True)]), 'dt': FieldInfo(annotation=float, required=False, default=0.5, description='Step-size multiplier for each level-set iteration. Larger values converge faster but may lead to convergence problems on complex or low-contrast shapes; keep within 0.1--1.0 on real plate images.', metadata=[TuneSpec(low=0.1, high=1.0, step=None, log=False, categories=None, tunable=True)]), 'init_level_set': FieldInfo(annotation=str, required=False, default='checkerboard', description='Shape used to initialise the level-set function before evolution. Accepted values: ``"checkerboard"`` (sin × sin pattern; fast multi-front convergence, well-suited to arrayed plates with spatially distributed colonies), ``"disk"`` (large circle shrinking inward; slower but more likely to detect implicit edges), ``"small disk"`` (small expanding circle at the image centre). Default: ``"checkerboard"``.'), 'lambda1': FieldInfo(annotation=float, required=False, default=1.0, description='Fidelity weight for intensity deviation inside detected regions. Increasing ``lambda1`` forces the contour to enclose pixels whose intensity matches the estimated colony mean more tightly. Equal weights (``lambda1`` = ``lambda2`` = 1.0) are the standard default recommended by Chan & Vese (2001); use asymmetric weights when colony and agar intensity distributions differ strongly. Default: 1.0.', metadata=[TuneSpec(low=0.5, high=2.0, step=None, log=False, categories=None, tunable=True)]), 'lambda2': FieldInfo(annotation=float, required=False, default=1.0, description='Fidelity weight for intensity deviation outside detected regions (background). Increasing ``lambda2`` relative to ``lambda1`` penalises background heterogeneity more strongly (follows directly from the energy functional); useful when agar is uniform but colony texture is heterogeneous. Default: 1.0.', metadata=[TuneSpec(low=0.5, high=2.0, step=None, log=False, categories=None, tunable=True)]), 'max_num_iter': FieldInfo(annotation=int, required=False, default=500, description='Hard cap on level-set evolution iterations. The algorithm stops early if ``tol`` is satisfied. Increase for complex or slowly converging shapes (mucoid, low-contrast); decrease to trade boundary accuracy for speed. Typical range: 100--1000. Default: 500.', metadata=[TuneSpec(low=100, high=1000, step=None, log=False, categories=None, tunable=True)]), 'min_size': FieldInfo(annotation=int, required=False, default=50, description='Minimum connected-component area in pixels. Components smaller than this are discarded after labelling. Increase to remove condensation droplets, debris, or noise fragments; decrease for high-density formats where each colony occupies few pixels. Typical range: 10--500. Default: 50.', metadata=[TuneSpec(low=10, high=500, step=None, log=True, categories=None, tunable=True)]), 'mu': FieldInfo(annotation=float, required=False, default=0.25, description='Contour-length penalty weight in the Chan-Vese energy functional. Higher values produce shorter, smoother outlines and merge nearby colonies; lower values allow the contour to track fine boundary detail at the cost of noise sensitivity. Typical range: 0--1 (lower for diffuse mucoid edges, higher for noisy plates).', metadata=[TuneSpec(low=0.0, high=1.0, step=None, log=False, categories=None, tunable=True)]), 'tol': FieldInfo(annotation=float, required=False, default=0.001, description='Early-stopping criterion: per-pixel level-set change normalised by image area. Smaller values give more precise convergence but require more iterations; values below the noise floor exhaust ``max_num_iter`` without improving results. Typical range: 1e-5--1e-2. Default: 1e-3.', metadata=[TuneSpec(low=1e-05, high=0.01, step=None, log=True, categories=None, tunable=True)])}

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.

mu: Annotated[float, TuneSpec(0.0, 1.0)]

tol: Annotated[float, TuneSpec(1e-05, 0.01, log=True)]

class phenotypic.detect.CompositeDetector(*, detectors: ~typing.List[~typing.Annotated[~typing.Any, ~pydantic.functional_validators.BeforeValidator(func=~phenotypic.sdk_.typing_._deserialize_operation_value, json_schema_input_type=PydanticUndefined), ~pydantic.functional_validators.AfterValidator(func=~phenotypic.sdk_.typing_._make_require_value.<locals>._require), ~pydantic.functional_serializers.PlainSerializer(func=~phenotypic.sdk_.typing_._serialize_operation_value, return_type=PydanticUndefined, when_used=always), _OperationFieldMarker()] | None] = <factory>, mode: ~typing.Literal['union', 'intersection', 'overlap'] = 'overlap', min_overlap_ratio: ~typing.Annotated[float, ~annotated_types.Ge(ge=0.0), ~annotated_types.Le(le=1.0), TuneSpec(low=0.0, high=0.5, step=None, log=False, categories=None, tunable=True)] = 0.0)

Bases: ObjectDetector

Detect colonies by combining multiple detectors via union, intersection, or overlap filtering.

Apply two or more detection algorithms (or preprocessing pipelines ending in a detector) to the same plate image and merge their binary masks. Ensemble combination improves sensitivity (union), specificity (intersection), or both (overlap filtering). This is especially useful for challenging plates where no single algorithm captures all colonies reliably. For a full comparison see Detection Strategies Compared.

Best For:

• Plates where different colony sub-populations respond to different detection algorithms (e.g., bright colonies via Otsu, faint colonies via triangle thresholding).

• Consensus-based quality control that accepts only colonies confirmed by all methods.

• Ensemble strategies that maximise recall by unioning masks from complementary algorithms.

• Benchmarking workflows that compare detector agreement across methods.

Consider Also:

• OtsuDetector or HysteresisDetector when a single detector already captures all colonies reliably.

• WatershedDetector when the primary challenge is separating touching colonies rather than combining detection strategies.

Parameters:

• detectors (List[Annotated[Any, BeforeValidator(func=~phenotypic.sdk_.typing_._deserialize_operation_value, json_schema_input_type=PydanticUndefined), AfterValidator(func=~phenotypic.sdk_.typing_._make_require_value.<locals>._require), PlainSerializer(func=~phenotypic.sdk_.typing_._serialize_operation_value, return_type=PydanticUndefined, when_used=always), _OperationFieldMarker()] | None]) – List of ObjectDetector or ImagePipeline instances to combine. Pipelines allow preprocessing steps before detection. Defaults to [OtsuDetector(), RoundPeaksDetector()] when not specified.

• mode (Literal['union', 'intersection', 'overlap']) – Combination strategy. 'union' marks a pixel as colony if any detector flags it (logical OR, maximises sensitivity). 'intersection' requires all detectors to agree (logical AND, maximises specificity). 'overlap' retains whole objects that have mutual spatial overlap across masks (balances sensitivity and specificity). Default: 'overlap'.

• min_overlap_ratio (Annotated[float, Ge(ge=0.0), Le(le=1.0), TuneSpec(low=0.0, high=0.5, step=None, log=False, categories=None, tunable=True)]) – For 'overlap' mode, minimum fraction of object pixels that must overlap with another mask before an object is retained. At the default 0.0 any mutually overlapping object is kept; larger values bias towards objects confirmed by more than one detector. Typical range: 0.0–0.5. Default: 0.0.

Returns:

Input image with objmask set to the combined binary colony mask and objmap derived from the merged mask.

Return type:

Image

Raises:

ValueError – If detectors is empty or mode is not one of 'union', 'intersection', or 'overlap'.

See also

Tutorial 2: Detecting Colonies

Step-by-step tutorial for basic colony detection.

How To: Choose a Detection Algorithm

Guide for selecting the right detector for your plate images.

Detection Strategies Compared

In-depth comparison of all detection strategies.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

detectors: List[OperationField | None]

min_overlap_ratio: Annotated[float, TuneSpec(0.0, 0.5)]

mode: Literal['union', 'intersection', 'overlap']

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].

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 = {'detectors': FieldInfo(annotation=List[Union[Annotated[Any, BeforeValidator, AfterValidator, PlainSerializer, _OperationFieldMarker], NoneType]], required=False, default_factory=<lambda>, description='List of :class:`~phenotypic.abc_.ObjectDetector` or :class:`~phenotypic.ImagePipeline` instances to combine. Pipelines allow preprocessing steps before detection. Defaults to ``[OtsuDetector(), RoundPeaksDetector()]`` when not specified.'), 'min_overlap_ratio': FieldInfo(annotation=float, required=False, default=0.0, description="For ``'overlap'`` mode, minimum fraction of object pixels that must overlap with another mask before an object is retained. At the default 0.0 any mutually overlapping object is kept; larger values bias towards objects confirmed by more than one detector. Typical range: 0.0--0.5. Default: 0.0.", metadata=[Ge(ge=0.0), Le(le=1.0), TuneSpec(low=0.0, high=0.5, step=None, log=False, categories=None, tunable=True)]), 'mode': FieldInfo(annotation=Literal['union', 'intersection', 'overlap'], required=False, default='overlap', description="Combination strategy. ``'union'`` marks a pixel as colony if any detector flags it (logical OR, maximises sensitivity). ``'intersection'`` requires all detectors to agree (logical AND, maximises specificity). ``'overlap'`` retains whole objects that have mutual spatial overlap across masks (balances sensitivity and specificity). Default: ``'overlap'``.")}

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.

class phenotypic.detect.FilamentousFungiDetector(*, inoculum_detector: ~typing.Annotated[~typing.Any, ~pydantic.functional_validators.BeforeValidator(func=~phenotypic.sdk_.typing_._deserialize_operation_value, json_schema_input_type=PydanticUndefined), ~pydantic.functional_validators.AfterValidator(func=~phenotypic.sdk_.typing_._make_require_value.<locals>._require), ~pydantic.functional_serializers.PlainSerializer(func=~phenotypic.sdk_.typing_._serialize_operation_value, return_type=PydanticUndefined, when_used=always), _OperationFieldMarker()] | None = None, max_colony_radius_px: ~typing.Annotated[float, TuneSpec(low=50.0, high=500.0, step=None, log=True, categories=None, tunable=True)] = 250.0, min_branch_width_px: ~typing.Annotated[int, TuneSpec(low=2, high=10, step=None, log=False, categories=None, tunable=True)] = 3, ignore_borders: bool = True, edge_noise_threshold: ~typing.Annotated[float, TuneSpec(low=2.0, high=12.0, step=None, log=False, categories=None, tunable=True)] = 6.0, reconnection_tolerance: ~typing.Annotated[float, TuneSpec(low=1.0, high=5.0, step=None, log=False, categories=None, tunable=True)] = 2.5, max_gap_length: ~typing.Annotated[int, TuneSpec(low=10, high=60, step=None, log=False, categories=None, tunable=True)] = 30, border_margin_px: ~typing.Annotated[int, TuneSpec(low=20, high=100, step=None, log=False, categories=None, tunable=True)] = 50, frag_reach_px: ~typing.Annotated[int, TuneSpec(low=5, high=30, step=None, log=False, categories=None, tunable=True)] = 10, gap_crossing_penalty: ~typing.Annotated[float, TuneSpec(low=1.0, high=10.0, step=None, log=False, categories=None, tunable=True)] = 4.0, gauss_sigma: ~typing.Annotated[float | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = None, tile_size: ~typing.Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = None, tile_overlap: ~typing.Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = None, pct_min_wavelength: ~typing.Annotated[float | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = None, mad_window: ~typing.Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = None, path_dilation_radius: ~typing.Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = None, snr_margin: ~typing.Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = None, coherence_window_radius: ~typing.Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = None)

Bases: GridObjectDetector

Detect and individually label filamentous fungal colonies by two-stage inoculum-plus-hyphae detection with Euclidean Voronoi partition.

First detect compact inoculation centres with inoculum_detector, then capture the full hyphal network using phase-congruency edge detection combined with Gaussian background subtraction. Disconnected branch fragments are reconnected to their parent colonies via quality-filtered Dijkstra pathfinding on a composite cost surface derived from phase congruency energy, local texture, and orientation coherence. Inoculum centroids seed a Euclidean Voronoi partition that assigns every fungal pixel to its nearest colony, with connectivity-based correction enforcing uniform labelling within each connected component.

For an algorithm overview and a comparison with other detection strategies, see Detection Strategies Compared and The Filamentous Fungi Detection Algorithm.

Best For:

• Filamentous fungal colonies (Aspergillus, Neurospora, Trichoderma) with irregular, spreading hyphal morphologies.

• Dense plates where neighbouring fungal colonies touch or overlap and must be individually labelled.

• Time-course experiments tracking hyphal extension radially outward from compact inoculation sites.

• Grid-based fungal culture plates where one colony per well must be quantified separately.

• High-throughput fungal phenotyping screens requiring consistent separation quality across hundreds of plates.

Consider Also:

• WatershedDetector when colonies are compact and roughly circular (yeast or bacterial morphology).

• OtsuDetector when fungi are well-separated and a single binary mask suffices without individual colony labelling.

• CompositeDetector when combining multiple detection strategies is preferred over the two-stage centre-plus-hyphae approach.

• InoculumDetector when only the compact inoculation centres are needed and full hyphal reconstruction is not required.

Parameters:

• inoculum_detector (Annotated[Any, BeforeValidator(func=~phenotypic.sdk_.typing_._deserialize_operation_value, json_schema_input_type=PydanticUndefined), AfterValidator(func=~phenotypic.sdk_.typing_._make_require_value.<locals>._require), PlainSerializer(func=~phenotypic.sdk_.typing_._serialize_operation_value, return_type=PydanticUndefined, when_used=always), _OperationFieldMarker()] | None) – ObjectDetector or ImagePipeline used to locate compact fungal centres. Should produce small, tight regions at inoculation points; centroids from this detector seed the final Voronoi partition. When None (default), an internal InoculumDetector + KeepSectionLargest pipeline is used. Default: None.

• follow (# Scene-scale parameters — set these first; derived params)

• max_colony_radius_px (Annotated[float, TuneSpec(low=50.0, high=500.0, step=None, log=True, categories=None, tunable=True)]) – Expected maximum colony radius in pixels. Acts as the master scene knob: proportionally scales gauss_sigma, tile_size, and tile_overlap when those are left at None. A reasonable starting point is the radius of the largest colony in pixels at your imaging resolution (e.g. measure colony extent in your image viewer before setting this). Reduce for short-incubation plates or high-well-count formats; increase for slow-growing species with extensive radial growth. Typical range: 50–400. Default: 250.0.

• min_branch_width_px (Annotated[int, TuneSpec(low=2, high=10, step=None, log=False, categories=None, tunable=True)]) – Expected narrowest hyphal branch width in pixels. Scales signal-detection parameters (pct_min_wavelength, mad_window, path_dilation_radius, snr_margin, coherence_window_radius) when those are left at None. Set to the thinnest hyphae visible at your imaging resolution; the derived pct_min_wavelength (2 × min_branch_width_px) is clamped at the Nyquist floor of 2 px. Typical range: 2–8. Default: 3.

• control (# Detection)

• ignore_borders (bool) – Drop objects touching the image border during hysteresis-threshold branch detection. Enable (default) to avoid partial colonies at plate edges; disable when genuine peripheral hyphal growth must be retained. Default: True.

• edge_noise_threshold (Annotated[float, TuneSpec(low=2.0, high=12.0, step=None, log=False, categories=None, tunable=True)]) – Noise-suppression multiplier k for the phase congruency detector. Only features whose phase energy exceeds the estimated noise mean plus k standard deviations of the noise energy are accepted as real edges. Higher values suppress agar texture artefacts at the cost of rejecting weak peripheral hyphae; lower values recover fine structure but may pass background noise on textured media. Typical range: 2.0–10.0. Default: 6.0.

• quality (# Reconnection)

• reconnection_tolerance (Annotated[float, TuneSpec(low=1.0, high=5.0, step=None, log=False, categories=None, tunable=True)]) – IQR multiplier for calibrating reconnection path quality thresholds from confirmed calibration branches. Thresholds are set at median ± reconnection_tolerance × IQR across five quality metrics. Higher values accept more candidate paths (permissive); lower values require paths to closely resemble calibration branches (conservative). Typical range: 1.5–4.0. Default: 2.5.

• max_gap_length (Annotated[int, TuneSpec(low=10, high=60, step=None, log=False, categories=None, tunable=True)]) – Maximum contiguous stretch of high-cost pixels tolerated along a reconnection path, in pixels. Paths containing a window worse than the calibrated threshold are rejected as routing through bare agar. Increase to bridge longer hyphal gaps; decrease to reject longer detours through background. Typical range: 10–100. Default: 30.

• border_margin_px (Annotated[int, TuneSpec(low=20, high=100, step=None, log=False, categories=None, tunable=True)]) – Width of the border penalty ramp applied to image-edge pixels in the Dijkstra cost surface. Prevents reconnection paths from routing along plate borders instead of through genuine hyphal corridors. Set to 0 to disable. Typical range: 0–150. Default: 50.

• frag_reach_px (Annotated[int, TuneSpec(low=5, high=30, step=None, log=False, categories=None, tunable=True)]) – Pre-screening radius in pixels. Fragments whose nearest routable pixel exceeds this distance from the colony boundary are discarded before Dijkstra, saving computation. Fragments within this radius are forwarded for full quality-filtered reconnection. Typical range: 5–40. Default: 10.

• gap_crossing_penalty (Annotated[float, TuneSpec(low=1.0, high=10.0, step=None, log=False, categories=None, tunable=True)]) – Scaling factor for the distance-weighted gap penalty applied to Dijkstra path costs. Higher values strongly penalise traversal of bare agar far from the colony, keeping paths near established structure; lower values allow longer background detours. Typical range: 1.0–10.0. Default: 4.0.

• overrides (# Scene-derivation)

• gauss_sigma (Annotated[float | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Gaussian sigma for background subtraction, in pixels. When None, set to 1.2 × max_colony_radius_px (300 px at the default radius). Must exceed the largest colony radius so the Gaussian estimates only the illumination gradient, not colony signal. Typical range: 50–600. Default: None.

• tile_size (Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Side length of square processing tiles in pixels. When None, set to int(round(4.8 × max_colony_radius_px)) (1200 px at the default radius). Must be large enough to contain an entire colony and its satellite fragments within one tile. Typical range: 200–3000. Default: None.

• tile_overlap (Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Overlap between adjacent tiles in pixels. When None, set to int(round(2.4 × max_colony_radius_px)) (600 px at the default radius). Larger overlap ensures fragments near tile boundaries are co-located with their parent colony in at least one tile. Typical range: 50–1500. Default: None.

• pct_min_wavelength (Annotated[float | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Minimum log-Gabor filter wavelength in pixels for phase congruency detection. When None, set to 2.0 × min_branch_width_px (6 px at the default width). Must be ≥ 2 (Nyquist). Match to the thinnest hyphae width at your imaging resolution. Typical range: 2–20. Default: None.

• mad_window (Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Side length of the square median-filter kernel for local MAD texture computation (must be odd). When None, set to 2 × min_branch_width_px + 1 forced odd (7 at the default width). Should span approximately one branch diameter plus background buffer on each side. Typical range: 3–21. Default: None.

• path_dilation_radius (Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Disk radius for dilating accepted reconnection paths before painting colony labels. When None, set to max(1, round(0.5 × min_branch_width_px)) (2 at the default width). Also sets the inner band radius for path quality metrics. Match to half the expected hyphal width. Typical range: 1–10. Default: None.

• snr_margin (Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Extra pixel margin beyond path_dilation_radius that forms the background annular ring for local SNR estimation. When None, set to max(2, round(0.5 × min_branch_width_px)) (2 at the default width). Keep narrow on dense hyphal networks to avoid sampling adjacent hyphae as background. Typical range: 1–8. Default: None.

• coherence_window_radius (Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Radius of the square averaging kernel for orientation coherence computation. When None, set to round(5.0 × min_branch_width_px) (15 at the default width). Larger radius captures long-range directional consistency; reduce for highly curved or heavily branching networks. Typical range: 5–50. Default: None.

Returns:

Input image with objmask set to a binary mask of all detected fungal pixels and objmap set to a labelled colony map where each fungal colony receives a unique consecutive integer label via Voronoi assignment.

Return type:

Image

Raises:

• TypeError – If inoculum_detector is not an ObjectDetector or ImagePipeline instance.

• ValueError – If no inoculum centres are detected, or no detected centres overlap with the branch structure after filtering.

References

[1] P. Kovesi, “Phase congruency: A low-level image invariant,” Psychol. Res., vol. 64, no. 2, pp. 136–148, 2000.

[2] E. W. Dijkstra, “A note on two problems in connexion with graphs,” Numer. Math., vol. 1, no. 1, pp. 269–271, 1959.

See also

Tutorial 10: Detecting Filamentous Fungi

Dedicated tutorial for filamentous fungi detection workflows.

How To: Choose a Detection Algorithm

Guide for selecting the right detector for your plate images.

The Filamentous Fungi Detection Algorithm

Algorithm details for the two-stage detection and Voronoi partition approach.

Detection Strategies Compared

Comparison of all detection strategies and their failure modes.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

beta: ClassVar[float] = 2.0

border_margin_px: Annotated[int, TuneSpec(20, 100)]

coherence_window_radius: Annotated[int | None, TuneSpec(tunable=False)]

delta: ClassVar[float] = 1.0

edge_noise_threshold: Annotated[float, TuneSpec(2.0, 12.0)]

frag_reach_px: Annotated[int, TuneSpec(5, 30)]

gamma: ClassVar[float] = 1.2

gap_crossing_penalty: Annotated[float, TuneSpec(1.0, 10.0)]

gauss_n_iter: ClassVar[int] = 2

gauss_sigma: Annotated[float | None, TuneSpec(tunable=False)]

ignore_borders: bool

inoculum_detector: OperationField | None

mad_window: Annotated[int | None, TuneSpec(tunable=False)]

max_colony_radius_px: Annotated[float, TuneSpec(50.0, 500.0, log=True)]

max_gap_length: Annotated[int, TuneSpec(10, 60)]

min_branch_width_px: Annotated[int, TuneSpec(2, 10)]

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].

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 = {'border_margin_px': FieldInfo(annotation=int, required=False, default=50, description='Width of the border penalty ramp applied to image-edge pixels in the Dijkstra cost surface. Prevents reconnection paths from routing along plate borders instead of through genuine hyphal corridors. Set to 0 to disable. Typical', metadata=[TuneSpec(low=20, high=100, step=None, log=False, categories=None, tunable=True)]), 'coherence_window_radius': FieldInfo(annotation=Union[int, NoneType], required=False, default=None, description='Radius of the square averaging kernel for orientation coherence computation. When ``None``, set to ``round(5.0 × min_branch_width_px)`` (15 at the default width). Larger radius captures long-range directional consistency; reduce for highly curved or heavily branching networks. Typical', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'edge_noise_threshold': FieldInfo(annotation=float, required=False, default=6.0, description='Noise-suppression multiplier ``k`` for the phase congruency detector. Only features whose phase energy exceeds the estimated noise mean plus ``k`` standard deviations of the noise energy are accepted as real edges. Higher values suppress agar texture artefacts at the cost of rejecting weak peripheral hyphae; lower values recover fine structure but may pass background noise on textured media. Typical range: 2.0--10.0. Default: 6.0. # Reconnection quality', metadata=[TuneSpec(low=2.0, high=12.0, step=None, log=False, categories=None, tunable=True)]), 'frag_reach_px': FieldInfo(annotation=int, required=False, default=10, description='Pre-screening radius in pixels. Fragments whose nearest routable pixel exceeds this distance from the colony boundary are discarded before Dijkstra, saving computation. Fragments within this radius are forwarded for full quality-filtered reconnection. Typical range: 5--40. Default: 10.', metadata=[TuneSpec(low=5, high=30, step=None, log=False, categories=None, tunable=True)]), 'gap_crossing_penalty': FieldInfo(annotation=float, required=False, default=4.0, description='Scaling factor for the distance-weighted gap penalty applied to Dijkstra path costs. Higher values strongly penalise traversal of bare agar far from the colony, keeping paths near established structure; lower values allow longer background detours. Typical range: 1.0--10.0. Default: 4.0. # Scene-derivation overrides (leave at None to auto-derive)', metadata=[TuneSpec(low=1.0, high=10.0, step=None, log=False, categories=None, tunable=True)]), 'gauss_sigma': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Gaussian sigma for background subtraction, in pixels. When ``None``, set to ``1.2 × max_colony_radius_px`` (300 px at the default radius). Must exceed the largest colony radius so the Gaussian estimates only the illumination gradient, not colony signal. Typical range: 50--600. Default: None.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'ignore_borders': FieldInfo(annotation=bool, required=False, default=True, description='Drop objects touching the image border during hysteresis-threshold branch detection. Enable (default) to avoid partial colonies at plate edges; disable when genuine peripheral hyphal growth must be retained. Default: True.'), 'inoculum_detector': FieldInfo(annotation=Union[Annotated[Any, BeforeValidator, AfterValidator, PlainSerializer, _OperationFieldMarker], NoneType], required=False, default=None, description='ObjectDetector or ImagePipeline used to locate compact fungal centres. Should produce small, tight regions at inoculation points; centroids from this detector seed the final Voronoi partition. When ``None`` (default), an internal ``InoculumDetector`` + ``KeepSectionLargest`` pipeline is used.'), 'mad_window': FieldInfo(annotation=Union[int, NoneType], required=False, default=None, description='Side length of the square median-filter kernel for local MAD texture computation (must be odd). When ``None``, set to ``2 × min_branch_width_px + 1`` forced odd (7 at the default width). Should span approximately one branch diameter plus background buffer on each side. Typical range: 3--21.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'max_colony_radius_px': FieldInfo(annotation=float, required=False, default=250.0, description='Expected maximum colony radius in pixels. Acts as the master scene knob: proportionally scales ``gauss_sigma``, ``tile_size``, and ``tile_overlap`` when those are left at ``None``. A reasonable starting point is the radius of the largest colony in pixels at your imaging resolution (e.g. measure colony extent in your image viewer before setting this). Reduce for short-incubation plates or high-well-count formats; increase for slow-growing species with extensive radial growth. Typical range: 50--400. Default: 250.0.', metadata=[TuneSpec(low=50.0, high=500.0, step=None, log=True, categories=None, tunable=True)]), 'max_gap_length': FieldInfo(annotation=int, required=False, default=30, description='Maximum contiguous stretch of high-cost pixels tolerated along a reconnection path, in pixels. Paths containing a window worse than the calibrated threshold are rejected as routing through bare agar. Increase to bridge longer hyphal gaps; decrease to reject longer detours through background. Typical', metadata=[TuneSpec(low=10, high=60, step=None, log=False, categories=None, tunable=True)]), 'min_branch_width_px': FieldInfo(annotation=int, required=False, default=3, description='Expected narrowest hyphal branch width in pixels. Scales signal-detection parameters (``pct_min_wavelength``, ``mad_window``, ``path_dilation_radius``, ``snr_margin``, ``coherence_window_radius``) when those are left at ``None``. Set to the thinnest hyphae visible at your imaging resolution; the derived ``pct_min_wavelength`` (``2 × min_branch_width_px``) is clamped at the Nyquist floor of 2 px. Typical range: 2--8. Default: 3. # Detection control', metadata=[TuneSpec(low=2, high=10, step=None, log=False, categories=None, tunable=True)]), 'path_dilation_radius': FieldInfo(annotation=Union[int, NoneType], required=False, default=None, description='Disk radius for dilating accepted reconnection paths before painting colony labels. When ``None``, set to ``max(1, round(0.5 × min_branch_width_px))`` (2 at the default width). Also sets the inner band radius for path quality metrics. Match to half the expected hyphal width. Typical range: 1--10.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'pct_min_wavelength': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Minimum log-Gabor filter wavelength in pixels for phase congruency detection. When ``None``, set to ``2.0 × min_branch_width_px`` (6 px at the default width). Must be ≥ 2 (Nyquist). Match to the thinnest hyphae width at your imaging resolution. Typical range: 2--20. Default: None.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'reconnection_tolerance': FieldInfo(annotation=float, required=False, default=2.5, description='IQR multiplier for calibrating reconnection path quality thresholds from confirmed calibration branches. Thresholds are set at median ± ``reconnection_tolerance`` × IQR across five quality metrics. Higher values accept more candidate paths (permissive); lower values require paths to closely resemble calibration branches (conservative). Typical range: 1.5--4.0.', metadata=[TuneSpec(low=1.0, high=5.0, step=None, log=False, categories=None, tunable=True)]), 'snr_margin': FieldInfo(annotation=Union[int, NoneType], required=False, default=None, description='Extra pixel margin beyond ``path_dilation_radius`` that forms the background annular ring for local SNR estimation. When ``None``, set to ``max(2, round(0.5 × min_branch_width_px))`` (2 at the default width). Keep narrow on dense hyphal networks to avoid sampling adjacent hyphae as background. Typical range: 1--8. Default: None.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'tile_overlap': FieldInfo(annotation=Union[int, NoneType], required=False, default=None, description='Overlap between adjacent tiles in pixels. When ``None``, set to ``int(round(2.4 × max_colony_radius_px))`` (600 px at the default radius). Larger overlap ensures fragments near tile boundaries are co-located with their parent colony in at least one tile. Typical range: 50--1500. Default: None.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'tile_size': FieldInfo(annotation=Union[int, NoneType], required=False, default=None, description='Side length of square processing tiles in pixels. When ``None``, set to ``int(round(4.8 × max_colony_radius_px))`` (1200 px at the default radius). Must be large enough to contain an entire colony and its satellite fragments within one tile. Typical range: 200--3000. Default: None.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)])}

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.

path_dilation_radius: Annotated[int | None, TuneSpec(tunable=False)]

pct_min_wavelength: Annotated[float | None, TuneSpec(tunable=False)]

pct_n_orient: ClassVar[int] = 8

reconnection_tolerance: Annotated[float, TuneSpec(1.0, 5.0)]

snr_margin: Annotated[int | None, TuneSpec(tunable=False)]

tile_overlap: Annotated[int | None, TuneSpec(tunable=False)]

tile_size: Annotated[int | None, TuneSpec(tunable=False)]

class phenotypic.detect.HysteresisDetector(*, low: str | float = 'mean', high: str | float = 'otsu', ignore_zeros: bool = False, ignore_borders: bool = True)

Bases: ThresholdDetector

Detect colonies by dual-threshold hysteresis, bridging bright cores to faint edges.

Seed strong colony regions that exceed the high threshold and expand each seed via pixel connectivity to include neighbouring pixels above the low threshold. This two-pass approach captures colonies whose intensity varies from bright centres to faint margins – a common pattern across growth stages and under uneven illumination. For a full comparison see Detection Strategies Compared.

Best For:

• Plates where colony brightness varies (e.g., young versus mature growth, or centre-to-edge intensity gradients within a colony).

• Noisy agar backgrounds where isolated noise pixels sit above a single threshold but lack connectivity to true colony regions.

• Moderate vignetting or lighting gradients that cause a single global threshold to over- or under-segment parts of the plate.

• Mixed-species plates where different organisms produce colonies of different intensities on the same agar.

Consider Also:

• OtsuDetector when colony and background peaks are balanced and a single threshold suffices.

• WatershedDetector when touching colonies must be split into individually labelled regions.

• CannyDetector when colonies are best delineated by edge contrast rather than intensity.

Parameters:

• low (str | float) – Lower threshold controlling expansion sensitivity. There is no universal best value – it is a user choice. Accepts a method name ('otsu', 'triangle', 'li', 'yen', 'isodata', 'mean', 'minimum') for automatic computation, or a float for a manual value (0–255 for 8-bit, 0–65535 for 16-bit). Default 'mean'. Lowering low grows each seed outward to capture more faint marginal pixels but risks bridging colonies into noise; raising it tightens each colony toward its bright core. Start with 'mean' and adjust by observing whether faint colony edges are kept or lost. Dense plates and filamentous fungi (thin faint margins) often need a lower low; noisy agar needs it raised.

• high (str | float) – Upper threshold seeding strong colony regions. Same format and user-choice character as low. Default 'otsu'. Must resolve to a value >= low. Raising high restricts seeds to the brightest colony centres (fewer, higher-confidence detections); lowering it admits more, dimmer seeds. Raise high on noisy or textured plates so agar granularity is not seeded; lower it when genuine faint colonies fail to seed at all.

• ignore_zeros (bool) – If True, exclude zero-intensity pixels from automatic threshold computation. Enable for plates with black borders or masked regions. Default: False.

• ignore_borders (bool) – If True (default), remove colonies touching image edges via clear_border(). Recommended for grid-based colony counting; disable when peripheral colonies must be retained.

Returns:

Input image with objmask set to a binary colony mask where True pixels are colony foreground (including faint pixels connected to strong seed regions). Assigning objmask rebuilds objmap from the binary mask via the accessor.

Return type:

Image

Raises:

ValueError – If the computed high threshold is less than the computed low threshold, or if an unrecognised threshold method name is provided.

See also

Tutorial 2: Detecting Colonies

Step-by-step tutorial for basic colony detection.

How To: Choose a Detection Algorithm

Guide for selecting the right detector for your plate images.

Detection Strategies Compared

In-depth comparison of all detection strategies.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

high: str | float

ignore_borders: bool

ignore_zeros: bool

low: str | float

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].

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 = {'high': FieldInfo(annotation=Union[str, float], required=False, default='otsu', description="Upper threshold seeding strong colony regions. Same format and user-choice character as *low*. Default ``'otsu'``. Must resolve to a value >= *low*. Raising *high* restricts seeds to the brightest colony centres (fewer, higher-confidence detections); lowering it admits more, dimmer seeds. Raise *high* on noisy or textured plates so agar granularity is not seeded; lower it when genuine faint colonies fail to seed at all."), 'ignore_borders': FieldInfo(annotation=bool, required=False, default=True, description='If True (default), remove colonies touching image edges via ``clear_border()``. Recommended for grid-based colony counting; disable when peripheral colonies must be retained.'), 'ignore_zeros': FieldInfo(annotation=bool, required=False, default=False, description='If True, exclude zero-intensity pixels from automatic threshold computation. Enable for plates with black borders or masked regions. Default: False.'), 'low': FieldInfo(annotation=Union[str, float], required=False, default='mean', description="Lower threshold controlling expansion sensitivity. There is no universal best value -- it is a user choice. Accepts a method name (``'otsu'``, ``'triangle'``, ``'li'``, ``'yen'``, ``'isodata'``, ``'mean'``, ``'minimum'``) for automatic computation, or a float for a manual value (0--255 for 8-bit, 0--65535 for 16-bit). Default ``'mean'``. Lowering *low* grows each seed outward to capture more faint marginal pixels but risks bridging colonies into noise; raising it tightens each colony toward its bright core. Start with ``'mean'`` and adjust by observing whether faint colony edges are kept or lost. Dense plates and filamentous fungi (thin faint margins) often need a lower *low*; noisy agar needs it raised.")}

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.

class phenotypic.detect.InoculumDetector(*, min_diameter: Annotated[float, Gt(gt=0.0), TuneSpec(low=5.0, high=80.0, step=None, log=True, categories=None, tunable=True)] = 30.0, max_diameter: Annotated[float, Gt(gt=0.0), TuneSpec(low=50.0, high=300.0, step=None, log=True, categories=None, tunable=True)] = 100.0, thresh_method: Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li'] = 'otsu', enable_gmm: bool = True, gmm_n_components: Annotated[int, TuneSpec(low=2, high=4, step=None, log=False, categories=None, tunable=True)] = 2, gmm_separation_threshold: Annotated[float, TuneSpec(low=0.8, high=1.2, step=None, log=False, categories=None, tunable=True)] = 0.9, validate_obj_count: bool = True)

Bases: ObjectDetector

Detect inoculation sites on agar plates via Gaussian background subtraction and multi-scale blob enhancement.

Identify inoculation spots (from pin-deposition tools, liquid spotting, or serial dilutions) by composing Gaussian background subtraction, median filtering, multi-scale Laplacian-of-Gaussian blob enhancement, contrast stretching, morphological opening, round-peaks detection, and optional GMM-based core extraction. All processing occurs on a working copy so that image.detect_mat is never modified. For a full comparison see Detection Strategies Compared.

Best For:

• Pin-tool inoculation on high-density plates (96-well, 384-well) where inocula are 30–80 pixels in diameter.

• Spot-dilution assays producing 10–150 pixel inocula across serial dilution series.

• Pre-growth phenotyping baselines (T=0 imaging) for establishing reference coordinates before growth measurements.

• Liquid spotting assays where GMM core extraction refines boundaries for accurate area and circularity measurements.

Consider Also:

• RoundPeaksDetector when colonies (not inocula) must be detected on a regular grid without multi-scale blob enhancement.

• OtsuDetector when inocula are high-contrast and a simple global threshold is sufficient.

• FilamentousFungiDetector when inoculation sites have developed into filamentous fungal growth.

Parameters:

• min_diameter (Annotated[float, Gt(gt=0.0), TuneSpec(low=5.0, high=80.0, step=None, log=True, categories=None, tunable=True)]) – Smallest expected inoculum diameter in pixels. Used to derive LoG minimum radius and GMM morphological parameters. Set based on the smallest visible spot in your images. Typical range: 5–80. Default: 30.0.

• max_diameter (Annotated[float, Gt(gt=0.0), TuneSpec(low=50.0, high=300.0, step=None, log=True, categories=None, tunable=True)]) – Largest expected inoculum diameter in pixels. Used to derive Gaussian background subtraction sigma and LoG maximum radius. Must be greater than min_diameter. Typical range: 50–300. Default: 100.0.

• thresh_method (Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li']) – Thresholding method for binary segmentation within the RoundPeaksDetector step. Accepted values: 'otsu' (default), 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li'. 'otsu' works well for most standardised setups; 'local' adapts to spatial illumination gradients. Default: 'otsu'.

• enable_gmm (bool) – Apply Gaussian Mixture Model core extraction to refine detected regions to bright, compact cores. Disable for inocula that lack clear core-surround structure. Default: True.

• gmm_n_components (Annotated[int, TuneSpec(low=2, high=4, step=None, log=False, categories=None, tunable=True)]) – Number of GMM components per region. Two components separate core from surround; increase only for complex multi-layered spots. Default: 2.

• gmm_separation_threshold (Annotated[float, TuneSpec(low=0.8, high=1.2, step=None, log=False, categories=None, tunable=True)]) – Normalised Euclidean distance between GMM component means below which a region is left unmodified (no clear core). Increase to make refinement less aggressive. Typical range: 0.8–1.2. Default: 0.9.

• validate_obj_count (bool) – When True and the input is a GridImage, raise ValueError when the detected object count exceeds nrows * ncols. Catches over-segmentation early. Default: True.

Returns:

Input image with objmask (binary inoculum mask) and objmap (labelled inoculum map) populated.

Return type:

Image

Raises:

ValueError – If min_diameter >= max_diameter, or if detected object count exceeds grid capacity when validate_obj_count is True and input is a GridImage.

See also

Tutorial 2: Detecting Colonies

Step-by-step tutorial for basic colony detection.

How To: Choose a Detection Algorithm

Guide for selecting the right detector for your plate images.

Detection Strategies Compared

In-depth comparison of all detection strategies.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

enable_gmm: bool

gmm_n_components: Annotated[int, TuneSpec(2, 4)]

gmm_separation_threshold: Annotated[float, TuneSpec(0.8, 1.2)]

max_diameter: Annotated[float, TuneSpec(50.0, 300.0, log=True)]

min_diameter: Annotated[float, TuneSpec(5.0, 80.0, log=True)]

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].

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 = {'enable_gmm': FieldInfo(annotation=bool, required=False, default=True, description='Apply Gaussian Mixture Model core extraction to refine detected regions to bright, compact cores. Disable for inocula that lack clear core-surround structure. Default: True.'), 'gmm_n_components': FieldInfo(annotation=int, required=False, default=2, description='Number of GMM components per region. Two components separate core from surround; increase only for complex multi-layered spots. Default: 2.', metadata=[TuneSpec(low=2, high=4, step=None, log=False, categories=None, tunable=True)]), 'gmm_separation_threshold': FieldInfo(annotation=float, required=False, default=0.9, description='Normalised Euclidean distance between GMM component means below which a region is left unmodified (no clear core). Increase to make refinement less aggressive. Typical range: 0.8--1.2. Default: 0.9.', metadata=[TuneSpec(low=0.8, high=1.2, step=None, log=False, categories=None, tunable=True)]), 'max_diameter': FieldInfo(annotation=float, required=False, default=100.0, description='Largest expected inoculum diameter in pixels. Used to derive Gaussian background subtraction sigma and LoG maximum radius. Must be greater than ``min_diameter``. Typical range: 50--300. Default: 100.0.', metadata=[Gt(gt=0.0), TuneSpec(low=50.0, high=300.0, step=None, log=True, categories=None, tunable=True)]), 'min_diameter': FieldInfo(annotation=float, required=False, default=30.0, description='Smallest expected inoculum diameter in pixels. Used to derive LoG minimum radius and GMM morphological parameters. Set based on the smallest visible spot in your images. Typical', metadata=[Gt(gt=0.0), TuneSpec(low=5.0, high=80.0, step=None, log=True, categories=None, tunable=True)]), 'thresh_method': FieldInfo(annotation=Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li'], required=False, default='otsu', description="Thresholding method for binary segmentation within the RoundPeaksDetector step. Accepted values: ``'otsu'`` (default), ``'mean'``, ``'local'``, ``'triangle'``, ``'minimum'``, ``'isodata'``, ``'li'``. ``'otsu'`` works well for most standardised setups; ``'local'`` adapts to spatial illumination gradients. Default: ``'otsu'``."), 'validate_obj_count': FieldInfo(annotation=bool, required=False, default=True, description='When True and the input is a ``GridImage``, raise ``ValueError`` when the detected object count exceeds ``nrows * ncols``. Catches over-segmentation early. Default: True.')}

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.

thresh_method: Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li']

validate_obj_count: bool

class phenotypic.detect.IsodataDetector(*, ignore_zeros: bool = False, ignore_borders: bool = True)

Bases: ThresholdDetector

Detect colonies by iterative ISODATA clustering of the intensity histogram.

Iteratively partition pixels into foreground and background classes by computing class means, then refine the threshold until the estimate converges. The resulting binary mask separates colony pixels from agar background and works best when both pixel populations have similar variance and roughly balanced counts. For a full comparison of detection strategies see Detection Strategies Compared.

Best For:

• Plates where colony and background pixel counts are roughly balanced.

• Medium-contrast images where iterative refinement improves on a single-pass threshold.

• Standardised imaging setups producing consistently symmetric histograms across plates.

Consider Also:

• OtsuDetector for a faster single-pass threshold when the histogram is clearly bimodal.

• LiDetector when the histogram is skewed or noise dominates one side of the distribution.

• HysteresisDetector when colony brightness varies across the plate and a single threshold under-segments faint regions.

Parameters:

• ignore_zeros (bool) – Exclude zero-intensity pixels from the histogram before computing the threshold. Enable for plates with black borders or masked regions. Default: False.

• ignore_borders (bool) – Remove colonies touching image edges via clear_border(). Recommended for grid-based colony counting to eliminate partial colonies at plate boundaries. Default: True.

Returns:

Input image with objmask set to the binary colony mask and objmap set to labeled connected components.

Return type:

Image

Raises:

ValueError – If threshold computation fails due to a degenerate histogram with insufficient intensity variation.

References

[1] T. W. Ridler and S. Calvard, “Picture thresholding using an iterative selection method,” IEEE Trans. Syst., Man, Cybern., vol. 8, no. 8, pp. 630–632, 1978.

See also

Tutorial 2: Detecting Colonies for a step-by-step tutorial on basic colony detection. How To: Choose a Detection Algorithm for guidance on selecting the right detector for your plate images. Detection Strategies Compared for an in-depth comparison of all thresholding strategies.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

ignore_borders: bool

ignore_zeros: bool

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].

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 = {'ignore_borders': FieldInfo(annotation=bool, required=False, default=True, description='Remove colonies touching image edges via ``clear_border()``. Recommended for grid-based colony counting to eliminate partial colonies at plate boundaries. Default: True.'), 'ignore_zeros': FieldInfo(annotation=bool, required=False, default=False, description='Exclude zero-intensity pixels from the histogram before computing the threshold. Enable for plates with black borders or masked regions. Default: False.')}

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.

class phenotypic.detect.LiDetector(*, ignore_zeros: bool = False, ignore_borders: bool = True)

Bases: ThresholdDetector

Detect colonies by minimising cross-entropy between the original and thresholded image.

Iteratively refine a threshold that minimises the information loss (cross-entropy) between the original intensity distribution and its binarised form. Performs well on low-contrast or noisy plates where the histogram is not clearly bimodal and variance-based assumptions may not hold. For a full comparison of detection strategies see Detection Strategies Compared.

Best For:

• Low-contrast plates where colony and background intensities overlap significantly.

• Noisy or textured agar backgrounds that create histogram irregularities breaking bimodal assumptions.

• Images where the intensity distribution is unimodal or only weakly bimodal.

Consider Also:

• OtsuDetector when the histogram is clearly bimodal and a single-pass variance-minimising threshold suffices.

• YenDetector for a correlation-based alternative that handles skewed histograms.

• HysteresisDetector when colony brightness varies across the plate and a single threshold under-segments faint regions.

Parameters:

• ignore_zeros (bool) – Exclude zero-intensity pixels from the histogram before computing the threshold. Enable for plates with black borders or masked regions. Default: False.

• ignore_borders (bool) – Remove colonies touching image edges via clear_border(). Recommended for grid-based colony counting to eliminate partial colonies at plate boundaries. Default: True.

Returns:

Input image with objmask set to the binary colony mask and objmap set to labeled connected components.

Return type:

Image

Raises:

ValueError – If threshold computation fails due to a degenerate histogram with insufficient intensity variation.

References

[1] C. H. Li and C. K. Lee, “Minimum cross entropy thresholding,” Pattern Recognit., vol. 26, no. 4, pp. 617–625, 1993.

See also

Tutorial 2: Detecting Colonies for a step-by-step tutorial on basic colony detection. How To: Choose a Detection Algorithm for guidance on selecting the right detector for your plate images. Detection Strategies Compared for an in-depth comparison of all thresholding strategies.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

ignore_borders: bool

ignore_zeros: bool

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].

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 = {'ignore_borders': FieldInfo(annotation=bool, required=False, default=True, description='Remove colonies touching image edges via ``clear_border()``. Recommended for grid-based colony counting to eliminate partial colonies at plate boundaries. Default: True.'), 'ignore_zeros': FieldInfo(annotation=bool, required=False, default=False, description='Exclude zero-intensity pixels from the histogram before computing the threshold. Enable for plates with black borders or masked regions. Default: False.')}

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.

class phenotypic.detect.MadHysteresisDetector(*, k_high: Annotated[float, TuneSpec(low=4.0, high=8.0, step=None, log=False, categories=None, tunable=True)] = 5.0, k_low: Annotated[float, TuneSpec(low=1.5, high=3.5, step=None, log=False, categories=None, tunable=True)] = 2.5, min_size: Annotated[int, TuneSpec(low=10, high=500, step=None, log=True, categories=None, tunable=True)] = 20, connectivity: Annotated[int, Ge(ge=1), Le(le=2), TuneSpec(low=None, high=None, step=None, log=False, categories=1, 2, tunable=True)] = 2, ignore_zeros: bool = False, ignore_borders: bool = True)

Bases: ThresholdDetector

Detect colonies by MAD-based noise estimation and hysteresis thresholding.

Estimate the background noise floor using the Median Absolute Deviation (MAD), then apply hysteresis thresholding with thresholds set as multiples of the estimated noise standard deviation. Designed for filter response maps (CED, Hessian, LoG, Frangi) where the noise structure is approximately Gaussian and histogram-based methods produce unstable thresholds. For a full comparison see Detection Strategies Compared.

Best For:

• Filter response maps (CED, Hessian, LoG, Frangi) where the noise floor is approximately Gaussian.

• Low-contrast colonies where signal is faint relative to background texture and MAD provides a stable noise estimate.

• Standardised pipelines where multiplier-based thresholds generalise across plates with varying colony density.

Consider Also:

• HysteresisDetector when thresholds should be derived from the intensity histogram rather than noise statistics.

• OtsuDetector when the image is a raw intensity plate with a bimodal histogram.

• ChanVeseDetector when colonies have diffuse edges and region-based segmentation is more appropriate.

Parameters:

• k_high (Annotated[float, TuneSpec(low=4.0, high=8.0, step=None, log=False, categories=None, tunable=True)]) – High-threshold multiplier setting the seed threshold at k_high * sigma_noise standard deviations above the noise floor. There is no universal best value – it is tuned to the scene. Raising k_high accepts only the most prominent colonies as seeds (more conservative); lowering it seeds dimmer structures. Typical range: 3.0–8.0. Default: 5.0. On noisy or strongly textured plates raise toward 6–8 so agar granularity is not seeded; on faint enhancer outputs (e.g. Frangi on weak hyphae) lower toward 3–4 so genuine signal seeds at all.

• k_low (Annotated[float, TuneSpec(low=1.5, high=3.5, step=None, log=False, categories=None, tunable=True)]) – Low-threshold multiplier setting the growth threshold at k_low * sigma_noise; pixels above this join a seed if connected to it. Must be strictly less than k_high. The ratio k_high / k_low trades selectivity against coverage: a wider gap grows seeds further into faint margins. Typical range: 1.5–4.0. Default: 2.5. Lower toward 1.5–2.0 to recover the faint edges of filamentous or low-contrast colonies; raise it on clean high-contrast maps.

• min_size (Annotated[int, TuneSpec(low=10, high=500, step=None, log=True, categories=None, tunable=True)]) – Minimum colony area in pixels; connected components smaller than this are removed as noise, debris, or condensation. Raising it silences small artefacts at the cost of missing genuine micro-colonies; lowering it recovers faint colonies but raises false positives. Scale with resolution – smaller for dense 384/1536 formats, larger for high-dpi scans. Default: 20.

• connectivity (Annotated[int, Ge(ge=1), Le(le=2), TuneSpec(low=None, high=None, step=None, log=False, categories=(1, 2), tunable=True)]) – Pixel connectivity for labelling connected components. 1 (4-connected) keeps diagonally touching objects separate; 2 (8-connected) bridges diagonal gaps in thin or branching structures into fewer, larger regions. Default: 2.

• ignore_zeros (bool) – Exclude zero-intensity pixels from MAD computation. Enable for plates with black borders or masked regions. Default: False.

• ignore_borders (bool) – Remove colonies touching image edges via clear_border(). Recommended for grid-based colony counting to eliminate partial colonies at plate boundaries. Default: True.

Returns:

Input image with objmask set to binary mask and objmap set to labeled connected components.

Return type:

Image

Raises:

ValueError – If k_low >= k_high.

See also

Tutorial 2: Detecting Colonies

Step-by-step tutorial for basic colony detection.

How To: Choose a Detection Algorithm

Guide for selecting the right detector for your plate images.

Detection Strategies Compared

In-depth comparison of all detection strategies.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

connectivity: Annotated[int, TuneSpec(categories=[1, 2])]

ignore_borders: bool

ignore_zeros: bool

k_high: Annotated[float, TuneSpec(4.0, 8.0)]

k_low: Annotated[float, TuneSpec(1.5, 3.5)]

min_size: Annotated[int, TuneSpec(10, 500, log=True)]

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].

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 = {'connectivity': FieldInfo(annotation=int, required=False, default=2, description='Pixel connectivity for labelling connected components. ``1`` (4-connected) keeps diagonally touching objects separate; ``2`` (8-connected) bridges diagonal gaps in thin or branching structures into fewer, larger regions.', metadata=[Ge(ge=1), Le(le=2), TuneSpec(low=None, high=None, step=None, log=False, categories=(1, 2), tunable=True)]), 'ignore_borders': FieldInfo(annotation=bool, required=False, default=True, description='Remove colonies touching image edges via ``clear_border()``. Recommended for grid-based colony counting to eliminate partial colonies at plate boundaries. Default: True.'), 'ignore_zeros': FieldInfo(annotation=bool, required=False, default=False, description='Exclude zero-intensity pixels from MAD computation. Enable for plates with black borders or masked regions.'), 'k_high': FieldInfo(annotation=float, required=False, default=5.0, description='High-threshold multiplier setting the seed threshold at ``k_high * sigma_noise`` standard deviations above the noise floor. There is no universal best value -- it is tuned to the scene. Raising *k_high* accepts only the most prominent colonies as seeds (more conservative); lowering it seeds dimmer structures. Typical range: 3.0--8.0. Default: 5.0. On noisy or strongly textured plates raise toward 6--8 so agar granularity is not seeded; on faint enhancer outputs (e.g. Frangi on weak hyphae) lower toward 3--4 so genuine signal seeds at all.', metadata=[TuneSpec(low=4.0, high=8.0, step=None, log=False, categories=None, tunable=True)]), 'k_low': FieldInfo(annotation=float, required=False, default=2.5, description='Low-threshold multiplier setting the growth threshold at ``k_low * sigma_noise``; pixels above this join a seed if connected to it. Must be strictly less than *k_high*. The ratio *k_high* / *k_low* trades selectivity against coverage: a wider gap grows seeds further into faint margins. Typical range: 1.5--4.0. Default: 2.5. Lower toward 1.5--2.0 to recover the faint edges of filamentous or low-contrast colonies; raise it on clean high-contrast maps.', metadata=[TuneSpec(low=1.5, high=3.5, step=None, log=False, categories=None, tunable=True)]), 'min_size': FieldInfo(annotation=int, required=False, default=20, description='Minimum colony area in pixels; connected components smaller than this are removed as noise, debris, or condensation. Raising it silences small artefacts at the cost of missing genuine micro-colonies; lowering it recovers faint colonies but raises false positives. Scale with resolution -- smaller for dense 384/1536 formats, larger for high-dpi scans. Default: 20.', metadata=[TuneSpec(low=10, high=500, step=None, log=True, categories=None, tunable=True)])}

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.

class phenotypic.detect.ManualGridPointDetector(*, coord1: tuple[int, int] = (0, 0), coord2: tuple[int, int] | None = None, shape: Literal['square', 'diamond', 'disk'] = 'disk', width: Annotated[int, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 15)

Bases: GridObjectDetector, FootprintMixin

Detect colonies by stamping footprint masks at evenly-spaced grid positions derived from reference coordinates.

Compute a regular grid of colony positions from one or two user-supplied pixel coordinates, then stamp a morphological footprint at each position to produce objmask and objmap. This purely geometric approach bypasses intensity-based detection entirely, making it ideal when colony positions follow a known pattern but automatic grid detection is unreliable. For a full comparison see Detection Strategies Compared.

In one-coordinate mode, coord1 defines the top-left cell centre and symmetric margins are assumed: row spacing = (H - 2*y) / (nrows - 1), column spacing = (W - 2*x) / (ncols - 1). In two-coordinate mode, coord1 and coord2 define cells (0, 0) and (1, 1); row and column spacing are derived from their difference and extrapolated across all grid cells.

Best For:

• Plates where automatic grid finders fail due to low contrast, missing wells, or non-standard plate formats.

• Template-based detection when colony positions are known a priori from plate layout metadata or robotic spotting coordinates.

• Generating ground-truth masks for testing or validating other detection pipelines.

• Quick prototyping when full detection is unnecessary and grid geometry is well-characterised.

Consider Also:

• RoundPeaksDetector when grid positions can be inferred automatically from intensity profiles.

• WatershedDetector when colonies are not on a regular grid and must be separated by region growing.

• InoculumDetector when inoculation sites must be detected from image content rather than geometric templates.

Parameters:

• coord1 (tuple[int, int]) – (y, x) pixel position of the top-left grid cell centre (row 0, column 0), picked by the user (no universal value). This is the anchor from which all other positions are calculated. Default (0, 0). Place it on the visible centre of the first colony; adjust by observing whether the stamped grid drifts off the colonies toward the far rows/columns.

• coord2 (tuple[int, int] | None) – Optional (y, x) pixel position of the diagonally adjacent cell (row 1, column 1). When provided, row and column spacing are derived from the difference between coord2 and coord1 – the most reliable mode, since it pins the true pitch from two real colonies rather than assuming symmetric margins. When omitted, spacing is computed from image dimensions assuming symmetric margins. Default: None.

• shape (Literal['square', 'diamond', 'disk']) – Morphological footprint shape stamped at each grid position. "disk" (default) preserves round colony geometry. "square" covers rectangular well regions. "diamond" offers a compromise between the two.

• width (Annotated[int, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Diameter of the footprint in pixels. Larger values cover more area per grid cell (risking overlap of adjacent cells); smaller values produce tighter, more precise masks. A reasonable starting point is roughly the visible colony diameter, then shrink it if neighbouring stamps merge or grow it if colonies overflow their stamp. Typical range: 5–50, depending on image resolution and colony size. Default: 15.

Returns:

Input image with objmask set to the union of all stamped footprints and objmap set to uniquely labelled regions (1-indexed, row-major order).

Return type:

GridImage

Raises:

GridImageInputError – If a plain Image is passed instead of a GridImage.

See also

Tutorial 2: Detecting Colonies

Step-by-step tutorial for basic colony detection.

How To: Choose a Detection Algorithm

Guide for selecting the right detector for your plate images.

Detection Strategies Compared

In-depth comparison of all detection strategies.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

napari(image: GridImage) → ManualGridPointDetector

Interactively pick 1–2 anchor coordinates using a napari viewer.

Opens a blocking napari viewer displaying the plate image layers (RGB, grayscale, detection matrix). Click up to two points to define the grid anchor positions, then click Confirm in the dock widget. The picked coordinates update coord1 and coord2 on this detector instance.

Parameters:

image (GridImage) – The GridImage to display for coordinate selection.

Returns:

Self, for method chaining.

Return type:

ManualGridPointDetector

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

coord1: tuple[int, int]

coord2: tuple[int, int] | None

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].

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 = {'coord1': FieldInfo(annotation=tuple[int, int], required=False, default=(0, 0), description='``(y, x)`` pixel position of the top-left grid cell centre (row 0, column 0), picked by the user (no universal value). This is the anchor from which all other positions are calculated. Default ``(0, 0)``. Place it on the visible centre of the first colony; adjust by observing whether the stamped grid drifts off the colonies toward the far rows/columns.'), 'coord2': FieldInfo(annotation=Union[tuple[int, int], NoneType], required=False, default=None, description='Optional ``(y, x)`` pixel position of the diagonally adjacent cell (row 1, column 1). When provided, row and column spacing are derived from the difference between *coord2* and *coord1* -- the most reliable mode, since it pins the true pitch from two real colonies rather than assuming symmetric margins. When omitted, spacing is computed from image dimensions assuming symmetric margins. Default: None.'), 'shape': FieldInfo(annotation=Literal['square', 'diamond', 'disk'], required=False, default='disk', description='Morphological footprint shape stamped at each grid position. ``"disk"`` (default) preserves round colony geometry. ``"square"`` covers rectangular well regions. ``"diamond"`` offers a compromise between the two.'), 'width': FieldInfo(annotation=int, required=False, default=15, description='Diameter of the footprint in pixels. Larger values cover more area per grid cell (risking overlap of adjacent cells); smaller values produce tighter, more precise masks. A reasonable starting point is roughly the visible colony diameter, then shrink it if neighbouring stamps merge or grow it if colonies overflow their stamp. Typical range: 5--50, depending on image resolution and colony size. Default: 15.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)])}

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.

shape: Literal['square', 'diamond', 'disk']

width: Annotated[int, TuneSpec(tunable=False)]

class phenotypic.detect.ManualPointDetector(*, centers: list[tuple[float, float]] | None = None, shape: Literal['square', 'diamond', 'disk'] = 'disk', width: Annotated[int, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 15)

Bases: ObjectDetector, PointPickerMixin, FootprintMixin

Detect objects by stamping footprint masks at user-specified coordinates.

Place a morphological footprint at each explicitly provided (y, x) centre coordinate to produce objmask and objmap. Unlike ManualGridPointDetector, which extrapolates a regular grid from one or two anchor points, this class requires an explicit list of every colony centre. This makes it suitable for plates without regular geometry, sparse or irregular layouts, and manual annotation workflows where each object position is known individually.

Best For:

• Manual annotation and ground-truth mask generation for benchmarking detection algorithms.

• Non-grid plates (e.g., streak plates, random inoculations, environmental samples) where colony positions are irregular.

• Validating other detection algorithms by comparing their output against user-curated centre coordinates.

• Quick prototyping on small numbers of colonies without needing automatic detection.

Consider Also:

• ManualGridPointDetector when colonies lie on a regular grid and only one or two anchor coordinates are needed.

• RoundPeaksDetector when colony centres can be inferred automatically from intensity profiles.

Parameters:

• centers (list[tuple[float, float]] | None) – An N x 2 array-like of (y, x) pixel coordinates, one per colony, supplied by the user (purely a manual choice). Accepts any sequence that np.asarray can convert (list of tuples, nested list, or NumPy array). When None (default) or empty, apply() zeros out objmask and objmap and returns immediately.

• shape (Literal['square', 'diamond', 'disk']) – Morphological footprint shape stamped at each coordinate. "disk" (default) preserves round colony geometry. "square" covers rectangular regions. "diamond" offers a compromise between the two.

• width (Annotated[int, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Diameter of the footprint in pixels. Larger values cover more area per colony (risking overlap of touching colonies); smaller values produce tighter, more precise masks. A reasonable starting point is roughly the visible colony diameter, then adjust by checking whether stamps under-cover large colonies or spill onto neighbours. Typical range: 5–50, depending on image resolution and colony size. Default: 15.

Returns:

Input image with objmask set to the union of all stamped footprints and objmap set to uniquely labelled regions (1-indexed, in the order centres were supplied).

Return type:

Image

See also

Tutorial 2: Detecting Colonies

Step-by-step tutorial for basic colony detection.

How To: Choose a Detection Algorithm

Guide for selecting the right detector for your plate images.

Detection Strategies Compared

In-depth comparison of all detection strategies.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

napari(image: Image) → _T

Interactively pick coordinates using a napari viewer.

Opens a blocking napari viewer displaying the plate image layers. Click points on the image, then click Confirm in the dock widget. The picked coordinates are stored in the attribute named by _point_picker_param_name. If the viewer is closed without confirming any points, existing coordinates are preserved.

Parameters:

• image (Image) – The Image to display for coordinate selection.

• self (_T)

Returns:

The mixin-bearing instance, for method chaining.

Raises:

ImportError – If napari is not installed.

Return type:

_T

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

centers: list[tuple[float, float]] | None

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].

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 = {'centers': FieldInfo(annotation=Union[list[tuple[float, float]], NoneType], required=False, default=None, description='An N x 2 array-like of ``(y, x)`` pixel coordinates, one per colony, supplied by the user (purely a manual choice). Accepts any sequence that ``np.asarray`` can convert (list of tuples, nested list, or NumPy array). When *None* (default) or empty, :meth:`apply` zeros out ``objmask`` and ``objmap`` and returns immediately.'), 'shape': FieldInfo(annotation=Literal['square', 'diamond', 'disk'], required=False, default='disk', description='Morphological footprint shape stamped at each coordinate. ``"disk"`` (default) preserves round colony geometry. ``"square"`` covers rectangular regions. ``"diamond"`` offers a compromise between the two.'), 'width': FieldInfo(annotation=int, required=False, default=15, description='Diameter of the footprint in pixels. Larger values cover more area per colony (risking overlap of touching colonies); smaller values produce tighter, more precise masks. A reasonable starting point is roughly the visible colony diameter, then adjust by checking whether stamps under-cover large colonies or spill onto neighbours. Typical range: 5--50, depending on image resolution and colony size. Default: 15.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)])}

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.

shape: Literal['square', 'diamond', 'disk']

width: Annotated[int, TuneSpec(tunable=False)]

class phenotypic.detect.MeanDetector(*, ignore_zeros: bool = False, ignore_borders: bool = True)

Bases: ThresholdDetector

Detect colonies by thresholding at the arithmetic mean pixel intensity.

Use the arithmetic mean of all pixel intensities as the classification boundary, assigning pixels above the mean to colony foreground. This parameter-free baseline is fast, deterministic, and requires no histogram assumptions, making it a reliable fallback when adaptive methods produce unexpected results. For a full comparison of detection strategies see Detection Strategies Compared.

Best For:

• Quick baseline detection requiring no parameter tuning.

• Sanity-checking preprocessing steps before applying a more specialised detector.

• Plates where colony and background areas are roughly equal in size, placing the mean near the natural separation point.

• Debugging pipelines where a simple, predictable threshold is needed.

Consider Also:

• OtsuDetector for a statistically optimal threshold that adapts to the histogram shape.

• TriangleDetector when colonies are sparse and the histogram is strongly skewed toward the background.

• IsodataDetector for an iterative refinement that converges to a class-mean midpoint more robustly than the global mean.

Parameters:

• ignore_zeros (bool) – Exclude zero-intensity pixels from the mean calculation before computing the threshold. Enable for plates with black borders or masked regions. Default: False.

• ignore_borders (bool) – Remove colonies touching image edges via clear_border(). Recommended for grid-based colony counting to eliminate partial colonies at plate boundaries. Default: True.

Returns:

Input image with objmask set to the binary colony mask and objmap set to labeled connected components.

Return type:

Image

Raises:

ValueError – If all pixels share the same intensity value, making threshold computation degenerate.

See also

Tutorial 2: Detecting Colonies for a step-by-step tutorial on basic colony detection. How To: Choose a Detection Algorithm for guidance on selecting the right detector for your plate images. Detection Strategies Compared for an in-depth comparison of all thresholding strategies.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

ignore_borders: bool

ignore_zeros: bool

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].

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 = {'ignore_borders': FieldInfo(annotation=bool, required=False, default=True, description='Remove colonies touching image edges via ``clear_border()``. Recommended for grid-based colony counting to eliminate partial colonies at plate boundaries. Default: True.'), 'ignore_zeros': FieldInfo(annotation=bool, required=False, default=False, description='Exclude zero-intensity pixels from the mean calculation before computing the threshold. Enable for plates with black borders or masked regions. Default: False.')}

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.

class phenotypic.detect.MinimumDetector(*, ignore_zeros: bool = False, ignore_borders: bool = True)

Bases: ThresholdDetector

Detect colonies by thresholding at the intensity valley between two histogram peaks.

Locate the minimum intensity value (valley) between the two dominant peaks of the image histogram and set it as the threshold. The resulting binary mask places the colony–background boundary at the natural gap in the intensity distribution. For a full comparison of detection strategies see Detection Strategies Compared.

Best For:

• High-contrast plates where colony and background intensities form two distinct, well-separated histogram peaks.

• Standardised imaging setups producing consistently bimodal histograms across plates.

• Images where the intensity gap between colonies and agar is wide and the valley is unambiguous.

Consider Also:

• OtsuDetector when the histogram is bimodal but peaks are broad or partially overlapping.

• LiDetector when the histogram is unimodal or weakly bimodal and a cross-entropy criterion is more appropriate.

• HysteresisDetector when colony brightness varies across the plate and a single valley-based threshold under-segments faint regions.

Parameters:

• ignore_zeros (bool) – Exclude zero-intensity pixels from the histogram before locating the valley. Enable for plates with black borders or masked regions. Default: False.

• ignore_borders (bool) – Remove colonies touching image edges via clear_border(). Recommended for grid-based colony counting to eliminate partial colonies at plate boundaries. Default: True.

Returns:

Input image with objmask set to the binary colony mask and objmap set to labeled connected components.

Return type:

Image

Raises:

ValueError – If the histogram has no clear bimodal distribution and no valley can be identified.

See also

Tutorial 2: Detecting Colonies for a step-by-step tutorial on basic colony detection. How To: Choose a Detection Algorithm for guidance on selecting the right detector for your plate images. Detection Strategies Compared for an in-depth comparison of all thresholding strategies.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

ignore_borders: bool

ignore_zeros: bool

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].

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 = {'ignore_borders': FieldInfo(annotation=bool, required=False, default=True, description='Remove colonies touching image edges via ``clear_border()``. Recommended for grid-based colony counting to eliminate partial colonies at plate boundaries. Default: True.'), 'ignore_zeros': FieldInfo(annotation=bool, required=False, default=False, description='Exclude zero-intensity pixels from the histogram before locating the valley. Enable for plates with black borders or masked regions. Default: False.')}

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.

class phenotypic.detect.OtsuDetector(*, ignore_zeros: bool = False, ignore_borders: bool = True)

Bases: ThresholdDetector

Detect colonies by minimising intra-class variance of the intensity histogram.

Automatically compute a single global threshold that separates colony foreground from agar background by maximising the between-class intensity variance. The resulting binary mask cleanly segments plates whose histograms are bimodal. For a comparison of all available detection strategies see Detection Strategies Compared.

Best For:

• Plates imaged under standardised lighting where the intensity histogram shows two well-separated peaks.

• High-throughput screens with uniform agar colour and colony density.

• Clean plates with minimal dust, scratches, or condensation.

• Quick baseline detection requiring no parameter tuning.

Consider Also:

• TriangleDetector when colonies occupy a small fraction of the plate and the histogram is strongly skewed toward background.

• HysteresisDetector when colony intensity varies across the plate and a single threshold under-segments faint regions.

• WatershedDetector when touching colonies must be split into individually labelled objects.

Parameters:

• ignore_zeros (bool) – Exclude zero-intensity pixels from the histogram before computing the threshold. Enable for plates with black borders or masked regions. Default: False.

• ignore_borders (bool) – Remove colonies touching image edges via clear_border(). Recommended for grid-based colony counting to eliminate partial colonies at plate boundaries. Default: True.

Returns:

Input image with objmask set to the binary colony mask and objmap set to labeled connected components.

Return type:

Image

Raises:

ValueError – If threshold computation fails due to a degenerate histogram (e.g., all pixels share the same intensity value).

References

[1] N. Otsu, “A threshold selection method from gray-level histograms,” IEEE Trans. Syst., Man, Cybern., vol. 9, no. 1, pp. 62–66, 1979.

See also

Tutorial 2: Detecting Colonies for a step-by-step tutorial on basic colony detection. How To: Choose a Detection Algorithm for guidance on selecting the right detector for your plate images. Detection Strategies Compared for an in-depth comparison of all thresholding strategies.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

ignore_borders: bool

ignore_zeros: bool

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].

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 = {'ignore_borders': FieldInfo(annotation=bool, required=False, default=True, description='Remove colonies touching image edges via ``clear_border()``. Recommended for grid-based colony counting to eliminate partial colonies at plate boundaries. Default: True.'), 'ignore_zeros': FieldInfo(annotation=bool, required=False, default=False, description='Exclude zero-intensity pixels from the histogram before computing the threshold. Enable for plates with black borders or masked regions. Default: False.')}

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.

class phenotypic.detect.RankOtsuDetector(*, shape: Literal['square', 'diamond', 'disk'] = 'square', width: Annotated[int | None, TuneSpec(low=3, high=31, step=None, log=False, categories=None, tunable=True)] = None, ignore_zeros: bool = False)

Bases: ObjectDetector, FootprintMixin

Detect colonies by adaptive local Otsu thresholding within a sliding footprint.

Compute an Otsu threshold independently for every pixel using a local spatial neighbourhood, producing a per-pixel adaptive threshold map. This compensates for vignetting, lighting gradients, and spatially varying agar colour that cause a single global threshold to over- or under-segment parts of the plate. For a full comparison see Detection Strategies Compared.

Best For:

• Plates with vignetting, hot-spots, or centre-to-edge illumination gradients.

• Large-format plates (384-well or larger) where lighting uniformity is difficult to achieve.

• Images with spatially varying agar colour or reflectance that shifts across the plate surface.

Consider Also:

• OtsuDetector when illumination is uniform and a fast global threshold suffices.

• HysteresisDetector when colony brightness varies but spatial illumination is reasonably even.

• ChanVeseDetector when colonies have diffuse edges and region-based segmentation is more appropriate.

Parameters:

• shape (Literal['square', 'diamond', 'disk']) – Footprint shape for the local neighbourhood. Disk and diamond are rotationally symmetric; square is faster. Accepted values: 'square', 'diamond', 'disk'. Default: 'square'.

• width (Annotated[int | None, TuneSpec(low=3, high=31, step=None, log=False, categories=None, tunable=True)]) – Footprint width (or radius for disk/diamond) in pixels. Larger values smooth the threshold spatially (less local adaptation); smaller values track finer illumination changes but may over-segment. When None, auto-scales to min(height, width) // 8. Default: None.

• ignore_zeros (bool) – Exclude zero-intensity pixels from the local threshold computation. Enable for plates with black borders or masked regions. Default: False.

Returns:

Input image with objmask set to binary mask and objmap set to labeled connected components.

Return type:

Image

Raises:

ValueError – If shape is not one of the accepted values or width is not positive.

See also

Tutorial 2: Detecting Colonies

Step-by-step tutorial for basic colony detection.

How To: Choose a Detection Algorithm

Guide for selecting the right detector for your plate images.

Detection Strategies Compared

In-depth comparison of all detection strategies.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

ignore_zeros: bool

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].

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 = {'ignore_zeros': FieldInfo(annotation=bool, required=False, default=False, description='Exclude zero-intensity pixels from the local threshold computation. Enable for plates with black borders or masked regions. Default: False.'), 'shape': FieldInfo(annotation=Literal['square', 'diamond', 'disk'], required=False, default='square', description='Footprint shape for the local neighbourhood. Disk and diamond are rotationally symmetric; square is faster. Accepted'), 'width': FieldInfo(annotation=Union[int, NoneType], required=False, default=None, description='Footprint width (or radius for disk/diamond) in pixels. Larger values smooth the threshold spatially (less local adaptation); smaller values track finer illumination changes but may over-segment. When ``None``, auto-scales to ``min(height, width) // 8``. Default: None.', metadata=[TuneSpec(low=3, high=31, step=None, log=False, categories=None, tunable=True)])}

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.

shape: Literal['square', 'diamond', 'disk']

width: Annotated[int | None, TuneSpec(3, 31)]

class phenotypic.detect.RoundPeaksDetector(*, thresh_method: Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li'] = 'otsu', subtract_background: bool = True, remove_noise: bool = True, footprint_width: Annotated[int, Ge(ge=1), TuneSpec(low=4, high=20, step=None, log=False, categories=None, tunable=True)] = 6, noise_radius: Annotated[int, Ge(ge=1), TuneSpec(low=1, high=3, step=None, log=False, categories=None, tunable=True)] = 1, smoothing_sigma: Annotated[float, TuneSpec(low=0.0, high=5.0, step=None, log=False, categories=None, tunable=True)] = 2.0, min_peak_distance: Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = None, peak_prominence: Annotated[float | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = None, edge_refinement: bool = True, selection_mode: Literal['dominant', 'centered', 'regularized'] = 'dominant', split_merged: bool = True)

Bases: GridInferenceMixin, ObjectDetector

Detect round colonies on gridded plates by row/column peak analysis (gitter algorithm).

Threshold the plate image, project row and column intensity sums to detect periodic peaks, infer grid edges from peak positions, and assign one colony per grid cell. This implements the gitter algorithm optimised for pinned microbial culture plates with circular colonies arranged in regular arrays (96, 384, 1536 formats). For a full comparison see Detection Strategies Compared.

Best For:

• Pinned yeast or bacterial plates with colonies arranged in a regular rectangular grid.

• Plates where colony shape is approximately circular and colonies are well-separated or only mildly touching.

• High-throughput screens where automatic grid inference eliminates the need for manual grid specification.

• Workflows that require one-colony-per-cell assignment for downstream quantification.

Consider Also:

• SinePeakDetector when colony sizes are heterogeneous or some wells are empty, where rank cross-correlation locates the grid more robustly than direct peak finding.

• WatershedDetector when colonies are densely packed and touching but not arranged on a regular grid.

• FilamentousFungiDetector when colonies exhibit spreading, filamentous growth that violates the round-colony assumption.

• ManualGridPointDetector when colony positions are known a priori from robotic spotting coordinates.

Parameters:

• thresh_method (Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li']) – Thresholding method for binary mask creation. Accepted values: 'otsu' (default), 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li'. 'otsu' works well for most standardised imaging setups; 'local' adapts to spatial illumination gradients. Default: 'otsu'.

• subtract_background (bool) – Apply white tophat transform to remove uneven illumination before thresholding. Disable on plates with uniform lighting to save compute time. Default: True.

• remove_noise (bool) – Apply morphological opening to remove small noise artefacts from the binary mask. Default: True.

• footprint_width (Annotated[int, Ge(ge=1), TuneSpec(low=4, high=20, step=None, log=False, categories=None, tunable=True)]) – Width in pixels for the background subtraction kernel. When a GridImage is provided, an adaptive kernel sized to 1.5x colony spacing is used instead, making this a fallback for plain Image inputs. Typical range: 4–20. Default: 6.

• noise_radius (Annotated[int, Ge(ge=1), TuneSpec(low=1, high=3, step=None, log=False, categories=None, tunable=True)]) – Radius of the diamond structuring element for morphological noise removal. Increase for larger noise artefacts. Typical range: 1–3. Default: 1.

• smoothing_sigma (Annotated[float, TuneSpec(low=0.0, high=5.0, step=None, log=False, categories=None, tunable=True)]) – Gaussian sigma for smoothing row/column intensity profiles before peak detection. Higher values suppress noise but may merge adjacent colony peaks. Set to 0 to disable smoothing. Typical range: 0.0–5.0. Default: 2.0.

• min_peak_distance (Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Minimum pixel distance between detected peaks. When None, automatically estimated from grid dimensions. Default: None.

• peak_prominence (Annotated[float | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Minimum prominence threshold for peak detection. When None, auto-calculated as 0.1 × signal range. Higher values are more selective. Default: None.

• edge_refinement (bool) – Refine grid edges using weighted local intensity profiles for improved accuracy. Default: True.

• selection_mode (Literal['dominant', 'centered', 'regularized']) – Strategy for choosing one object per grid cell. "dominant" keeps the largest object by pixel count. "centered" keeps the object whose centroid is closest to the cell centre. "regularized" fits a global regular-grid model from median row/column centroids, then re-selects per cell — best for pinned arrays. Default: "dominant".

• split_merged (bool) – Pre-split merged colonies that span multiple grid cells using EDT watershed before grid assignment. Set to False when colonies are well-separated and splitting is unnecessary. Default: True.

Returns:

Input image with objmask set to a binary colony mask and objmap set to a labelled colony map with one label per grid cell.

Return type:

Image

Raises:

ValueError – If an invalid thresholding method is specified.

References

[1] O. Wagih and L. Parts, “gitter: A robust and accurate method for quantification of colony sizes from plate images,” G3 (Bethesda), vol. 4, no. 3, pp. 547–552, 2014. doi: 10.1534/g3.113.009431.

See also

Tutorial 2: Detecting Colonies

Step-by-step tutorial for basic colony detection.

How To: Choose a Detection Algorithm

Guide for selecting the right detector for your plate images.

Detection Strategies Compared

In-depth comparison of all detection strategies.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

edge_refinement: bool

footprint_width: Annotated[int, TuneSpec(4, 20)]

min_peak_distance: Annotated[int | None, TuneSpec(tunable=False)]

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].

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 = {'edge_refinement': FieldInfo(annotation=bool, required=False, default=True, description='Refine grid edges using weighted local intensity profiles for improved accuracy. Default: True.'), 'footprint_width': FieldInfo(annotation=int, required=False, default=6, description='Width in pixels for the background subtraction kernel. When a GridImage is provided, an adaptive kernel sized to 1.5x colony spacing is used instead, making this a fallback for plain Image inputs. Typical range: 4--20. Default: 6.', metadata=[Ge(ge=1), TuneSpec(low=4, high=20, step=None, log=False, categories=None, tunable=True)]), 'min_peak_distance': FieldInfo(annotation=Union[int, NoneType], required=False, default=None, description='Minimum pixel distance between detected peaks. When ``None``, automatically estimated from grid dimensions.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'noise_radius': FieldInfo(annotation=int, required=False, default=1, description='Radius of the diamond structuring element for morphological noise removal. Increase for larger noise artefacts. Typical range: 1--3. Default: 1.', metadata=[Ge(ge=1), TuneSpec(low=1, high=3, step=None, log=False, categories=None, tunable=True)]), 'peak_prominence': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Minimum prominence threshold for peak detection. When ``None``, auto-calculated as 0.1 × signal range. Higher values are more selective. Default: None.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'remove_noise': FieldInfo(annotation=bool, required=False, default=True, description='Apply morphological opening to remove small noise artefacts from the binary mask. Default: True.'), 'selection_mode': FieldInfo(annotation=Literal['dominant', 'centered', 'regularized'], required=False, default='dominant', description='Strategy for choosing one object per grid cell. ``"dominant"`` keeps the largest object by pixel count. ``"centered"`` keeps the object whose centroid is closest to the cell centre. ``"regularized"`` fits a global regular-grid model from median row/column centroids, then re-selects per cell — best for pinned arrays. Default: ``"dominant"``.'), 'smoothing_sigma': FieldInfo(annotation=float, required=False, default=2.0, description='Gaussian sigma for smoothing row/column intensity profiles before peak detection. Higher values suppress noise but may merge adjacent colony peaks. Set to 0 to disable smoothing. Typical range: 0.0--5.0. Default: 2.0.', metadata=[TuneSpec(low=0.0, high=5.0, step=None, log=False, categories=None, tunable=True)]), 'split_merged': FieldInfo(annotation=bool, required=False, default=True, description='Pre-split merged colonies that span multiple grid cells using EDT watershed before grid assignment. Set to False when colonies are well-separated and splitting is unnecessary.'), 'subtract_background': FieldInfo(annotation=bool, required=False, default=True, description='Apply white tophat transform to remove uneven illumination before thresholding. Disable on plates with uniform lighting to save compute time. Default: True.'), 'thresh_method': FieldInfo(annotation=Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li'], required=False, default='otsu', description="Thresholding method for binary mask creation. Accepted values: ``'otsu'`` (default), ``'mean'``, ``'local'``, ``'triangle'``, ``'minimum'``, ``'isodata'``, ``'li'``. ``'otsu'`` works well for most standardised imaging setups; ``'local'`` adapts to spatial illumination gradients. Default: ``'otsu'``.")}

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.

noise_radius: Annotated[int, TuneSpec(1, 3)]

peak_prominence: Annotated[float | None, TuneSpec(tunable=False)]

remove_noise: bool

selection_mode: Literal['dominant', 'centered', 'regularized']

smoothing_sigma: Annotated[float, TuneSpec(0.0, 5.0)]

split_merged: bool

subtract_background: bool

thresh_method: Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li']

class phenotypic.detect.SecondaryOtsuDetector

Bases: ThresholdDetector

Detect colonies by two-stage Otsu thresholding with per-object boundary refinement.

Apply an initial global Otsu threshold (or reuse an existing objmask), then re-threshold each detected object independently using its own intensity distribution. This sharpens colony boundaries on plates where colonies vary in brightness, removing soft halos while preserving colony cores. For a full comparison of detection strategies see Detection Strategies Compared.

Best For:

• Refining boundaries after an initial global threshold that leaves soft or blurry colony edges.

• Heterogeneous plates where colonies differ in pigmentation or optical density across the plate surface.

• Suppressing preprocessing halos that expand colony outlines beyond their true boundaries.

Consider Also:

• OtsuDetector when a single global threshold already produces clean colony boundaries.

• HysteresisDetector when colony intensity varies smoothly and dual-threshold expansion is more appropriate than per-object refinement.

• RankOtsuDetector when spatially varying illumination is the primary cause of boundary inaccuracy.

Returns:

Input image with objmask set to the refined binary colony mask and objmap set to labeled connected components.

Return type:

Image

References

[1] N. Otsu, “A threshold selection method from gray-level histograms,” IEEE Trans. Syst., Man, Cybern., vol. 9, no. 1, pp. 62–66, 1979.

See also

Tutorial 2: Detecting Colonies for a step-by-step tutorial on basic colony detection. How To: Choose a Detection Algorithm for guidance on selecting the right detector for your plate images. Detection Strategies Compared for an in-depth comparison of all thresholding strategies.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

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].

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 = {}

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.

class phenotypic.detect.SinePeakDetector(*, thresh_method: Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li'] = 'otsu', subtract_background: bool = True, remove_noise: bool = True, footprint_width: Annotated[int, Ge(ge=1), TuneSpec(low=4, high=20, step=None, log=False, categories=None, tunable=True)] = 6, noise_radius: Annotated[int, Ge(ge=1), TuneSpec(low=1, high=3, step=None, log=False, categories=None, tunable=True)] = 1, smoothing_sigma: Annotated[float, TuneSpec(low=0.0, high=5.0, step=None, log=False, categories=None, tunable=True)] = 2.0, min_peak_distance: Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = None, peak_prominence: Annotated[float | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = None, edge_refinement: bool = True, correlation_threshold: Annotated[float, TuneSpec(low=0.1, high=0.5, step=None, log=False, categories=None, tunable=True)] = 0.3, selection_mode: Literal['dominant', 'centered', 'regularized'] = 'dominant', split_merged: bool = True)

Bases: GridInferenceMixin, ObjectDetector

Detect colonies on gridded plates using sinusoidal cross-correlation peak finding.

Generate a sinusoidal template matching the expected colony periodicity, compute FFT-based rank (Spearman) cross-correlation against row and column projection signals, and select peaks from the correlation output to locate grid positions. Rank-based correlation is insensitive to outlier colonies and monotonic intensity transformations, making this more robust than direct peak finding on plates with heterogeneous growth. For a full comparison see Detection Strategies Compared.

Best For:

• Gridded plates (96-well, 384-well, pinned arrays) where colonies are arranged in a regular periodic pattern.

• Plates with heterogeneous colony sizes or uneven growth where rank-based correlation outperforms intensity-based peak finding.

• High-throughput batch processing of arrayed plates without manual grid specification.

• Plates where a small number of empty or very faint wells would mislead direct intensity peak detection.

Consider Also:

• RoundPeaksDetector for a simpler grid detector when colony intensities are uniform and direct peak finding suffices.

• OtsuDetector when colonies are not gridded and a global threshold is appropriate.

• RankOtsuDetector when spatial illumination variation is the primary challenge rather than grid localisation.

Parameters:

• thresh_method (Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li']) – Thresholding method for binary mask creation. Accepted values: 'otsu' (default), 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li'. 'otsu' works well for most standardised setups; 'local' adapts to spatial illumination gradients. Default: 'otsu'.

• subtract_background (bool) – Apply white tophat transform to remove uneven illumination before thresholding. Default: True.

• remove_noise (bool) – Apply morphological opening to remove small noise artefacts from the binary mask. Default: True.

• footprint_width (Annotated[int, Ge(ge=1), TuneSpec(low=4, high=20, step=None, log=False, categories=None, tunable=True)]) – Width in pixels for the background subtraction kernel. When a GridImage is provided, an adaptive kernel sized to 1.5x colony spacing is used instead, making this a fallback for plain Image inputs. Typical range: 4–20. Default: 6.

• noise_radius (Annotated[int, Ge(ge=1), TuneSpec(low=1, high=3, step=None, log=False, categories=None, tunable=True)]) – Radius of the diamond structuring element for morphological noise removal. Typical range: 1–3. Default: 1.

• smoothing_sigma (Annotated[float, TuneSpec(low=0.0, high=5.0, step=None, log=False, categories=None, tunable=True)]) – Gaussian standard deviation for smoothing row/column intensity profiles before cross-correlation. Higher values suppress noise but may merge adjacent peaks. Set to 0 to disable. Typical range: 0.0–5.0. Default: 2.0.

• min_peak_distance (Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Minimum pixel distance between detected peaks. When None, automatically estimated from grid dimensions. Default: None.

• peak_prominence (Annotated[float | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Minimum prominence for peak detection. When None, auto-calculated as 0.1 × signal range. Higher values are more selective. Default: None.

• edge_refinement (bool) – Refine grid edges using weighted local intensity profiles for improved accuracy. Default: True.

• correlation_threshold (Annotated[float, TuneSpec(low=0.1, high=0.5, step=None, log=False, categories=None, tunable=True)]) – Minimum normalised cross-correlation score for a sinusoidal template peak to be accepted as a valid grid position. Lower values recover grid cells with weak colony signal (sparse plates); higher values reject false grid positions at the cost of missing faint wells. Typical range: 0.1–0.5. Default: 0.3.

• selection_mode (Literal['dominant', 'centered', 'regularized']) – Strategy for choosing one object per grid cell. "dominant" keeps the largest object by pixel count. "centered" keeps the object whose centroid is closest to the cell centre. "regularized" fits a global regular-grid model from median centroids, then re-selects per cell — best for pinned arrays. Default: "dominant".

• split_merged (bool) – Pre-split merged colonies spanning multiple grid cells using EDT watershed before grid assignment. Set to False when colonies are well-separated. Default: True.

Returns:

Input image with objmask set to binary mask and objmap set to labeled connected components with one label per grid cell.

Return type:

Image

Raises:

ValueError – If thresh_method is not one of the accepted values.

References

[1] O. Wagih and L. Parts, “gitter: a robust and accurate method for quantification of colony sizes from plate images,” G3 (Bethesda), vol. 4, no. 3, pp. 547–552, 2014. doi: 10.1534/g3.113.009431.

See also

Tutorial 2: Detecting Colonies

Step-by-step tutorial for basic colony detection.

How To: Choose a Detection Algorithm

Guide for selecting the right detector for your plate images.

Detection Strategies Compared

In-depth comparison of all detection strategies.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

correlation_threshold: Annotated[float, TuneSpec(0.1, 0.5)]

edge_refinement: bool

footprint_width: Annotated[int, TuneSpec(4, 20)]

min_peak_distance: Annotated[int | None, TuneSpec(tunable=False)]

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].

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 = {'correlation_threshold': FieldInfo(annotation=float, required=False, default=0.3, description='Minimum normalised cross-correlation score for a sinusoidal template peak to be accepted as a valid grid position. Lower values recover grid cells with weak colony signal (sparse plates); higher values reject false grid positions at the cost of missing faint wells. Typical range: 0.1--0.5. Default: 0.3.', metadata=[TuneSpec(low=0.1, high=0.5, step=None, log=False, categories=None, tunable=True)]), 'edge_refinement': FieldInfo(annotation=bool, required=False, default=True, description='Refine grid edges using weighted local intensity profiles for improved accuracy. Default: True.'), 'footprint_width': FieldInfo(annotation=int, required=False, default=6, description='Width in pixels for the background subtraction kernel. When a GridImage is provided, an adaptive kernel sized to 1.5x colony spacing is used instead, making this a fallback for plain Image inputs. Typical range: 4--20. Default: 6.', metadata=[Ge(ge=1), TuneSpec(low=4, high=20, step=None, log=False, categories=None, tunable=True)]), 'min_peak_distance': FieldInfo(annotation=Union[int, NoneType], required=False, default=None, description='Minimum pixel distance between detected peaks. When ``None``, automatically estimated from grid dimensions.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'noise_radius': FieldInfo(annotation=int, required=False, default=1, description='Radius of the diamond structuring element for morphological noise removal. Typical range: 1--3. Default: 1.', metadata=[Ge(ge=1), TuneSpec(low=1, high=3, step=None, log=False, categories=None, tunable=True)]), 'peak_prominence': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Minimum prominence for peak detection. When ``None``, auto-calculated as 0.1 × signal range. Higher values are more selective. Default: None.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'remove_noise': FieldInfo(annotation=bool, required=False, default=True, description='Apply morphological opening to remove small noise artefacts from the binary mask. Default: True.'), 'selection_mode': FieldInfo(annotation=Literal['dominant', 'centered', 'regularized'], required=False, default='dominant', description='Strategy for choosing one object per grid cell. ``"dominant"`` keeps the largest object by pixel count. ``"centered"`` keeps the object whose centroid is closest to the cell centre. ``"regularized"`` fits a global regular-grid model from median centroids, then re-selects per cell — best for pinned arrays. Default: ``"dominant"``.'), 'smoothing_sigma': FieldInfo(annotation=float, required=False, default=2.0, description='Gaussian standard deviation for smoothing row/column intensity profiles before cross-correlation. Higher values suppress noise but may merge adjacent peaks. Set to 0 to disable. Typical range: 0.0--5.0. Default: 2.0.', metadata=[TuneSpec(low=0.0, high=5.0, step=None, log=False, categories=None, tunable=True)]), 'split_merged': FieldInfo(annotation=bool, required=False, default=True, description='Pre-split merged colonies spanning multiple grid cells using EDT watershed before grid assignment. Set to False when colonies are well-separated. Default: True.'), 'subtract_background': FieldInfo(annotation=bool, required=False, default=True, description='Apply white tophat transform to remove uneven illumination before thresholding. Default: True.'), 'thresh_method': FieldInfo(annotation=Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li'], required=False, default='otsu', description="Thresholding method for binary mask creation. Accepted values: ``'otsu'`` (default), ``'mean'``, ``'local'``, ``'triangle'``, ``'minimum'``, ``'isodata'``, ``'li'``. ``'otsu'`` works well for most standardised setups; ``'local'`` adapts to spatial illumination gradients. Default: ``'otsu'``.")}

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.

noise_radius: Annotated[int, TuneSpec(1, 3)]

peak_prominence: Annotated[float | None, TuneSpec(tunable=False)]

remove_noise: bool

selection_mode: Literal['dominant', 'centered', 'regularized']

smoothing_sigma: Annotated[float, TuneSpec(0.0, 5.0)]

split_merged: bool

subtract_background: bool

thresh_method: Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li']

class phenotypic.detect.TriangleDetector

Bases: ThresholdDetector

Detect colonies by triangle thresholding on skewed, background-dominant plate histograms.

Compute a threshold at the base of the triangle formed between the histogram peak, the minimum, and the maximum. This method excels when colonies occupy a small fraction of the plate so that the intensity histogram is strongly skewed toward background, capturing faint colonies that variance-based methods may miss. For a full comparison of detection strategies see Detection Strategies Compared.

Best For:

• Plates where colonies are sparse and the agar background dominates the intensity histogram.

• Faintly pigmented or translucent colonies that produce a small foreground peak relative to the background tail.

• Early time-point images where colony growth is minimal and most pixels represent agar background.

• Drop-out screens with many empty grid positions and few visible colonies.

Consider Also:

• OtsuDetector when colonies and background occupy roughly equal histogram areas, giving a balanced bimodal distribution.

• HysteresisDetector when colony brightness varies across the plate and a single threshold under-segments faint regions.

• UserThreshold when an empirically determined threshold is known to outperform automatic methods for your plate type.

Returns:

Input image with objmask set to the binary colony mask and objmap set to labeled connected components.

Return type:

Image

Raises:

ValueError – If threshold computation fails due to a degenerate histogram with insufficient intensity variation.

References

[1] G. W. Zack, W. E. Rogers, and S. A. Latt, “Automatic measurement of sister chromatid exchange frequency,” J. Histochem. Cytochem., vol. 25, no. 7, pp. 741–753, 1977.

See also

Tutorial 2: Detecting Colonies for a step-by-step tutorial on basic colony detection. How To: Choose a Detection Algorithm for guidance on selecting the right detector for your plate images. Detection Strategies Compared for an in-depth comparison of all thresholding strategies.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

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].

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 = {}

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.

class phenotypic.detect.UserThreshold(*, threshold: Annotated[float, TuneSpec(low=0.0, high=1.0, step=None, log=False, categories=None, tunable=True)] = 0.5, ignore_zeros: bool = False, ignore_borders: bool = True)

Bases: ThresholdDetector

Detect colonies by applying a user-specified intensity threshold.

Apply a fixed intensity cutoff to the plate detection matrix, producing a binary colony mask without any automatic threshold computation. This gives explicit control over detection sensitivity and is the preferred approach when empirical testing has identified an optimal threshold for a specific imaging setup. For a full comparison see Detection Strategies Compared.

Best For:

• Standardised imaging setups where the optimal threshold has been determined empirically and remains stable across plates.

• Overriding automatic methods (Otsu, triangle, etc.) that consistently over- or under-segment on a particular plate type.

• High-contrast plates where colonies are uniformly bright or dark relative to background and a single cutoff cleanly separates foreground from background.

• Reproducibility-critical workflows where a fixed numeric threshold eliminates variability introduced by automatic selection.

Consider Also:

• OtsuDetector when an automatic, parameter-free threshold is preferred and the histogram is bimodal.

• HysteresisDetector when colony intensity varies across the plate and a single threshold cannot capture all colonies.

• TriangleDetector when colonies are sparse and the histogram is skewed toward background.

Parameters:

• threshold (Annotated[float, TuneSpec(low=0.0, high=1.0, step=None, log=False, categories=None, tunable=True)]) – Intensity cutoff for binary segmentation; pixels with intensity >= threshold become colony (True), others background (False). This is inherently a user choice – there is no universal optimum, since it depends on the imaging setup and organism contrast. Valid range is bit-depth dependent: 0–255 for 8-bit, 0–65535 for 16-bit, 0.0–1.0 for float images; must be non-negative. Raising it is more conservative (fewer colonies, less noise); lowering it is more sensitive (more colonies, more noise). Default: 0.5. Start by inspecting the histogram for the valley between the background and colony peaks, then nudge it while watching whether faint colonies survive or agar texture leaks in.

• ignore_zeros (bool) – If True, exclude zero-intensity pixels from processing. Enable for plates with black borders or masked regions. Default: False.

• ignore_borders (bool) – If True (default), remove colonies touching image edges via clear_border(). Recommended for grid-based colony counting; disable to retain peripheral colonies.

Returns:

Input image with objmask set to a binary colony mask (True = colony, False = background). Assigning objmask rebuilds objmap from the binary mask via the accessor.

Return type:

Image

Raises:

ValueError – If threshold is negative.

See also

Tutorial 2: Detecting Colonies

Step-by-step tutorial for basic colony detection.

How To: Choose a Detection Algorithm

Guide for selecting the right detector for your plate images.

Detection Strategies Compared

In-depth comparison of all detection strategies.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

ignore_borders: bool

ignore_zeros: bool

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].

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 = {'ignore_borders': FieldInfo(annotation=bool, required=False, default=True, description='If True (default), remove colonies touching image edges via ``clear_border()``. Recommended for grid-based colony counting; disable to retain peripheral colonies.'), 'ignore_zeros': FieldInfo(annotation=bool, required=False, default=False, description='If True, exclude zero-intensity pixels from processing. Enable for plates with black borders or masked regions. Default: False.'), 'threshold': FieldInfo(annotation=float, required=False, default=0.5, description='Intensity cutoff for binary segmentation; pixels with intensity >= *threshold* become colony (True), others background (False). This is inherently a user choice -- there is no universal optimum, since it depends on the imaging setup and organism contrast. Valid range is bit-depth dependent: 0--255 for 8-bit, 0--65535 for 16-bit, 0.0--1.0 for float images; must be non-negative. Raising it is more conservative (fewer colonies, less noise); lowering it is more sensitive (more colonies, more noise). Default: 0.5. Start by inspecting the histogram for the valley between the background and colony peaks, then nudge it while watching whether faint colonies survive or agar texture leaks in.', metadata=[TuneSpec(low=0.0, high=1.0, step=None, log=False, categories=None, tunable=True)])}

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.

threshold: Annotated[float, TuneSpec(0.0, 1.0)]

class phenotypic.detect.WatershedDetector(*, footprint: WithJsonSchema(json_schema={'type': 'array', 'items': {}}, mode=None)] | int | None = None, min_size: Annotated[int, Ge(ge=1), TuneSpec(low=20, high=200, step=None, log=False, categories=None, tunable=True)] = 50, compactness: Annotated[float, Ge(ge=0.0), TuneSpec(low=0.0001, high=0.1, step=None, log=True, categories=None, tunable=True)] = 0.001, connectivity: Annotated[int, Ge(ge=1), Le(le=2), TuneSpec(low=None, high=None, step=None, log=False, categories=1, 2, tunable=True)] = 1, relabel: bool = True, ignore_zeros: bool = False)

Bases: ThresholdDetector

Detect and separate touching colonies by watershed segmentation on a distance-transform surface.

Thresholds the plate image to a binary mask, computes a Euclidean distance transform to locate colony centres, seeds markers at local maxima of that surface, and propagates labelled regions via compact watershed on the Sobel gradient. This region-growing approach individually labels colonies that are in physical contact — a scenario where global thresholding merges them into a single object. For a full comparison of detection strategies, see Detection Strategies Compared.

Best For:

• Dense plates where yeast or bacterial colonies touch or overlap and must be counted individually.

• Mutant-library plates with variable colony sizes where the distance transform naturally adapts seed placement to each colony’s footprint.

• Post-incubation plates where colony crowding is the primary segmentation challenge.

• Round, compact colonies on rich-media agar where compactness regularisation reinforces the expected shape.

Consider Also:

• OtsuDetector when colonies are well-separated and a simple global threshold suffices without region-growing.

• RoundPeaksDetector when colonies sit on a regular pinned grid and peak-based grid-cell assignment is more efficient.

• FilamentousFungiDetector when colonies exhibit spreading hyphal growth rather than compact morphology.

• CannyDetector when edge contrast is stronger than intensity contrast for delineating colony boundaries.

Parameters:

• footprint (Literal['auto'] | ~typing.Annotated[~numpy.ndarray, ~pydantic.functional_validators.BeforeValidator(func=~phenotypic.sdk_.typing_._coerce_to_ndarray, json_schema_input_type=PydanticUndefined), ~pydantic.functional_serializers.PlainSerializer(func=~phenotypic.sdk_.typing_._ndarray_to_list, return_type=list, when_used=always), ~pydantic.json_schema.WithJsonSchema(json_schema={'type': 'array', 'items': {}}, mode=None)] | int | None) – Structuring element for peak suppression on the distance-transform surface. 'auto' infers the diamond radius from grid spacing (GridImage only, half the well pitch); an int is expanded to a diamond of that radius in pixels; an ndarray supplies a custom binary footprint; None (default) lets scikit-image use a 1-px minimum distance, which typically over-seeds dense images. Larger footprints merge nearby peaks into fewer seeds; smaller footprints allow finer segmentation. Typical diamond radius range: 5–50 px. Default: None. A reasonable starting point for pinned-array plates is 'auto', which sets the radius to approximately half the well pitch.

• min_size (Annotated[int, Ge(ge=1), TuneSpec(low=20, high=200, step=None, log=False, categories=None, tunable=True)]) – Minimum object area in pixels. Objects smaller than this are removed from the binary mask before distance-transform computation (to reduce noise) and from the final labelled map. Typical range: 20–200 px, scaling with image resolution and colony size. Default: 50.

• compactness (Annotated[float, Ge(ge=0.0), TuneSpec(low=0.0001, high=0.1, step=None, log=True, categories=None, tunable=True)]) – Compact-watershed shape-regularisation penalty. Higher values produce more geometrically regular, convex segments; lower values let region boundaries follow the Sobel gradient freely, fitting irregular colony morphologies. Typical range: 0.0001–0.1. Increase toward 0.01–0.05 for round yeast colonies on rich agar; decrease toward 0.0001 for mucoid, sectored, or spreading morphologies. Default: 0.001.

• connectivity (Annotated[int, Ge(ge=1), Le(le=2), TuneSpec(low=None, high=None, step=None, log=False, categories=(1, 2), tunable=True)]) – Pixel connectivity for watershed flooding and final region labelling. 1 for 4-connectivity (default); 2 for 8-connectivity. 4-connectivity avoids false merges at diagonal colony contact points. Default: 1.

• relabel (bool) – When True (default), relabels segments to consecutive integer IDs starting at 1 after watershed. Set to False only when downstream code depends on the raw marker indices. Default: True.

• ignore_zeros (bool) – When True, Otsu threshold is computed only from non-zero pixels and zero-valued pixels are forced to background. Enable for images with black borders, scanner shadow, or pre-masked regions outside the plate area where structural zeros would otherwise bias the Otsu histogram. Default: False.

Returns:

Input image with objmap set to a labelled colony map where each colony receives a unique integer label, and objmask derived from the non-zero entries of that map.

Return type:

Image

References

[1] P. Neubert and P. Protzel, “Compact watershed and preemptive SLIC: On improving trade-offs of superpixel segmentation algorithms,” in Proc. 22nd Int. Conf. Pattern Recognit. (ICPR), Stockholm, Sweden, 2014, pp. 996–1001. [2] N. Otsu, “A threshold selection method from gray-level histograms,” IEEE Trans. Syst., Man, Cybern., vol. 9, no. 1, pp. 62–66, Jan. 1979.

See also

Tutorial 2: Detecting Colonies for a step-by-step tutorial demonstrating colony detection on real plate images. How To: Choose a Detection Algorithm for a guide to selecting the right detector for your plate images. Detection Strategies Compared for an in-depth comparison of all detection strategies and their failure modes.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

compactness: Annotated[float, TuneSpec(0.0001, 0.1, log=True)]

connectivity: Annotated[int, TuneSpec(categories=[1, 2])]

footprint: Literal['auto'] | NdArrayField | int | None

ignore_zeros: bool

min_size: Annotated[int, TuneSpec(20, 200)]

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].

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 = {'compactness': FieldInfo(annotation=float, required=False, default=0.001, description='Compact-watershed shape-regularisation penalty. Higher values produce more geometrically regular, convex segments; lower values let region boundaries follow the Sobel gradient freely, fitting irregular colony morphologies. Typical range: 0.0001--0.1. Increase toward 0.01--0.05 for round yeast colonies on rich agar; decrease toward 0.0001 for mucoid, sectored, or spreading morphologies. Default: 0.001.', metadata=[Ge(ge=0.0), TuneSpec(low=0.0001, high=0.1, step=None, log=True, categories=None, tunable=True)]), 'connectivity': FieldInfo(annotation=int, required=False, default=1, description='Pixel connectivity for watershed flooding and final region labelling. ``1`` for 4-connectivity (default); ``2`` for 8-connectivity. 4-connectivity avoids false merges at diagonal colony contact points. Default: 1.', metadata=[Ge(ge=1), Le(le=2), TuneSpec(low=None, high=None, step=None, log=False, categories=(1, 2), tunable=True)]), 'footprint': FieldInfo(annotation=Union[Literal['auto'], Annotated[ndarray, BeforeValidator, PlainSerializer, WithJsonSchema], int, NoneType], required=False, default=None, description="Structuring element for peak suppression on the distance-transform surface. ``'auto'`` infers the diamond radius from grid spacing (GridImage only, half the well pitch); an ``int`` is expanded to a diamond of that radius in pixels; an ``ndarray`` supplies a custom binary footprint; ``None`` (default) lets scikit-image use a 1-px minimum distance, which typically over-seeds dense images. Larger footprints merge nearby peaks into fewer seeds; smaller footprints allow finer segmentation. Typical diamond radius range: 5--50 px. Default: None. A reasonable starting point for pinned-array plates is ``'auto'``, which sets the radius to approximately half the well pitch."), 'ignore_zeros': FieldInfo(annotation=bool, required=False, default=False, description='When ``True``, Otsu threshold is computed only from non-zero pixels and zero-valued pixels are forced to background. Enable for images with black borders, scanner shadow, or pre-masked regions outside the plate area where structural zeros would otherwise bias the Otsu histogram. Default: False.'), 'min_size': FieldInfo(annotation=int, required=False, default=50, description='Minimum object area in pixels. Objects smaller than this are removed from the binary mask before distance-transform computation (to reduce noise) and from the final labelled map. Typical range: 20--200 px, scaling with image resolution and colony size. Default: 50.', metadata=[Ge(ge=1), TuneSpec(low=20, high=200, step=None, log=False, categories=None, tunable=True)]), 'relabel': FieldInfo(annotation=bool, required=False, default=True, description='When ``True`` (default), relabels segments to consecutive integer IDs starting at 1 after watershed. Set to ``False`` only when downstream code depends on the raw marker indices. Default: True.')}

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.

relabel: bool

class phenotypic.detect.YenDetector(*, ignore_zeros: bool = False, ignore_borders: bool = True)

Bases: ThresholdDetector

Detect colonies by maximising the correlation between the original and binarised image.

Compute a threshold that maximises the squared correlation coefficient between the original intensity image and its binarised version. Handles skewed histograms reliably, offering a middle ground between variance-based (Otsu) and entropy-based (Li) criteria. For a full comparison of detection strategies see Detection Strategies Compared.

Best For:

• High-contrast plates with clear intensity separation between colonies and agar background.

• Images with skewed histograms where one pixel class is substantially larger than the other.

• Exploratory analysis when unsure whether a variance-based or entropy-based criterion better fits the plate histogram.

Consider Also:

• OtsuDetector for a faster variance-based threshold when the histogram is balanced and clearly bimodal.

• LiDetector when the histogram is low-contrast or unimodal and entropy-based separation is more appropriate.

• TriangleDetector when colonies are very sparse and the histogram is strongly background-dominated.

Parameters:

• ignore_zeros (bool) – Exclude zero-intensity pixels from the histogram before computing the threshold. Enable for plates with black borders or masked regions. Default: False.

• ignore_borders (bool) – Remove colonies touching image edges via clear_border(). Recommended for grid-based colony counting to eliminate partial colonies at plate boundaries. Default: True.

Returns:

Input image with objmask set to the binary colony mask and objmap set to labeled connected components.

Return type:

Image

Raises:

ValueError – If threshold computation fails due to a degenerate histogram with insufficient intensity variation.

References

[1] J. C. Yen, F. J. Chang, and S. Chang, “A new criterion for automatic multilevel thresholding,” IEEE Trans. Image Process., vol. 4, no. 3, pp. 370–378, 1995.

See also

Tutorial 2: Detecting Colonies for a step-by-step tutorial on basic colony detection. How To: Choose a Detection Algorithm for guidance on selecting the right detector for your plate images. Detection Strategies Compared for an in-depth comparison of all thresholding strategies.

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

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

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

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

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

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

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:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  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

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 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

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

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__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.

__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:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__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

apply(image, inplace=False)

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

Return type:

Image

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

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:

• 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)

• 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)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

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

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

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

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

ignore_borders: bool

ignore_zeros: bool

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].

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 = {'ignore_borders': FieldInfo(annotation=bool, required=False, default=True, description='Remove colonies touching image edges via ``clear_border()``. Recommended for grid-based colony counting to eliminate partial colonies at plate boundaries. Default: True.'), 'ignore_zeros': FieldInfo(annotation=bool, required=False, default=False, description='Exclude zero-intensity pixels from the histogram before computing the threshold. Enable for plates with black borders or masked regions. Default: False.')}

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.

Subpackages

• phenotypic.detect.nn package