phenotypic.prefab

Prefab pipelines for fungal colony plate processing.

Ready-to-run chains of enhancement, detection, refinement, and measurement steps tuned for common agar plate scenarios. Includes watershed-heavy pipelines for clustered colonies, Otsu-based pipelines for clean backgrounds, grid-section pipelines for tiled inputs, and grid-aware Gitter-style processing for dense arrays.

Classes

HeavyWatershedPipeline	Detect and measure colonies using watershed segmentation for touching colonies.
HeavyOtsuPipeline	Detect and measure colonies using multi-stage Otsu thresholding with refinement.
GridSectionPipeline	Detect and measure colonies using per-section processing on grid plates.
HeavyRoundPeaksPipeline	Detect and measure round colonies using peak detection with full refinement.
RoundPeaksPipeline	Detect and measure round colonies using lightweight peak-based detection.
FilamentousFungiPipeline	Ready-to-use pipeline for filamentous fungi detection with DenoiseBlockMatch denoising and spatial measurements.
SpImagerPipeline	A prefabricated pipeline for light image processing task for images from the S&P Robotics Imager

class phenotypic.prefab.FilamentousFungiPipeline(bm3d_block_size: int = 4, bm3d_stage_arg: Literal['all_stages', 'hard_thresholding'] = 'all_stages', homo_sigma: float = 300.0, homo_gamma_low: float = 0.5, homo_gamma_high: float = 1.5, inoculum_min_diameter: float = 30.0, inoculum_max_diameter: float = 100.0, inoculum_detector: ObjectDetector | ImagePipeline | None = None, max_colony_radius_px: float = 250.0, min_branch_width_px: int = 3, ignore_borders: bool = True, edge_noise_threshold: float = 6.0, reconnection_tolerance: float = 2.5, max_gap_length: int = 30, border_margin_px: int = 50, frag_reach_px: int = 10, gap_crossing_penalty: float = 4.0, gauss_sigma: float | None = None, pct_min_wavelength: float | None = None, coherence_window_radius: int | None = None, mad_window: int | None = None, snr_margin: int | None = None, path_dilation_radius: int | None = None, tile_size: int | None = None, tile_overlap: int | None = None, texture_scale: int = 5, texture_warn: bool = False, benchmark: bool = False, verbose: bool = False)

Bases: PrefabPipeline

Ready-to-use pipeline for filamentous fungi detection with DenoiseBlockMatch denoising and spatial measurements.

Pipeline Steps:

1. DenoiseBlockMatch – Variance-stabilized BM3D denoising for Poisson-Gaussian noise removal on gray and detect_mat channels.

2. FlattenIllumination – Illumination normalization via frequency-domain filtering on detect_mat.

3. FilamentousFungiDetector – Two-stage detection (inoculum + dual-mask reconnection) with Euclidean Voronoi partition and Dijkstra branch reconnection.

Measurements:

• MeasureNeighborDist – Grid-level spatial statistics.

• MeasureShape – Per-colony shape descriptors.

• MeasureIntensity – Per-colony intensity statistics.

• MeasureTexture – Haralick texture features.

Parameters:

• bm3d_block_size (int) – BM3D patch size for denoising. Default 8.

• bm3d_stage_arg (Literal['all_stages', 'hard_thresholding']) – BM3D processing mode. 'all_stages' gives best quality; 'hard_thresholding' is faster.

• homo_sigma (float) – Gaussian cutoff sigma for the homomorphic filter.

• homo_gamma_low (float) – Gain for low-frequency (illumination) components.

• homo_gamma_high (float) – Gain for high-frequency (reflectance) components.

• inoculum_min_diameter (float) – Smallest expected inoculum diameter in pixels for the default InoculumDetector. Ignored when inoculum_detector is provided. Default 30.0.

• inoculum_max_diameter (float) – Largest expected inoculum diameter in pixels for the default InoculumDetector. Ignored when inoculum_detector is provided. Default 100.0.

• inoculum_detector (Union[ObjectDetector, ImagePipeline, None]) – Custom ObjectDetector or ImagePipeline that identifies fungal centers/nuclei. When None, builds a default pipeline of InoculumDetector + KeepSectionLargest.

• max_colony_radius_px (float) – Largest colony radius (in pixels) the detector should handle. Sizes scene-derived spatial parameters for this worst case. Default 250.

• min_branch_width_px (int) – Narrowest hyphal branch width (in pixels) to detect. Sizes signal-scale parameters. Default 3.

• ignore_borders (bool) – If True, drops objects touching the image border.

• edge_noise_threshold (float) – Noise threshold scaling factor for phase congruency edge detection.

• reconnection_tolerance (float) – IQR multiplier for path quality threshold calibration (higher = more permissive).

• max_gap_length (int) – Maximum acceptable length (pixels) of a suspicious cost stretch along a reconnection path.

• border_margin_px (int) – Border penalty buffer width in pixels.

• frag_reach_px (int) – Maximum 2D distance (pixels) from a fragment’s boundary to the nearest routable pixel; fragments more isolated than this are dropped before Dijkstra routing.

• gap_crossing_penalty (float) – Distance-gap penalty strength during Dijkstra routing.

• gauss_sigma (Optional[float]) – Override for SubtractGaussian sigma; None auto-derives.

• pct_min_wavelength (Optional[float]) – Override for log-Gabor minimum wavelength; None auto-derives.

• coherence_window_radius (Optional[int]) – Override for orientation coherence radius; None auto-derives.

• mad_window (Optional[int]) – Override for local MAD window (odd); None auto-derives.

• snr_margin (Optional[int]) – Override for SNR ring radius; None auto-derives.

• path_dilation_radius (Optional[int]) – Override for path dilation radius; None auto-derives.

• tile_size (Optional[int]) – Override for tile side length; None auto-derives.

• tile_overlap (Optional[int]) – Override for tile overlap; None auto-derives.

• texture_scale (int) – Scale parameter for Haralick texture features.

• texture_warn (bool) – Whether to warn on texture computation errors.

• benchmark (bool) – Enable per-step timing and memory benchmarks.

• verbose (bool) – Enable verbose logging during pipeline execution.

See also

Tutorial 10: Detecting Filamentous Fungi for a visual walkthrough of filamentous fungi detection. The Filamentous Fungi Detection Algorithm for the theory behind the reconnection algorithm. Prefab Pipelines: Which One for Which Organism for guidance on choosing a prefab pipeline.

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, benchmark: bool = False, verbose: bool = False) → PrefabPipeline

Deserialize a PrefabPipeline from JSON.

PrefabPipeline subclasses build their ops/meas inside __init__, so the base from_json (which passes ops= directly) would conflict. This override deserializes via ImagePipeline and re-tags the instance as the correct PrefabPipeline subclass.

Parameters:

• json_data (str | Path | dict) – A JSON string, path to a JSON file, or a pre-parsed dict.

• benchmark (bool) – Whether to enable benchmarking for the pipeline.

• verbose (bool) – Whether to enable verbose output.

Returns:

A PrefabPipeline (or subclass) instance with the loaded configuration.

Return type:

PrefabPipeline

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.

__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

__str__() → str

Return a JSON-formatted string representation of the pipeline.

The generated JSON string provides a structured representation of the object’s current state, including its operations and measurements. This output can be used for logging, debugging, or to recreate the object’s configuration in another context.

Returns:

A JSON-formatted string that encodes the object’s current configuration in a human-readable manner. This includes the phenotypic version, pipeline name, description, and the lists of operations and measurements.

Return type:

str

analyze(df: pandas.DataFrame) → pandas.DataFrame

Run the analysis chain (filters then model) against an aggregate frame.

Applies each filter in order — each transforms a DataFrame into another DataFrame — then runs the configured terminal model to produce a fit summary (typically one row per group).

The expected input is the post-applied, aggregated DataFrame the CLI seeds into measurements.parquet. analyze does not apply post itself: by default measure() runs self._post before returning, and the CLI applies post explicitly to a copy of the aggregated master before invoking analyze. Callers passing apply_post=False to measure() are responsible for applying post (or accepting that filters/model see pre-post data) before calling analyze.

Parameters:

df (pandas.DataFrame) – The aggregate measurements DataFrame.

Returns:

The model-fit output (one row per group, plus shared

MODEL_METRICS columns for fit quality).

Return type:

pd.DataFrame

Raises:

ValueError – If no model is configured. Configure via set_model() (or pass model= at construction).

apply(image: Image, inplace: bool = False, reset: bool | None = None) → GridImage | Image

The class provides an interface to process and apply a series of operations on an Image. The operations are maintained in a queue and executed sequentially when applied to the given Image.

Parameters:

• image (Image) – The arr Image to be processed. The type Image refers to an instance of the Image object to which transformations are applied.

• inplace (bool, optional) – A flag indicating whether to apply the transformations directly on the provided Image (True) or create a copy of the Image before performing transformations (False). Defaults to False.

• reset (bool, optional) – Whether to reset the image before applying the pipeline. If None (default), uses the pipeline’s reset setting from __init__. If explicitly set to True or False, overrides the pipeline setting.

Return type:

Union[GridImage, Image]

apply_and_measure(image: Image, inplace: bool = False, reset: bool | None = None, include_metadata: bool = True, apply_post: bool = True) → pd.DataFrame

Applies processing to the given image and measures the results.

This function first applies a processing method to the supplied image, adjusting it based on the given parameters. After processing, the resulting image is measured, and a DataFrame containing the measurement data is returned.

Parameters:

• image (Image) – The image to process and measure.

• inplace (bool) – Whether to modify the original image directly or work on a copy. Default is False.

• reset (bool, optional) – Whether to reset any previous processing on the image before applying the current method. If None (default), uses the pipeline’s reset setting. If explicitly set, overrides the pipeline setting.

• include_metadata (bool) – Whether to include metadata in the measurement results. Default is True.

• apply_post (bool) – Forwarded to measure(). When False, the returned DataFrame skips PostMeasurement ops. Defaults to True.

Returns:

A DataFrame containing measurement data for the processed image.

Return type:

pd.DataFrame

apply_napari(image: Image, inplace: bool = False, reset: bool | None = None, viewer: napari.Viewer | None = None) → NapariPipelineResult

Apply the pipeline and progressively add layers to a napari viewer.

Creates (or reuses) a napari viewer and adds the original image layers as a baseline, then adds the modified layer after each operation completes. Layer names follow the pattern {step:02d}_{OperationName}_{accessor}.

Parameters:

• image (Image) – The input image to process.

• inplace (bool) – If True the image is modified in place; otherwise a copy is made first. Defaults to False.

• reset (bool | None) – Whether to reset the image before applying operations. None (default) uses the pipeline-level setting.

• viewer (napari.Viewer | None) – An existing napari viewer to add layers to. If None (default), a new viewer is created.

Returns:

Named tuple with the final image and the napari viewer reference.

Return type:

NapariPipelineResult

Raises:

ImportError – If napari is not installed.

apply_with_intermediates(image: Image, inplace: bool = False, reset: bool | None = None, output_dir: str | Path | None = None, *, full_layers: bool = False) → IntermediateResult

Apply the pipeline and capture a snapshot of the image after each operation.

Behaves identically to apply() (respecting inplace, reset, benchmark timing, and verbose/tqdm progress) but additionally records the image state after every operation completes.

Parameters:

• image (Image) – The input image to process.

• inplace (bool) – If True the image is modified in place; otherwise a copy is made first. Defaults to False.

• reset (Optional[bool]) – Whether to reset the image before applying operations. None (default) uses the pipeline-level setting.

• output_dir (Optional[Union[str, Path]]) – Optional directory path. When provided, each intermediate image is persisted to an HDF5 file inside this directory (created automatically) and the corresponding dict value is set to None to conserve memory. When None, intermediates are kept in memory as Image copies.

• full_layers (bool) – When True and output_dir is set, each non-read-only operation’s full image state is written as a complete schema-v2 snapshot via save2hdf5 (all layers + class/grid metadata) instead of the delta layout. Used by the builder’s node-preview cache so any node’s HDF reconstructs a faithful Image/GridImage. Defaults to False.

Returns:

A named tuple containing the final image and a dictionary mapping operation names to intermediate snapshots (or None when output_dir is used).

Return type:

IntermediateResult

benchmark_results() → pandas.DataFrame

Return execution times and memory usage for operations and measurements.

This method should be called after applying the pipeline on an image to get the execution times and memory consumption of the different processes.

When an operation is itself an ImagePipelineCore (nested pipeline), its sub-operations are expanded as indented sub-rows beneath the parent entry with names like "ParentOp > ChildOp".

Returns:

A DataFrame with columns Process Type,

Process Name, Execution Time (s), Memory Delta (MB), and RSS After (MB).

Return type:

pd.DataFrame

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]

get_filters() → Dict[str, SetAnalyzer]

Get a copy of the analysis filter chain.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Ordered dict mapping filter names to

SetAnalyzer instances. Empty when no filters configured.

Return type:

Dict[str, SetAnalyzer]

get_meas() → Dict[str, MeasureFeatures]

Get a copy of the measurements dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping measurement names to

MeasureFeatures instances.

Return type:

Dict[str, MeasureFeatures]

get_model() → ModelFitter | None

Get the analysis endpoint model, if configured.

Returns:

The configured ModelFitter instance,

or None when no model is set.

Return type:

Optional[ModelFitter]

get_ops() → Dict[str, ImageOperation | ImagePipelineCore]

Get a copy of the operations dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping

operation names to ImageOperation instances (or nested pipelines).

Return type:

Dict[str, ImageOperation | ImagePipelineCore]

get_post() → Dict[str, PostMeasurement]

Get a copy of the post-measurement transforms dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping post-measurement

names to PostMeasurement instances.

Return type:

Dict[str, PostMeasurement]

get_qc() → List[QcRecipeEntry]

Get a copy of the QC config entry list.

Returns a shallow copy so callers cannot mutate the pipeline’s internal list by appending/removing. The entries themselves are shared (they are lightweight config dataclasses); run_qc and the GUI only read them and instantiate fresh checks from their params.

Returns:

Ordered QC config entries. Empty when no

checks are configured.

Return type:

List[QcRecipeEntry]

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

measure(image: Image, include_metadata: bool = True, apply_post: bool = True) → pd.DataFrame

Measures properties of a given image and optionally includes metadata. The method performs measurements using a set of predefined measurement operations. If benchmarking is enabled, the execution time of each measurement is recorded. When verbose mode is active, detailed logging of the measurement process is displayed. A progress bar is used to track progress if the tqdm library is available.

Parameters:

• image (Image) – The image object for which measurements are performed. It must support the info method and optionally a grid or objects attribute.

• include_metadata (bool, optional) – Indicates whether metadata should be included in the measurements. Defaults to True.

• apply_post (bool, optional) – Whether to apply the configured PostMeasurement operations to the merged frame before returning. Defaults to True. Pass False to obtain the pre-post merged DataFrame — useful when the caller (e.g. the CLI) wants to persist a clean copy and apply post separately.

Returns:

A DataFrame containing the results of all performed measurements combined

on the same index. Columns are ordered as [metadata] -> [measurements] -> [MetadataImage_] -> [info block]: user/experimental Metadata* columns first (in canonical REMBI order, present only when include_metadata is True), then the measurement columns, then the framework MetadataImage_* bookkeeping block (per-image provenance: UUID, ImageName, BitDepth, …), then the per-object image-info block (Object_Label followed by the Bbox_* / Grid_* geometry columns) last.

Return type:

pd.DataFrame

Raises:

Exception – An exception is raised if a measurement operation fails while being applied to the image.

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

set_filters(filters: List[SetAnalyzer] | Dict[str, SetAnalyzer]) → None

Set the analysis filter chain.

Parameters:

filters (List[SetAnalyzer] | Dict[str, SetAnalyzer]) – A list or dictionary of SetAnalyzer instances. If a list, class names (deduplicated by suffix) are used as keys.

Raises:

TypeError – If filters is neither a list nor a dictionary.

Return type:

None

set_meas(measurements: List[MeasureFeatures] | Dict[str, MeasureFeatures])

Sets the measurements to be used for further computation. The input can be either a list of MeasureFeatures objects or a dictionary with string keys and MeasureFeatures objects as values.

The method processes the given input to construct a dictionary mapping measurement names to MeasureFeatures instances. If a list is passed, unique class names of the MeasureFeatures instances in the list are used as keys.

Parameters:

measurements (List[MeasureFeatures] | Dict[str, MeasureFeatures]) – A collection of measurement features either as a list of MeasureFeatures objects, where class names are used as keys for dictionary creation, or as a dictionary where keys are predefined strings and values are MeasureFeatures objects.

Raises:

TypeError – If the measurements argument is neither a list nor a dictionary.

set_model(model: ModelFitter | None) → None

Set the analysis endpoint model.

Only one model can be configured per pipeline; assigning a new value replaces any prior model. Pass None to clear.

Parameters:

model (ModelFitter | None) – A ModelFitter instance, or None to clear.

Raises:

TypeError – If model is not a ModelFitter instance and not None.

Return type:

None

set_ops(ops: List[ImageOperation | ImagePipeline] | Dict[str, ImageOperation | ImagePipeline])

Sets the operations to be performed. The operations can be passed as either a list of ImageOperation or ImagePipeline instances or a dictionary mapping operation names to ImageOperation or ImagePipeline instances. This method ensures that each operation in the list has a unique name. Raises a TypeError if the input is neither a list nor a dictionary.

Parameters:

ops (List[ImageOperation | ImagePipeline] | Dict[str, ImageOperation | ImagePipeline]) – A list of ImageOperation or ImagePipeline objects, or a dictionary where keys are operation names and values are ImageOperation or ImagePipeline objects.

Raises:

TypeError – If the input is not a list or a dictionary.

set_post(post: List[PostMeasurement] | Dict[str, PostMeasurement])

Set the post-measurement transforms.

Parameters:

post (List[PostMeasurement] | Dict[str, PostMeasurement]) – A list or dictionary of PostMeasurement objects. If a list, class names are used as keys.

Raises:

TypeError – If post is neither a list nor a dictionary.

set_qc(qc: List[QcRecipeEntry] | None) → None

Set the QC config entry list.

Mirrors set_post() / set_filters() but the QC section is an ordered list of QcRecipeEntry (carrying stable instance_id/enabled metadata), not a name-keyed dict.

Parameters:

qc (List[QcRecipeEntry] | None) – A list of QcRecipeEntry, or None to clear.

Raises:

TypeError – If qc is neither a list nor None (raised by the _normalize_qc validator on assignment).

Return type:

None

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

Serialize the pipeline configuration to JSON format.

This method captures the pipeline’s operations and measurements. It excludes internal state (pydantic PrivateAttr fields) and pandas DataFrames to keep the serialization clean and focused on reproducible configuration.

Parameters:

filepath (str | Path | None) – Optional path to save the JSON. If None, returns JSON string. Can be a string or Path object.

Returns:

JSON string representation of the pipeline configuration.

Return type:

str

Example

Serialize a pipeline to JSON format:

>>> from phenotypic import ImagePipeline
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.measure import MeasureShape
>>> pipe = ImagePipeline(pipe_cfgs=[OtsuDetector()], meas=[MeasureShape()])
>>> json_str = pipe.to_json()
>>> pipe.to_json('my_pipeline')  # Save to typed config file

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.

benchmark: bool

property desc: str

Get pipeline description. Returns class docstring if no description set.

desc_value: str | None

filters: Dict[str, SetAnalyzer]

meas: Dict[str, MeasureFeatures]

model: ModelFitter | None

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True, 'validate_by_name': 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 = {'benchmark': FieldInfo(annotation=bool, required=False, default=False, description='Whether to enable execution time tracking for operations and measurements.'), 'desc_value': FieldInfo(annotation=Union[str, NoneType], required=False, default=None, alias='desc', alias_priority=2), 'filters': FieldInfo(annotation=Dict[str, SetAnalyzer], required=False, default={}), 'meas': FieldInfo(annotation=Dict[str, MeasureFeatures], required=False, default={}), 'model': FieldInfo(annotation=Union[ModelFitter, NoneType], required=False, default=None), 'name': FieldInfo(annotation=str, required=False, default_factory=<lambda>, description='A unique identifier for this pipeline. Defaults to a randomly generated UUID4 string if not provided during initialization.'), 'ncols': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'nrows': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'ops': FieldInfo(annotation=Dict[str, Union[ImageOperation, ImagePipelineCore]], required=False, default_factory=dict, alias_priority=2, validation_alias=AliasChoices(choices=['ops', 'pipe_cfgs'])), 'post': FieldInfo(annotation=Dict[str, PostMeasurement], required=False, default={}), 'qc': FieldInfo(annotation=List[QcRecipeEntry], required=False, default_factory=list, exclude=True), 'reset': FieldInfo(annotation=bool, required=False, default=False), 'verbose': FieldInfo(annotation=bool, required=False, default=False, description='Whether to enable verbose logging during pipeline execution.')}

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.

name: str

ncols: int | None

nrows: int | None

ops: Dict[str, ImageOperation | 'ImagePipelineCore']

post: Dict[str, PostMeasurement]

qc: List[QcRecipeEntry]

reset: bool

verbose: bool

class phenotypic.prefab.GridSectionPipeline(gaussian_sigma: int = 10, gaussian_mode: str = 'reflect', gaussian_truncate: float = 4.0, clahe_kernel_size: int | None = None, clahe_clip_limit: float = 0.01, median_mode: str = 'nearest', median_cval: float = 0.0, otsu_ignore_zeros: bool = True, otsu_ignore_borders: bool = True, border_remover_size: int | float | None = 50, circularity_cutoff: float = 0.6, small_object_min_size: int = 100, outlier_axis: int | None = None, outlier_stddev_multiplier: float = 1.5, outlier_max_coeff_variance: int = 1, aligner_axis: int = 0, aligner_mode: str = 'edge', section_blur_sigma: int = 5, section_blur_mode: str = 'reflect', section_blur_truncate: float = 4.0, section_median_mode: str = 'nearest', section_median_cval: float = 0.0, section_contrast_lower_percentile: int = 2, section_contrast_upper_percentile: int = 98, section_otsu_ignore_zeros: bool = True, section_otsu_ignore_borders: bool = True, grid_apply_reset_enh_matrix: bool = True, small_object_min_size_2: int = 100, color_white_chroma_max: float = 4.0, color_chroma_min: float = 8.0, color_include_XYZ: bool = False, texture_scale: int | list[int] = 5, texture_quant_lvl: ~typing.Literal[8, 16, 32, 64] = 32, texture_enhance: bool = False, texture_warn: bool = False, benchmark: bool = False, *, name: str = <factory>, desc: str | None = None, verbose: bool = False, reset: bool = False, nrows: int | None = None, ncols: int | None = None, ops: ~typing.Dict[str, ~phenotypic.abc_._image_operation.ImageOperation | ~phenotypic._core._pipeline_parts._image_pipeline_core.ImagePipelineCore] = <factory>, meas: ~typing.Dict[str, ~phenotypic.abc_._measure_features.MeasureFeatures] = {}, post: ~typing.Dict[str, ~phenotypic.abc_._post_measurement.PostMeasurement] = {}, filters: ~typing.Dict[str, ~phenotypic.analysis.abc_._set_analyzer.SetAnalyzer] = {}, model: ~phenotypic.analysis.abc_._model_fitter.ModelFitter | None = None, qc: ~typing.List[~phenotypic.sdk_._qc_recipe._recipe.QcRecipeEntry] = <factory>)

Bases: PrefabPipeline

Detect and measure colonies using per-section processing on grid plates.

Applies a sub-pipeline independently to each grid section, enabling section-specific thresholds and parameters. Useful when colony properties vary across the plate (e.g., different strains in different wells).

Steps:

1. GaussianBlur + EnhanceLocalContrast — global preprocessing

2. OtsuDetector — initial global detection

3. RemoveBorderObjects, SmallObjectRemover — cleanup

4. GridAligner — straighten the grid

5. GridApply — apply per-section sub-pipeline

6. ReduceSectionsByLine — final grid refinement

Measurements: MeasureShape, MeasureColor, MeasureIntensity, MeasureTexture.

Best For:

• Plates where colony properties vary significantly across wells.

• Pre-tiled grid sections that need independent processing.

• Experiments with different strains or conditions in each well.

Consider Also:

• HeavyOtsuPipeline when uniform processing across the plate is sufficient.

• RoundPeaksPipeline for a faster approach on consistent round colonies.

See also

Prefab Pipelines: Which One for Which Organism for guidance on choosing a prefab pipeline.

Parameters:

• gaussian_sigma (int)

• gaussian_mode (str)

• gaussian_truncate (float)

• clahe_kernel_size (int | None)

• clahe_clip_limit (float)

• median_mode (str)

• median_cval (float)

• otsu_ignore_zeros (bool)

• otsu_ignore_borders (bool)

• border_remover_size (int | float | None)

• circularity_cutoff (float)

• small_object_min_size (int)

• outlier_axis (int | None)

• outlier_stddev_multiplier (float)

• outlier_max_coeff_variance (int)

• aligner_axis (int)

• aligner_mode (str)

• section_blur_sigma (int)

• section_blur_mode (str)

• section_blur_truncate (float)

• section_median_mode (str)

• section_median_cval (float)

• section_contrast_lower_percentile (int)

• section_contrast_upper_percentile (int)

• section_otsu_ignore_zeros (bool)

• section_otsu_ignore_borders (bool)

• grid_apply_reset_enh_matrix (bool)

• small_object_min_size_2 (int)

• color_white_chroma_max (float)

• color_chroma_min (float)

• color_include_XYZ (bool)

• texture_scale (int | list[int])

• texture_quant_lvl (Literal[8, 16, 32, 64])

• texture_enhance (bool)

• texture_warn (bool)

• benchmark (bool)

• name (str)

• desc (str | None)

• verbose (bool)

• reset (bool)

• nrows (int | None)

• ncols (int | None)

• ops (Dict[str, ImageOperation | ImagePipelineCore])

• meas (Dict[str, MeasureFeatures])

• post (Dict[str, PostMeasurement])

• filters (Dict[str, SetAnalyzer])

• model (ModelFitter | None)

• qc (List[QcRecipeEntry])

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, benchmark: bool = False, verbose: bool = False) → PrefabPipeline

Deserialize a PrefabPipeline from JSON.

PrefabPipeline subclasses build their ops/meas inside __init__, so the base from_json (which passes ops= directly) would conflict. This override deserializes via ImagePipeline and re-tags the instance as the correct PrefabPipeline subclass.

Parameters:

• json_data (str | Path | dict) – A JSON string, path to a JSON file, or a pre-parsed dict.

• benchmark (bool) – Whether to enable benchmarking for the pipeline.

• verbose (bool) – Whether to enable verbose output.

Returns:

A PrefabPipeline (or subclass) instance with the loaded configuration.

Return type:

PrefabPipeline

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__(gaussian_sigma: int = 10, gaussian_mode: str = 'reflect', gaussian_truncate: float = 4.0, clahe_kernel_size: int | None = None, clahe_clip_limit: float = 0.01, median_mode: str = 'nearest', median_cval: float = 0.0, otsu_ignore_zeros: bool = True, otsu_ignore_borders: bool = True, border_remover_size: int | float | None = 50, circularity_cutoff: float = 0.6, small_object_min_size: int = 100, outlier_axis: int | None = None, outlier_stddev_multiplier: float = 1.5, outlier_max_coeff_variance: int = 1, aligner_axis: int = 0, aligner_mode: str = 'edge', section_blur_sigma: int = 5, section_blur_mode: str = 'reflect', section_blur_truncate: float = 4.0, section_median_mode: str = 'nearest', section_median_cval: float = 0.0, section_contrast_lower_percentile: int = 2, section_contrast_upper_percentile: int = 98, section_otsu_ignore_zeros: bool = True, section_otsu_ignore_borders: bool = True, grid_apply_reset_enh_matrix: bool = True, small_object_min_size_2: int = 100, color_white_chroma_max: float = 4.0, color_chroma_min: float = 8.0, color_include_XYZ: bool = False, texture_scale: int | list[int] = 5, texture_quant_lvl: Literal[8, 16, 32, 64] = 32, texture_enhance: bool = False, texture_warn: bool = False, benchmark: bool = False, **kwargs)

Initializes the GridSectionPipeline with customizable operations and measurements.

Parameters:

• gaussian_sigma (int) – Standard deviation for Gaussian kernel in initial smoothing.

• gaussian_mode (str) – Mode for handling image boundaries during Gaussian smoothing.

• gaussian_truncate (float) – Truncate the Gaussian kernel at this many standard deviations.

• clahe_kernel_size (int | None) – Size of kernel for EnhanceLocalContrast. If None, automatically calculated.

• clahe_clip_limit (float) – Contrast limit for EnhanceLocalContrast.

• median_mode (str) – Boundary mode for median filter.

• median_cval (float) – Constant value for median filter when mode is ‘constant’.

• otsu_ignore_zeros (bool) – Whether to ignore zero pixels in Otsu thresholding.

• otsu_ignore_borders (bool) – Whether to ignore border objects in Otsu detection.

• border_remover_size (int | float | None) – Size of border region where objects are removed.

• circularity_cutoff (float) – Minimum circularity threshold for objects to be retained.

• small_object_min_size (int) – Minimum size of objects to retain in first removal step.

• outlier_axis (Optional[int]) – Axis for outlier analysis. None for both, 0 for rows, 1 for columns.

• outlier_stddev_multiplier (float) – Multiplier for standard deviation in outlier detection.

• outlier_max_coeff_variance (int) – Maximum coefficient of variance for outlier analysis.

• aligner_axis (int) – Axis for grid alignment (0 for rows, 1 for columns).

• aligner_mode (str) – Mode for grid alignment rotation.

• section_blur_sigma (int) – Standard deviation for Gaussian kernel in section-level detection.

• section_blur_mode (str) – Mode for Gaussian smoothing in section-level detection.

• section_blur_truncate (float) – Truncate for Gaussian kernel in section-level detection.

• section_median_mode (str) – Boundary mode for median filter in section-level detection.

• section_median_cval (float) – Constant value for median filter in section-level detection.

• section_contrast_lower_percentile (int) – Lower percentile for contrast stretching in sections.

• section_contrast_upper_percentile (int) – Upper percentile for contrast stretching in sections.

• section_otsu_ignore_zeros (bool) – Whether to ignore zeros in section-level Otsu detection.

• section_otsu_ignore_borders (bool) – Whether to ignore borders in section-level Otsu detection.

• grid_apply_reset_enh_matrix (bool) – Whether to reset detect_mat before applying section-level pipeline.

• small_object_min_size_2 (int) – Minimum size of objects to retain in second removal step.

• color_white_chroma_max (float) – Maximum white chroma value for color measurement.

• color_chroma_min (float) – Minimum chroma value for color measurement.

• color_include_XYZ (bool) – Whether to include XYZ color space measurements.

• texture_scale (int | list[int]) – Scale parameter(s) for Haralick texture features.

• texture_quant_lvl (Literal[8, 16, 32, 64]) – Quantization level for texture computation.

• texture_enhance (bool) – Whether to enhance image before texture measurement.

• texture_warn (bool) – Whether to warn on texture computation errors.

• benchmark (bool) – Indicates whether benchmarking is enabled across the pipeline.

__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

__str__() → str

Return a JSON-formatted string representation of the pipeline.

The generated JSON string provides a structured representation of the object’s current state, including its operations and measurements. This output can be used for logging, debugging, or to recreate the object’s configuration in another context.

Returns:

A JSON-formatted string that encodes the object’s current configuration in a human-readable manner. This includes the phenotypic version, pipeline name, description, and the lists of operations and measurements.

Return type:

str

analyze(df: pandas.DataFrame) → pandas.DataFrame

Run the analysis chain (filters then model) against an aggregate frame.

Applies each filter in order — each transforms a DataFrame into another DataFrame — then runs the configured terminal model to produce a fit summary (typically one row per group).

The expected input is the post-applied, aggregated DataFrame the CLI seeds into measurements.parquet. analyze does not apply post itself: by default measure() runs self._post before returning, and the CLI applies post explicitly to a copy of the aggregated master before invoking analyze. Callers passing apply_post=False to measure() are responsible for applying post (or accepting that filters/model see pre-post data) before calling analyze.

Parameters:

df (pandas.DataFrame) – The aggregate measurements DataFrame.

Returns:

The model-fit output (one row per group, plus shared

MODEL_METRICS columns for fit quality).

Return type:

pd.DataFrame

Raises:

ValueError – If no model is configured. Configure via set_model() (or pass model= at construction).

apply(image: Image, inplace: bool = False, reset: bool | None = None) → GridImage | Image

The class provides an interface to process and apply a series of operations on an Image. The operations are maintained in a queue and executed sequentially when applied to the given Image.

Parameters:

• image (Image) – The arr Image to be processed. The type Image refers to an instance of the Image object to which transformations are applied.

• inplace (bool, optional) – A flag indicating whether to apply the transformations directly on the provided Image (True) or create a copy of the Image before performing transformations (False). Defaults to False.

• reset (bool, optional) – Whether to reset the image before applying the pipeline. If None (default), uses the pipeline’s reset setting from __init__. If explicitly set to True or False, overrides the pipeline setting.

Return type:

Union[GridImage, Image]

apply_and_measure(image: Image, inplace: bool = False, reset: bool | None = None, include_metadata: bool = True, apply_post: bool = True) → pd.DataFrame

Applies processing to the given image and measures the results.

This function first applies a processing method to the supplied image, adjusting it based on the given parameters. After processing, the resulting image is measured, and a DataFrame containing the measurement data is returned.

Parameters:

• image (Image) – The image to process and measure.

• inplace (bool) – Whether to modify the original image directly or work on a copy. Default is False.

• reset (bool, optional) – Whether to reset any previous processing on the image before applying the current method. If None (default), uses the pipeline’s reset setting. If explicitly set, overrides the pipeline setting.

• include_metadata (bool) – Whether to include metadata in the measurement results. Default is True.

• apply_post (bool) – Forwarded to measure(). When False, the returned DataFrame skips PostMeasurement ops. Defaults to True.

Returns:

A DataFrame containing measurement data for the processed image.

Return type:

pd.DataFrame

apply_napari(image: Image, inplace: bool = False, reset: bool | None = None, viewer: napari.Viewer | None = None) → NapariPipelineResult

Apply the pipeline and progressively add layers to a napari viewer.

Creates (or reuses) a napari viewer and adds the original image layers as a baseline, then adds the modified layer after each operation completes. Layer names follow the pattern {step:02d}_{OperationName}_{accessor}.

Parameters:

• image (Image) – The input image to process.

• inplace (bool) – If True the image is modified in place; otherwise a copy is made first. Defaults to False.

• reset (bool | None) – Whether to reset the image before applying operations. None (default) uses the pipeline-level setting.

• viewer (napari.Viewer | None) – An existing napari viewer to add layers to. If None (default), a new viewer is created.

Returns:

Named tuple with the final image and the napari viewer reference.

Return type:

NapariPipelineResult

Raises:

ImportError – If napari is not installed.

apply_with_intermediates(image: Image, inplace: bool = False, reset: bool | None = None, output_dir: str | Path | None = None, *, full_layers: bool = False) → IntermediateResult

Apply the pipeline and capture a snapshot of the image after each operation.

Behaves identically to apply() (respecting inplace, reset, benchmark timing, and verbose/tqdm progress) but additionally records the image state after every operation completes.

Parameters:

• image (Image) – The input image to process.

• inplace (bool) – If True the image is modified in place; otherwise a copy is made first. Defaults to False.

• reset (Optional[bool]) – Whether to reset the image before applying operations. None (default) uses the pipeline-level setting.

• output_dir (Optional[Union[str, Path]]) – Optional directory path. When provided, each intermediate image is persisted to an HDF5 file inside this directory (created automatically) and the corresponding dict value is set to None to conserve memory. When None, intermediates are kept in memory as Image copies.

• full_layers (bool) – When True and output_dir is set, each non-read-only operation’s full image state is written as a complete schema-v2 snapshot via save2hdf5 (all layers + class/grid metadata) instead of the delta layout. Used by the builder’s node-preview cache so any node’s HDF reconstructs a faithful Image/GridImage. Defaults to False.

Returns:

A named tuple containing the final image and a dictionary mapping operation names to intermediate snapshots (or None when output_dir is used).

Return type:

IntermediateResult

benchmark_results() → pandas.DataFrame

Return execution times and memory usage for operations and measurements.

This method should be called after applying the pipeline on an image to get the execution times and memory consumption of the different processes.

When an operation is itself an ImagePipelineCore (nested pipeline), its sub-operations are expanded as indented sub-rows beneath the parent entry with names like "ParentOp > ChildOp".

Returns:

A DataFrame with columns Process Type,

Process Name, Execution Time (s), Memory Delta (MB), and RSS After (MB).

Return type:

pd.DataFrame

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]

get_filters() → Dict[str, SetAnalyzer]

Get a copy of the analysis filter chain.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Ordered dict mapping filter names to

SetAnalyzer instances. Empty when no filters configured.

Return type:

Dict[str, SetAnalyzer]

get_meas() → Dict[str, MeasureFeatures]

Get a copy of the measurements dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping measurement names to

MeasureFeatures instances.

Return type:

Dict[str, MeasureFeatures]

get_model() → ModelFitter | None

Get the analysis endpoint model, if configured.

Returns:

The configured ModelFitter instance,

or None when no model is set.

Return type:

Optional[ModelFitter]

get_ops() → Dict[str, ImageOperation | ImagePipelineCore]

Get a copy of the operations dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping

operation names to ImageOperation instances (or nested pipelines).

Return type:

Dict[str, ImageOperation | ImagePipelineCore]

get_post() → Dict[str, PostMeasurement]

Get a copy of the post-measurement transforms dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping post-measurement

names to PostMeasurement instances.

Return type:

Dict[str, PostMeasurement]

get_qc() → List[QcRecipeEntry]

Get a copy of the QC config entry list.

Returns a shallow copy so callers cannot mutate the pipeline’s internal list by appending/removing. The entries themselves are shared (they are lightweight config dataclasses); run_qc and the GUI only read them and instantiate fresh checks from their params.

Returns:

Ordered QC config entries. Empty when no

checks are configured.

Return type:

List[QcRecipeEntry]

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

measure(image: Image, include_metadata: bool = True, apply_post: bool = True) → pd.DataFrame

Measures properties of a given image and optionally includes metadata. The method performs measurements using a set of predefined measurement operations. If benchmarking is enabled, the execution time of each measurement is recorded. When verbose mode is active, detailed logging of the measurement process is displayed. A progress bar is used to track progress if the tqdm library is available.

Parameters:

• image (Image) – The image object for which measurements are performed. It must support the info method and optionally a grid or objects attribute.

• include_metadata (bool, optional) – Indicates whether metadata should be included in the measurements. Defaults to True.

• apply_post (bool, optional) – Whether to apply the configured PostMeasurement operations to the merged frame before returning. Defaults to True. Pass False to obtain the pre-post merged DataFrame — useful when the caller (e.g. the CLI) wants to persist a clean copy and apply post separately.

Returns:

A DataFrame containing the results of all performed measurements combined

on the same index. Columns are ordered as [metadata] -> [measurements] -> [MetadataImage_] -> [info block]: user/experimental Metadata* columns first (in canonical REMBI order, present only when include_metadata is True), then the measurement columns, then the framework MetadataImage_* bookkeeping block (per-image provenance: UUID, ImageName, BitDepth, …), then the per-object image-info block (Object_Label followed by the Bbox_* / Grid_* geometry columns) last.

Return type:

pd.DataFrame

Raises:

Exception – An exception is raised if a measurement operation fails while being applied to the image.

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

set_filters(filters: List[SetAnalyzer] | Dict[str, SetAnalyzer]) → None

Set the analysis filter chain.

Parameters:

filters (List[SetAnalyzer] | Dict[str, SetAnalyzer]) – A list or dictionary of SetAnalyzer instances. If a list, class names (deduplicated by suffix) are used as keys.

Raises:

TypeError – If filters is neither a list nor a dictionary.

Return type:

None

set_meas(measurements: List[MeasureFeatures] | Dict[str, MeasureFeatures])

Sets the measurements to be used for further computation. The input can be either a list of MeasureFeatures objects or a dictionary with string keys and MeasureFeatures objects as values.

The method processes the given input to construct a dictionary mapping measurement names to MeasureFeatures instances. If a list is passed, unique class names of the MeasureFeatures instances in the list are used as keys.

Parameters:

measurements (List[MeasureFeatures] | Dict[str, MeasureFeatures]) – A collection of measurement features either as a list of MeasureFeatures objects, where class names are used as keys for dictionary creation, or as a dictionary where keys are predefined strings and values are MeasureFeatures objects.

Raises:

TypeError – If the measurements argument is neither a list nor a dictionary.

set_model(model: ModelFitter | None) → None

Set the analysis endpoint model.

Only one model can be configured per pipeline; assigning a new value replaces any prior model. Pass None to clear.

Parameters:

model (ModelFitter | None) – A ModelFitter instance, or None to clear.

Raises:

TypeError – If model is not a ModelFitter instance and not None.

Return type:

None

set_ops(ops: List[ImageOperation | ImagePipeline] | Dict[str, ImageOperation | ImagePipeline])

Sets the operations to be performed. The operations can be passed as either a list of ImageOperation or ImagePipeline instances or a dictionary mapping operation names to ImageOperation or ImagePipeline instances. This method ensures that each operation in the list has a unique name. Raises a TypeError if the input is neither a list nor a dictionary.

Parameters:

ops (List[ImageOperation | ImagePipeline] | Dict[str, ImageOperation | ImagePipeline]) – A list of ImageOperation or ImagePipeline objects, or a dictionary where keys are operation names and values are ImageOperation or ImagePipeline objects.

Raises:

TypeError – If the input is not a list or a dictionary.

set_post(post: List[PostMeasurement] | Dict[str, PostMeasurement])

Set the post-measurement transforms.

Parameters:

post (List[PostMeasurement] | Dict[str, PostMeasurement]) – A list or dictionary of PostMeasurement objects. If a list, class names are used as keys.

Raises:

TypeError – If post is neither a list nor a dictionary.

set_qc(qc: List[QcRecipeEntry] | None) → None

Set the QC config entry list.

Mirrors set_post() / set_filters() but the QC section is an ordered list of QcRecipeEntry (carrying stable instance_id/enabled metadata), not a name-keyed dict.

Parameters:

qc (List[QcRecipeEntry] | None) – A list of QcRecipeEntry, or None to clear.

Raises:

TypeError – If qc is neither a list nor None (raised by the _normalize_qc validator on assignment).

Return type:

None

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

Serialize the pipeline configuration to JSON format.

This method captures the pipeline’s operations and measurements. It excludes internal state (pydantic PrivateAttr fields) and pandas DataFrames to keep the serialization clean and focused on reproducible configuration.

Parameters:

filepath (str | Path | None) – Optional path to save the JSON. If None, returns JSON string. Can be a string or Path object.

Returns:

JSON string representation of the pipeline configuration.

Return type:

str

Example

Serialize a pipeline to JSON format:

>>> from phenotypic import ImagePipeline
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.measure import MeasureShape
>>> pipe = ImagePipeline(pipe_cfgs=[OtsuDetector()], meas=[MeasureShape()])
>>> json_str = pipe.to_json()
>>> pipe.to_json('my_pipeline')  # Save to typed config file

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.

benchmark: bool

property desc: str

Get pipeline description. Returns class docstring if no description set.

desc_value: str | None

filters: Dict[str, SetAnalyzer]

meas: Dict[str, MeasureFeatures]

model: ModelFitter | None

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True, 'validate_by_name': 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 = {'benchmark': FieldInfo(annotation=bool, required=False, default=False, description='Whether to enable execution time tracking for operations and measurements.'), 'desc_value': FieldInfo(annotation=Union[str, NoneType], required=False, default=None, alias='desc', alias_priority=2), 'filters': FieldInfo(annotation=Dict[str, SetAnalyzer], required=False, default={}), 'meas': FieldInfo(annotation=Dict[str, MeasureFeatures], required=False, default={}), 'model': FieldInfo(annotation=Union[ModelFitter, NoneType], required=False, default=None), 'name': FieldInfo(annotation=str, required=False, default_factory=<lambda>, description='A unique identifier for this pipeline. Defaults to a randomly generated UUID4 string if not provided during initialization.'), 'ncols': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'nrows': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'ops': FieldInfo(annotation=Dict[str, Union[ImageOperation, ImagePipelineCore]], required=False, default_factory=dict, alias_priority=2, validation_alias=AliasChoices(choices=['ops', 'pipe_cfgs'])), 'post': FieldInfo(annotation=Dict[str, PostMeasurement], required=False, default={}), 'qc': FieldInfo(annotation=List[QcRecipeEntry], required=False, default_factory=list, exclude=True), 'reset': FieldInfo(annotation=bool, required=False, default=False), 'verbose': FieldInfo(annotation=bool, required=False, default=False, description='Whether to enable verbose logging during pipeline execution.')}

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.

name: str

ncols: int | None

nrows: int | None

ops: Dict[str, ImageOperation | 'ImagePipelineCore']

post: Dict[str, PostMeasurement]

qc: List[QcRecipeEntry]

reset: bool

verbose: bool

class phenotypic.prefab.HeavyOtsuPipeline(gaussian_sigma: int = 5, gaussian_mode: str = 'reflect', gaussian_truncate: float = 4.0, otsu_ignore_zeros: bool = True, otsu_ignore_borders: bool = True, mask_opener_footprint: Literal['auto'] | ndarray | int | None = 'auto', border_remover_size: int = 1, small_object_min_size: int = 50, texture_scale: int = 5, texture_warn: bool = False, benchmark: bool = False, verbose: bool = False)

Bases: PrefabPipeline

Detect and measure colonies using multi-stage Otsu thresholding with refinement.

A robust general-purpose pipeline that chains preprocessing, Otsu detection, morphological cleanup, grid alignment, and re-detection for reliable colony segmentation on standard grid plates.

Steps:

1. GaussianBlur — smooth noise

2. EnhanceLocalContrast — boost local contrast

3. MedianFilter — remove residual speckle

4. FocusEdgeSobel — enhance colony edges

5. OtsuDetector — threshold-based detection

6. MaskOpening — smooth mask boundaries

7. RemoveBorderObjects — remove partial edge colonies

8. SmallObjectRemover — remove noise fragments

9. MaskFill — fill interior holes

10. GridOversizedObjectRemover — remove merged multi-well objects

11. ReduceSectionsByLine — keep one colony per well

12. GridAligner — straighten the grid

Measurements: MeasureShape, MeasureColor, MeasureTexture, MeasureIntensity.

Best For:

• Standard 96-well or 384-well yeast plates with clean backgrounds.

• General-purpose colony detection when you are unsure which detector to use.

• Plates with uniform illumination and bimodal intensity histograms.

Consider Also:

• HeavyWatershedPipeline when colonies touch or overlap.

• RoundPeaksPipeline for a faster, lighter approach on well-separated round colonies.

• FilamentousFungiPipeline for filamentous organisms.

See also

Tutorial 8: Using Prefab Pipelines for a visual comparison of prefab pipelines. Prefab Pipelines: Which One for Which Organism for guidance on choosing a prefab pipeline.

Parameters:

• gaussian_sigma (int)

• gaussian_mode (str)

• gaussian_truncate (float)

• otsu_ignore_zeros (bool)

• otsu_ignore_borders (bool)

• mask_opener_footprint (Literal['auto'] | ~numpy.ndarray | int | None)

• border_remover_size (int)

• small_object_min_size (int)

• texture_scale (int)

• texture_warn (bool)

• benchmark (bool)

• verbose (bool)

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, benchmark: bool = False, verbose: bool = False) → PrefabPipeline

Deserialize a PrefabPipeline from JSON.

PrefabPipeline subclasses build their ops/meas inside __init__, so the base from_json (which passes ops= directly) would conflict. This override deserializes via ImagePipeline and re-tags the instance as the correct PrefabPipeline subclass.

Parameters:

• json_data (str | Path | dict) – A JSON string, path to a JSON file, or a pre-parsed dict.

• benchmark (bool) – Whether to enable benchmarking for the pipeline.

• verbose (bool) – Whether to enable verbose output.

Returns:

A PrefabPipeline (or subclass) instance with the loaded configuration.

Return type:

PrefabPipeline

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__(gaussian_sigma: int = 5, gaussian_mode: str = 'reflect', gaussian_truncate: float = 4.0, otsu_ignore_zeros: bool = True, otsu_ignore_borders: bool = True, mask_opener_footprint: Literal['auto'] | ndarray | int | None = 'auto', border_remover_size: int = 1, small_object_min_size: int = 50, texture_scale: int = 5, texture_warn: bool = False, benchmark: bool = False, verbose: bool = False)

Initializes the object with a sequence of operations and measurements for image processing. The sequence includes smoothing, enhance, segmentation, border object removal, and various measurement steps for analyzing images. Customizable parameters allow for adjusting the processing pipeline for specific use cases such as image segmentation and feature extraction.

Parameters:

• gaussian_sigma (int) – Standard deviation for Gaussian kernel in smoothing.

• gaussian_mode (str) – Mode for handling image boundaries in Gaussian smoothing.

• gaussian_truncate (float) – Truncate filter at this many standard deviations.

• otsu_ignore_zeros (bool) – Whether to ignore zero pixels in Otsu thresholding.

• otsu_ignore_borders (bool) – Whether to ignore border objects in Otsu detection.

• mask_opener_footprint (Literal['auto'] | ~numpy.ndarray | int | None) – Structuring element for morphological opening.

• border_remover_size (int) – Size of border to remove objects from.

• small_object_min_size (int) – Minimum size of objects to retain.

• texture_scale (int) – Scale parameter for Haralick texture features.

• texture_warn (bool) – Whether to warn on texture computation errors.

• shape – Deprecated, use mask_opener_footprint.

• min_size – Deprecated, use small_object_min_size.

• border_size – Deprecated, use border_remover_size.

• benchmark (bool)

• verbose (bool)

__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

__str__() → str

Return a JSON-formatted string representation of the pipeline.

The generated JSON string provides a structured representation of the object’s current state, including its operations and measurements. This output can be used for logging, debugging, or to recreate the object’s configuration in another context.

Returns:

A JSON-formatted string that encodes the object’s current configuration in a human-readable manner. This includes the phenotypic version, pipeline name, description, and the lists of operations and measurements.

Return type:

str

analyze(df: pandas.DataFrame) → pandas.DataFrame

Run the analysis chain (filters then model) against an aggregate frame.

Applies each filter in order — each transforms a DataFrame into another DataFrame — then runs the configured terminal model to produce a fit summary (typically one row per group).

The expected input is the post-applied, aggregated DataFrame the CLI seeds into measurements.parquet. analyze does not apply post itself: by default measure() runs self._post before returning, and the CLI applies post explicitly to a copy of the aggregated master before invoking analyze. Callers passing apply_post=False to measure() are responsible for applying post (or accepting that filters/model see pre-post data) before calling analyze.

Parameters:

df (pandas.DataFrame) – The aggregate measurements DataFrame.

Returns:

The model-fit output (one row per group, plus shared

MODEL_METRICS columns for fit quality).

Return type:

pd.DataFrame

Raises:

ValueError – If no model is configured. Configure via set_model() (or pass model= at construction).

apply(image: Image, inplace: bool = False, reset: bool | None = None) → GridImage | Image

The class provides an interface to process and apply a series of operations on an Image. The operations are maintained in a queue and executed sequentially when applied to the given Image.

Parameters:

• image (Image) – The arr Image to be processed. The type Image refers to an instance of the Image object to which transformations are applied.

• inplace (bool, optional) – A flag indicating whether to apply the transformations directly on the provided Image (True) or create a copy of the Image before performing transformations (False). Defaults to False.

• reset (bool, optional) – Whether to reset the image before applying the pipeline. If None (default), uses the pipeline’s reset setting from __init__. If explicitly set to True or False, overrides the pipeline setting.

Return type:

Union[GridImage, Image]

apply_and_measure(image: Image, inplace: bool = False, reset: bool | None = None, include_metadata: bool = True, apply_post: bool = True) → pd.DataFrame

Applies processing to the given image and measures the results.

This function first applies a processing method to the supplied image, adjusting it based on the given parameters. After processing, the resulting image is measured, and a DataFrame containing the measurement data is returned.

Parameters:

• image (Image) – The image to process and measure.

• inplace (bool) – Whether to modify the original image directly or work on a copy. Default is False.

• reset (bool, optional) – Whether to reset any previous processing on the image before applying the current method. If None (default), uses the pipeline’s reset setting. If explicitly set, overrides the pipeline setting.

• include_metadata (bool) – Whether to include metadata in the measurement results. Default is True.

• apply_post (bool) – Forwarded to measure(). When False, the returned DataFrame skips PostMeasurement ops. Defaults to True.

Returns:

A DataFrame containing measurement data for the processed image.

Return type:

pd.DataFrame

apply_napari(image: Image, inplace: bool = False, reset: bool | None = None, viewer: napari.Viewer | None = None) → NapariPipelineResult

Apply the pipeline and progressively add layers to a napari viewer.

Creates (or reuses) a napari viewer and adds the original image layers as a baseline, then adds the modified layer after each operation completes. Layer names follow the pattern {step:02d}_{OperationName}_{accessor}.

Parameters:

• image (Image) – The input image to process.

• inplace (bool) – If True the image is modified in place; otherwise a copy is made first. Defaults to False.

• reset (bool | None) – Whether to reset the image before applying operations. None (default) uses the pipeline-level setting.

• viewer (napari.Viewer | None) – An existing napari viewer to add layers to. If None (default), a new viewer is created.

Returns:

Named tuple with the final image and the napari viewer reference.

Return type:

NapariPipelineResult

Raises:

ImportError – If napari is not installed.

apply_with_intermediates(image: Image, inplace: bool = False, reset: bool | None = None, output_dir: str | Path | None = None, *, full_layers: bool = False) → IntermediateResult

Apply the pipeline and capture a snapshot of the image after each operation.

Behaves identically to apply() (respecting inplace, reset, benchmark timing, and verbose/tqdm progress) but additionally records the image state after every operation completes.

Parameters:

• image (Image) – The input image to process.

• inplace (bool) – If True the image is modified in place; otherwise a copy is made first. Defaults to False.

• reset (Optional[bool]) – Whether to reset the image before applying operations. None (default) uses the pipeline-level setting.

• output_dir (Optional[Union[str, Path]]) – Optional directory path. When provided, each intermediate image is persisted to an HDF5 file inside this directory (created automatically) and the corresponding dict value is set to None to conserve memory. When None, intermediates are kept in memory as Image copies.

• full_layers (bool) – When True and output_dir is set, each non-read-only operation’s full image state is written as a complete schema-v2 snapshot via save2hdf5 (all layers + class/grid metadata) instead of the delta layout. Used by the builder’s node-preview cache so any node’s HDF reconstructs a faithful Image/GridImage. Defaults to False.

Returns:

A named tuple containing the final image and a dictionary mapping operation names to intermediate snapshots (or None when output_dir is used).

Return type:

IntermediateResult

benchmark_results() → pandas.DataFrame

Return execution times and memory usage for operations and measurements.

This method should be called after applying the pipeline on an image to get the execution times and memory consumption of the different processes.

When an operation is itself an ImagePipelineCore (nested pipeline), its sub-operations are expanded as indented sub-rows beneath the parent entry with names like "ParentOp > ChildOp".

Returns:

A DataFrame with columns Process Type,

Process Name, Execution Time (s), Memory Delta (MB), and RSS After (MB).

Return type:

pd.DataFrame

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]

get_filters() → Dict[str, SetAnalyzer]

Get a copy of the analysis filter chain.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Ordered dict mapping filter names to

SetAnalyzer instances. Empty when no filters configured.

Return type:

Dict[str, SetAnalyzer]

get_meas() → Dict[str, MeasureFeatures]

Get a copy of the measurements dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping measurement names to

MeasureFeatures instances.

Return type:

Dict[str, MeasureFeatures]

get_model() → ModelFitter | None

Get the analysis endpoint model, if configured.

Returns:

The configured ModelFitter instance,

or None when no model is set.

Return type:

Optional[ModelFitter]

get_ops() → Dict[str, ImageOperation | ImagePipelineCore]

Get a copy of the operations dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping

operation names to ImageOperation instances (or nested pipelines).

Return type:

Dict[str, ImageOperation | ImagePipelineCore]

get_post() → Dict[str, PostMeasurement]

Get a copy of the post-measurement transforms dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping post-measurement

names to PostMeasurement instances.

Return type:

Dict[str, PostMeasurement]

get_qc() → List[QcRecipeEntry]

Get a copy of the QC config entry list.

Returns a shallow copy so callers cannot mutate the pipeline’s internal list by appending/removing. The entries themselves are shared (they are lightweight config dataclasses); run_qc and the GUI only read them and instantiate fresh checks from their params.

Returns:

Ordered QC config entries. Empty when no

checks are configured.

Return type:

List[QcRecipeEntry]

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

measure(image: Image, include_metadata: bool = True, apply_post: bool = True) → pd.DataFrame

Measures properties of a given image and optionally includes metadata. The method performs measurements using a set of predefined measurement operations. If benchmarking is enabled, the execution time of each measurement is recorded. When verbose mode is active, detailed logging of the measurement process is displayed. A progress bar is used to track progress if the tqdm library is available.

Parameters:

• image (Image) – The image object for which measurements are performed. It must support the info method and optionally a grid or objects attribute.

• include_metadata (bool, optional) – Indicates whether metadata should be included in the measurements. Defaults to True.

• apply_post (bool, optional) – Whether to apply the configured PostMeasurement operations to the merged frame before returning. Defaults to True. Pass False to obtain the pre-post merged DataFrame — useful when the caller (e.g. the CLI) wants to persist a clean copy and apply post separately.

Returns:

A DataFrame containing the results of all performed measurements combined

on the same index. Columns are ordered as [metadata] -> [measurements] -> [MetadataImage_] -> [info block]: user/experimental Metadata* columns first (in canonical REMBI order, present only when include_metadata is True), then the measurement columns, then the framework MetadataImage_* bookkeeping block (per-image provenance: UUID, ImageName, BitDepth, …), then the per-object image-info block (Object_Label followed by the Bbox_* / Grid_* geometry columns) last.

Return type:

pd.DataFrame

Raises:

Exception – An exception is raised if a measurement operation fails while being applied to the image.

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

set_filters(filters: List[SetAnalyzer] | Dict[str, SetAnalyzer]) → None

Set the analysis filter chain.

Parameters:

filters (List[SetAnalyzer] | Dict[str, SetAnalyzer]) – A list or dictionary of SetAnalyzer instances. If a list, class names (deduplicated by suffix) are used as keys.

Raises:

TypeError – If filters is neither a list nor a dictionary.

Return type:

None

set_meas(measurements: List[MeasureFeatures] | Dict[str, MeasureFeatures])

Sets the measurements to be used for further computation. The input can be either a list of MeasureFeatures objects or a dictionary with string keys and MeasureFeatures objects as values.

The method processes the given input to construct a dictionary mapping measurement names to MeasureFeatures instances. If a list is passed, unique class names of the MeasureFeatures instances in the list are used as keys.

Parameters:

measurements (List[MeasureFeatures] | Dict[str, MeasureFeatures]) – A collection of measurement features either as a list of MeasureFeatures objects, where class names are used as keys for dictionary creation, or as a dictionary where keys are predefined strings and values are MeasureFeatures objects.

Raises:

TypeError – If the measurements argument is neither a list nor a dictionary.

set_model(model: ModelFitter | None) → None

Set the analysis endpoint model.

Only one model can be configured per pipeline; assigning a new value replaces any prior model. Pass None to clear.

Parameters:

model (ModelFitter | None) – A ModelFitter instance, or None to clear.

Raises:

TypeError – If model is not a ModelFitter instance and not None.

Return type:

None

set_ops(ops: List[ImageOperation | ImagePipeline] | Dict[str, ImageOperation | ImagePipeline])

Sets the operations to be performed. The operations can be passed as either a list of ImageOperation or ImagePipeline instances or a dictionary mapping operation names to ImageOperation or ImagePipeline instances. This method ensures that each operation in the list has a unique name. Raises a TypeError if the input is neither a list nor a dictionary.

Parameters:

ops (List[ImageOperation | ImagePipeline] | Dict[str, ImageOperation | ImagePipeline]) – A list of ImageOperation or ImagePipeline objects, or a dictionary where keys are operation names and values are ImageOperation or ImagePipeline objects.

Raises:

TypeError – If the input is not a list or a dictionary.

set_post(post: List[PostMeasurement] | Dict[str, PostMeasurement])

Set the post-measurement transforms.

Parameters:

post (List[PostMeasurement] | Dict[str, PostMeasurement]) – A list or dictionary of PostMeasurement objects. If a list, class names are used as keys.

Raises:

TypeError – If post is neither a list nor a dictionary.

set_qc(qc: List[QcRecipeEntry] | None) → None

Set the QC config entry list.

Mirrors set_post() / set_filters() but the QC section is an ordered list of QcRecipeEntry (carrying stable instance_id/enabled metadata), not a name-keyed dict.

Parameters:

qc (List[QcRecipeEntry] | None) – A list of QcRecipeEntry, or None to clear.

Raises:

TypeError – If qc is neither a list nor None (raised by the _normalize_qc validator on assignment).

Return type:

None

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

Serialize the pipeline configuration to JSON format.

This method captures the pipeline’s operations and measurements. It excludes internal state (pydantic PrivateAttr fields) and pandas DataFrames to keep the serialization clean and focused on reproducible configuration.

Parameters:

filepath (str | Path | None) – Optional path to save the JSON. If None, returns JSON string. Can be a string or Path object.

Returns:

JSON string representation of the pipeline configuration.

Return type:

str

Example

Serialize a pipeline to JSON format:

>>> from phenotypic import ImagePipeline
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.measure import MeasureShape
>>> pipe = ImagePipeline(pipe_cfgs=[OtsuDetector()], meas=[MeasureShape()])
>>> json_str = pipe.to_json()
>>> pipe.to_json('my_pipeline')  # Save to typed config file

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.

benchmark: bool

property desc: str

Get pipeline description. Returns class docstring if no description set.

desc_value: str | None

filters: Dict[str, SetAnalyzer]

meas: Dict[str, MeasureFeatures]

model: ModelFitter | None

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True, 'validate_by_name': 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 = {'benchmark': FieldInfo(annotation=bool, required=False, default=False, description='Whether to enable execution time tracking for operations and measurements.'), 'desc_value': FieldInfo(annotation=Union[str, NoneType], required=False, default=None, alias='desc', alias_priority=2), 'filters': FieldInfo(annotation=Dict[str, SetAnalyzer], required=False, default={}), 'meas': FieldInfo(annotation=Dict[str, MeasureFeatures], required=False, default={}), 'model': FieldInfo(annotation=Union[ModelFitter, NoneType], required=False, default=None), 'name': FieldInfo(annotation=str, required=False, default_factory=<lambda>, description='A unique identifier for this pipeline. Defaults to a randomly generated UUID4 string if not provided during initialization.'), 'ncols': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'nrows': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'ops': FieldInfo(annotation=Dict[str, Union[ImageOperation, ImagePipelineCore]], required=False, default_factory=dict, alias_priority=2, validation_alias=AliasChoices(choices=['ops', 'pipe_cfgs'])), 'post': FieldInfo(annotation=Dict[str, PostMeasurement], required=False, default={}), 'qc': FieldInfo(annotation=List[QcRecipeEntry], required=False, default_factory=list, exclude=True), 'reset': FieldInfo(annotation=bool, required=False, default=False), 'verbose': FieldInfo(annotation=bool, required=False, default=False, description='Whether to enable verbose logging during pipeline execution.')}

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.

name: str

ncols: int | None

nrows: int | None

ops: Dict[str, ImageOperation | 'ImagePipelineCore']

post: Dict[str, PostMeasurement]

qc: List[QcRecipeEntry]

reset: bool

verbose: bool

class phenotypic.prefab.HeavyRoundPeaksPipeline(bm3d_sigma: float = 0.02, bm3d_block_size: int = 8, bm3d_stage_arg: Literal['all_stages', 'hard_thresholding'] = 'all_stages', bm3d_clip: bool = True, clahe_kernel_size: int | None = None, clahe_clip_limit: float = 0.01, median_mode: Literal['nearest', 'reflect', 'constant', 'mirror', 'wrap'] = 'nearest', median_shape: Literal['disk', 'square', 'diamond'] = 'diamond', median_radius: int = 5, median_cval: float = 0.0, detector_thresh_method: Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li'] = 'otsu', detector_subtract_background: bool = True, detector_remove_noise: bool = True, detector_footprint_width: int = 6, detector_noise_radius: int = 1, detector_smoothing_sigma: float = 2.0, detector_min_peak_distance: int | None = None, detector_peak_prominence: float | None = None, detector_edge_refinement: bool = True, detector_selection_mode: Literal['dominant', 'centered', 'regularized'] = 'dominant', detector_split_merged: bool = True, grid_aligner_axis: int = 0, grid_aligner_mode: str = 'edge', mask_opener_footprint: Literal['auto', 'disk', 'square', 'diamond'] | ndarray | None = 'auto', mask_opener_width: int = 5, mask_opener_n_iter: int = 1, border_remover_size: int | float = 1, small_object_min_size: int = 50, mask_fill_structure: ndarray | None = None, mask_fill_origin: int = 0, texture_scale: int | list[int] = 5, texture_quant_lvl: Literal[8, 16, 32, 64] = 32, texture_enhance: bool = False, texture_warn: bool = False, color_white_chroma_max: float = 4.0, color_chroma_min: float = 8.0, color_include_XYZ: bool = False, benchmark: bool = False, verbose: bool = False)

Bases: PrefabPipeline

Detect and measure round colonies using peak detection with full refinement.

An extended version of RoundPeaksPipeline that adds BM3D denoising, EnhanceLocalContrast contrast enhancement, morphological refinement, grid alignment, and a second detection pass for improved accuracy on challenging plates.

Steps:

1. EnhanceBlockMatch — high-quality denoising

2. EnhanceLocalContrast — boost local contrast

3. MedianFilter — remove residual speckle

4. RoundPeaksDetector — first detection pass

5. MaskOpening, RemoveBorderObjects, SmallObjectRemover, MaskFill — cleanup

6. GridOversizedObjectRemover, ReduceSectionsByLine — grid refinement

7. GridAligner — straighten the grid

8. RoundPeaksDetector — second detection pass after alignment

9. RemoveBorderObjects, SmallObjectRemover, MaskFill — final cleanup

10. ReduceSectionsByLine — final grid refinement

Measurements: MeasureShape, MeasureColor, MeasureIntensity, MeasureTexture.

Best For:

• Round colonies on grid plates that need thorough refinement.

• Noisy or low-contrast plates where RoundPeaksPipeline produces too many artifacts.

• Plates with slight rotation that benefits from grid alignment between detection passes.

Consider Also:

• RoundPeaksPipeline for a faster, lighter version when plates are clean and well-lit.

• HeavyOtsuPipeline for general-purpose Otsu-based detection.

See also

Tutorial 8: Using Prefab Pipelines for a visual comparison of prefab pipelines.

Parameters:

• bm3d_sigma (float)

• bm3d_block_size (int)

• bm3d_stage_arg (Literal['all_stages', 'hard_thresholding'])

• bm3d_clip (bool)

• clahe_kernel_size (int | None)

• clahe_clip_limit (float)

• median_mode (Literal['nearest', 'reflect', 'constant', 'mirror', 'wrap'])

• median_shape (Literal['disk', 'square', 'diamond'])

• median_radius (int)

• median_cval (float)

• detector_thresh_method (Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li'])

• detector_subtract_background (bool)

• detector_remove_noise (bool)

• detector_footprint_width (int)

• detector_noise_radius (int)

• detector_smoothing_sigma (float)

• detector_min_peak_distance (int | None)

• detector_peak_prominence (float | None)

• detector_edge_refinement (bool)

• detector_selection_mode (Literal['dominant', 'centered', 'regularized'])

• detector_split_merged (bool)

• grid_aligner_axis (int)

• grid_aligner_mode (str)

• mask_opener_footprint (Literal['auto', 'disk', 'square', 'diamond'] | ~numpy.ndarray | None)

• mask_opener_width (int)

• mask_opener_n_iter (int)

• border_remover_size (int | float)

• small_object_min_size (int)

• mask_fill_structure (ndarray | None)

• mask_fill_origin (int)

• texture_scale (int | list[int])

• texture_quant_lvl (Literal[8, 16, 32, 64])

• texture_enhance (bool)

• texture_warn (bool)

• color_white_chroma_max (float)

• color_chroma_min (float)

• color_include_XYZ (bool)

• benchmark (bool)

• verbose (bool)

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, benchmark: bool = False, verbose: bool = False) → PrefabPipeline

Deserialize a PrefabPipeline from JSON.

PrefabPipeline subclasses build their ops/meas inside __init__, so the base from_json (which passes ops= directly) would conflict. This override deserializes via ImagePipeline and re-tags the instance as the correct PrefabPipeline subclass.

Parameters:

• json_data (str | Path | dict) – A JSON string, path to a JSON file, or a pre-parsed dict.

• benchmark (bool) – Whether to enable benchmarking for the pipeline.

• verbose (bool) – Whether to enable verbose output.

Returns:

A PrefabPipeline (or subclass) instance with the loaded configuration.

Return type:

PrefabPipeline

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__(bm3d_sigma: float = 0.02, bm3d_block_size: int = 8, bm3d_stage_arg: Literal['all_stages', 'hard_thresholding'] = 'all_stages', bm3d_clip: bool = True, clahe_kernel_size: int | None = None, clahe_clip_limit: float = 0.01, median_mode: Literal['nearest', 'reflect', 'constant', 'mirror', 'wrap'] = 'nearest', median_shape: Literal['disk', 'square', 'diamond'] = 'diamond', median_radius: int = 5, median_cval: float = 0.0, detector_thresh_method: Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li'] = 'otsu', detector_subtract_background: bool = True, detector_remove_noise: bool = True, detector_footprint_width: int = 6, detector_noise_radius: int = 1, detector_smoothing_sigma: float = 2.0, detector_min_peak_distance: int | None = None, detector_peak_prominence: float | None = None, detector_edge_refinement: bool = True, detector_selection_mode: Literal['dominant', 'centered', 'regularized'] = 'dominant', detector_split_merged: bool = True, grid_aligner_axis: int = 0, grid_aligner_mode: str = 'edge', mask_opener_footprint: Literal['auto', 'disk', 'square', 'diamond'] | ndarray | None = 'auto', mask_opener_width: int = 5, mask_opener_n_iter: int = 1, border_remover_size: int | float = 1, small_object_min_size: int = 50, mask_fill_structure: ndarray | None = None, mask_fill_origin: int = 0, texture_scale: int | list[int] = 5, texture_quant_lvl: Literal[8, 16, 32, 64] = 32, texture_enhance: bool = False, texture_warn: bool = False, color_white_chroma_max: float = 4.0, color_chroma_min: float = 8.0, color_include_XYZ: bool = False, benchmark: bool = False, verbose: bool = False) → None

Represents an image processing pipeline for analyzing microbe colonies on solid media agar. The pipeline includes preprocessing, detection, morphological refinement, and measurement steps.

Parameters:

• bm3d_sigma (float)

• bm3d_block_size (int)

• bm3d_stage_arg (Literal['all_stages', 'hard_thresholding'])

• bm3d_clip (bool)

• clahe_kernel_size (int | None)

• clahe_clip_limit (float)

• median_mode (Literal['nearest', 'reflect', 'constant', 'mirror', 'wrap'])

• median_shape (Literal['disk', 'square', 'diamond'])

• median_radius (int)

• median_cval (float)

• detector_thresh_method (Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata', 'li'])

• detector_subtract_background (bool)

• detector_remove_noise (bool)

• detector_footprint_width (int)

• detector_noise_radius (int)

• detector_smoothing_sigma (float)

• detector_min_peak_distance (int | None)

• detector_peak_prominence (float | None)

• detector_edge_refinement (bool)

• detector_selection_mode (Literal['dominant', 'centered', 'regularized'])

• detector_split_merged (bool)

• grid_aligner_axis (int)

• grid_aligner_mode (str)

• mask_opener_footprint (Literal['auto', 'disk', 'square', 'diamond'] | ~numpy.ndarray | None)

• mask_opener_width (int)

• mask_opener_n_iter (int)

• border_remover_size (int | float)

• small_object_min_size (int)

• mask_fill_structure (ndarray | None)

• mask_fill_origin (int)

• texture_scale (int | list[int])

• texture_quant_lvl (Literal[8, 16, 32, 64])

• texture_enhance (bool)

• texture_warn (bool)

• color_white_chroma_max (float)

• color_chroma_min (float)

• color_include_XYZ (bool)

• benchmark (bool)

• verbose (bool)

Return type:

None

bm3d_sigma

Controls the degree of noise reduction during BM3D denoising. Lower values retain more fine details, which might preserve subtle colony textures. Higher values remove more noise but may blur colony edges, affecting detection accuracy.

bm3d_block_size

Block size for BM3D denoising. Larger blocks capture more spatial context for noise estimation but increase computation time.

bm3d_stage_arg

Specifies the stage of BM3D denoising. “all_stages” applies more comprehensive denoising, potentially enhancing signal uniformity but may result in detail loss. “hard_thresholding” retains more high-frequency details but may leave more background noise intact.

bm3d_clip

Whether to clip denoised values to the [0, 1] range. Disabling may preserve subtle intensity variations but can produce out-of-range values.

clahe_kernel_size

Determines the size of the kernel used for local contrast enhancement via EnhanceLocalContrast. Larger sizes improve contrast over broader areas, but may over-amplify large background variations. Smaller sizes enhance localized details but may introduce noise.

clahe_clip_limit

Contrast clipping limit for EnhanceLocalContrast. Lower values produce more subtle enhancement; higher values amplify local contrast more aggressively, which can over-enhance noise.

median_mode

Boundary handling mode for median filtering. Controls how pixel values are extrapolated at image edges.

median_shape

Defines the morphological shape (“disk”, “square”, “diamond”) used for median filtering. The choice impacts how texture and artifacts are smoothed. For instance, “disk” may preserve radial features, whereas “square” provides edge-focused filtering.

median_radius

Dictates the width for median filtering. Smaller values enhance fine textural differences, whereas larger radii smooth broader regions, potentially affecting the precise detection of small colonies.

median_cval

Constant value used to pad image borders when median_mode is “constant”.

detector_thresh_method

Specifies the thresholding method for binary segmentation. “otsu” (default) applies global thresholding, “mean” uses mean-based threshold, “local” adapts to background variations, “li” uses Li’s iterative minimum cross-entropy method, and “triangle”, “minimum”, “isodata” offer alternative thresholding strategies.

detector_subtract_background

Toggles white tophat background subtraction before thresholding. Enabling this helps standardize varying lighting or agar density but may also obscure genuine gradients or subtle ring colonies.

detector_remove_noise

Sets whether morphological opening is applied to remove small noise artifacts. True ensures a cleaner output but may falsely discard tiny colonies. False retains all details, which can increase false-positive noise levels.

detector_footprint_width

Width in pixels for the morphological footprint used in background subtraction. Larger values remove larger-scale background variations but may erode colony edges.

detector_noise_radius

Radius in pixels for the morphological opening used to remove small noise artifacts. Larger values remove larger noise but may erode fine colony features.

detector_smoothing_sigma

Standard deviation for Gaussian smoothing of intensity profiles before peak detection. Higher values increase robustness to noise but may merge nearby peaks. Set to 0 to disable smoothing.

detector_min_peak_distance

Minimum distance between detected peaks in pixels. If None, automatically estimated from grid dimensions. Prevents detection of spurious peaks too close together.

detector_peak_prominence

Minimum prominence of peaks for detection. If None, automatically estimated from signal statistics. Higher values are more selective.

detector_edge_refinement

Whether to refine grid edges using local intensity profiles. Improves accuracy but adds computational cost.

detector_selection_mode

Strategy for selecting the primary grid when multiple candidate grids are found. “dominant” selects the grid with the most colonies, “centered” prefers grids near the image center, “regularized” balances colony count with spatial regularity.

detector_split_merged

Whether to attempt splitting merged colonies that appear as single large objects. Improves accuracy for dense plates where colonies grow together but may over-segment irregular colony morphologies.

grid_aligner_axis

Axis along which to align the grid (0 for rows, 1 for columns).

grid_aligner_mode

Padding mode used when rotating the image for alignment.

mask_opener_footprint

Describes the morphological shape for noise removal or mask refinement. “auto” lets the system adapt, named shapes (“disk”, “square”, “diamond”) use a standard footprint, an ndarray specifies a custom structuring element, and None disables opening.

mask_opener_width

Width of the structuring element when using a named shape for mask opening. Larger values remove more noise but may erode small colonies.

mask_opener_n_iter

Number of iterations for the morphological opening. More iterations apply stronger smoothing to the mask.

border_remover_size

Specifies the width of the border region to remove. Larger sizes eliminate edge artifacts and colonies cropped by image edges but may discard valid colonies near borders.

small_object_min_size

Specifies the size threshold for considering objects as colonies. Increasing this parameter reduces false detection of small artifacts but risks ignoring small colonies.

mask_fill_structure

Binary structuring element for hole filling in masks. Larger or more connected structures fill bigger holes. None uses the default cross-shaped element.

mask_fill_origin

Origin offset for the structuring element used in hole filling.

texture_scale

Defines the spatial scale(s) at which texture features are measured. Larger scales focus on macro-textures; smaller scales enhance granular detail assessment. Can be a list to compute features at multiple scales simultaneously.

texture_quant_lvl

Number of gray levels for quantizing intensity values in texture analysis. Higher values capture finer intensity distinctions but increase computation time and may be sensitive to noise.

texture_enhance

Whether to apply contrast enhancement to the texture input before computing GLCM features. May improve texture discrimination for low-contrast colonies.

texture_warn

Boolean that enables warnings when texture measurements may not be reliable. Use this to flag potential inconsistencies in the captured texture data or image quality issues.

color_white_chroma_max

Maximum chroma value for classifying a colony as white. Colonies with chroma below this threshold are labeled as white/achromatic.

color_chroma_min

Minimum chroma value for assigning a chromatic hue. Colonies with chroma below this value receive a neutral color classification.

color_include_XYZ

Whether to include CIE XYZ color space measurements in addition to the standard Lab and descriptive color features.

benchmark

Enables time benchmarking for each pipeline step. Useful for performance debugging but adds overhead to the computation.

verbose

Specifies whether to output detailed process information during execution. True provides step-by-step logs, which are useful for debugging, while False ensures silent execution suitable for batch processing.

__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

__str__() → str

Return a JSON-formatted string representation of the pipeline.

The generated JSON string provides a structured representation of the object’s current state, including its operations and measurements. This output can be used for logging, debugging, or to recreate the object’s configuration in another context.

Returns:

A JSON-formatted string that encodes the object’s current configuration in a human-readable manner. This includes the phenotypic version, pipeline name, description, and the lists of operations and measurements.

Return type:

str

analyze(df: pandas.DataFrame) → pandas.DataFrame

Run the analysis chain (filters then model) against an aggregate frame.

Applies each filter in order — each transforms a DataFrame into another DataFrame — then runs the configured terminal model to produce a fit summary (typically one row per group).

The expected input is the post-applied, aggregated DataFrame the CLI seeds into measurements.parquet. analyze does not apply post itself: by default measure() runs self._post before returning, and the CLI applies post explicitly to a copy of the aggregated master before invoking analyze. Callers passing apply_post=False to measure() are responsible for applying post (or accepting that filters/model see pre-post data) before calling analyze.

Parameters:

df (pandas.DataFrame) – The aggregate measurements DataFrame.

Returns:

The model-fit output (one row per group, plus shared

MODEL_METRICS columns for fit quality).

Return type:

pd.DataFrame

Raises:

ValueError – If no model is configured. Configure via set_model() (or pass model= at construction).

apply(image: Image, inplace: bool = False, reset: bool | None = None) → GridImage | Image

The class provides an interface to process and apply a series of operations on an Image. The operations are maintained in a queue and executed sequentially when applied to the given Image.

Parameters:

• image (Image) – The arr Image to be processed. The type Image refers to an instance of the Image object to which transformations are applied.

• inplace (bool, optional) – A flag indicating whether to apply the transformations directly on the provided Image (True) or create a copy of the Image before performing transformations (False). Defaults to False.

• reset (bool, optional) – Whether to reset the image before applying the pipeline. If None (default), uses the pipeline’s reset setting from __init__. If explicitly set to True or False, overrides the pipeline setting.

Return type:

Union[GridImage, Image]

apply_and_measure(image: Image, inplace: bool = False, reset: bool | None = None, include_metadata: bool = True, apply_post: bool = True) → pd.DataFrame

Applies processing to the given image and measures the results.

This function first applies a processing method to the supplied image, adjusting it based on the given parameters. After processing, the resulting image is measured, and a DataFrame containing the measurement data is returned.

Parameters:

• image (Image) – The image to process and measure.

• inplace (bool) – Whether to modify the original image directly or work on a copy. Default is False.

• reset (bool, optional) – Whether to reset any previous processing on the image before applying the current method. If None (default), uses the pipeline’s reset setting. If explicitly set, overrides the pipeline setting.

• include_metadata (bool) – Whether to include metadata in the measurement results. Default is True.

• apply_post (bool) – Forwarded to measure(). When False, the returned DataFrame skips PostMeasurement ops. Defaults to True.

Returns:

A DataFrame containing measurement data for the processed image.

Return type:

pd.DataFrame

apply_napari(image: Image, inplace: bool = False, reset: bool | None = None, viewer: napari.Viewer | None = None) → NapariPipelineResult

Apply the pipeline and progressively add layers to a napari viewer.

Creates (or reuses) a napari viewer and adds the original image layers as a baseline, then adds the modified layer after each operation completes. Layer names follow the pattern {step:02d}_{OperationName}_{accessor}.

Parameters:

• image (Image) – The input image to process.

• inplace (bool) – If True the image is modified in place; otherwise a copy is made first. Defaults to False.

• reset (bool | None) – Whether to reset the image before applying operations. None (default) uses the pipeline-level setting.

• viewer (napari.Viewer | None) – An existing napari viewer to add layers to. If None (default), a new viewer is created.

Returns:

Named tuple with the final image and the napari viewer reference.

Return type:

NapariPipelineResult

Raises:

ImportError – If napari is not installed.

apply_with_intermediates(image: Image, inplace: bool = False, reset: bool | None = None, output_dir: str | Path | None = None, *, full_layers: bool = False) → IntermediateResult

Apply the pipeline and capture a snapshot of the image after each operation.

Behaves identically to apply() (respecting inplace, reset, benchmark timing, and verbose/tqdm progress) but additionally records the image state after every operation completes.

Parameters:

• image (Image) – The input image to process.

• inplace (bool) – If True the image is modified in place; otherwise a copy is made first. Defaults to False.

• reset (Optional[bool]) – Whether to reset the image before applying operations. None (default) uses the pipeline-level setting.

• output_dir (Optional[Union[str, Path]]) – Optional directory path. When provided, each intermediate image is persisted to an HDF5 file inside this directory (created automatically) and the corresponding dict value is set to None to conserve memory. When None, intermediates are kept in memory as Image copies.

• full_layers (bool) – When True and output_dir is set, each non-read-only operation’s full image state is written as a complete schema-v2 snapshot via save2hdf5 (all layers + class/grid metadata) instead of the delta layout. Used by the builder’s node-preview cache so any node’s HDF reconstructs a faithful Image/GridImage. Defaults to False.

Returns:

A named tuple containing the final image and a dictionary mapping operation names to intermediate snapshots (or None when output_dir is used).

Return type:

IntermediateResult

benchmark_results() → pandas.DataFrame

Return execution times and memory usage for operations and measurements.

This method should be called after applying the pipeline on an image to get the execution times and memory consumption of the different processes.

When an operation is itself an ImagePipelineCore (nested pipeline), its sub-operations are expanded as indented sub-rows beneath the parent entry with names like "ParentOp > ChildOp".

Returns:

A DataFrame with columns Process Type,

Process Name, Execution Time (s), Memory Delta (MB), and RSS After (MB).

Return type:

pd.DataFrame

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]

get_filters() → Dict[str, SetAnalyzer]

Get a copy of the analysis filter chain.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Ordered dict mapping filter names to

SetAnalyzer instances. Empty when no filters configured.

Return type:

Dict[str, SetAnalyzer]

get_meas() → Dict[str, MeasureFeatures]

Get a copy of the measurements dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping measurement names to

MeasureFeatures instances.

Return type:

Dict[str, MeasureFeatures]

get_model() → ModelFitter | None

Get the analysis endpoint model, if configured.

Returns:

The configured ModelFitter instance,

or None when no model is set.

Return type:

Optional[ModelFitter]

get_ops() → Dict[str, ImageOperation | ImagePipelineCore]

Get a copy of the operations dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping

operation names to ImageOperation instances (or nested pipelines).

Return type:

Dict[str, ImageOperation | ImagePipelineCore]

get_post() → Dict[str, PostMeasurement]

Get a copy of the post-measurement transforms dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping post-measurement

names to PostMeasurement instances.

Return type:

Dict[str, PostMeasurement]

get_qc() → List[QcRecipeEntry]

Get a copy of the QC config entry list.

Returns a shallow copy so callers cannot mutate the pipeline’s internal list by appending/removing. The entries themselves are shared (they are lightweight config dataclasses); run_qc and the GUI only read them and instantiate fresh checks from their params.

Returns:

Ordered QC config entries. Empty when no

checks are configured.

Return type:

List[QcRecipeEntry]

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

measure(image: Image, include_metadata: bool = True, apply_post: bool = True) → pd.DataFrame

Measures properties of a given image and optionally includes metadata. The method performs measurements using a set of predefined measurement operations. If benchmarking is enabled, the execution time of each measurement is recorded. When verbose mode is active, detailed logging of the measurement process is displayed. A progress bar is used to track progress if the tqdm library is available.

Parameters:

• image (Image) – The image object for which measurements are performed. It must support the info method and optionally a grid or objects attribute.

• include_metadata (bool, optional) – Indicates whether metadata should be included in the measurements. Defaults to True.

• apply_post (bool, optional) – Whether to apply the configured PostMeasurement operations to the merged frame before returning. Defaults to True. Pass False to obtain the pre-post merged DataFrame — useful when the caller (e.g. the CLI) wants to persist a clean copy and apply post separately.

Returns:

A DataFrame containing the results of all performed measurements combined

on the same index. Columns are ordered as [metadata] -> [measurements] -> [MetadataImage_] -> [info block]: user/experimental Metadata* columns first (in canonical REMBI order, present only when include_metadata is True), then the measurement columns, then the framework MetadataImage_* bookkeeping block (per-image provenance: UUID, ImageName, BitDepth, …), then the per-object image-info block (Object_Label followed by the Bbox_* / Grid_* geometry columns) last.

Return type:

pd.DataFrame

Raises:

Exception – An exception is raised if a measurement operation fails while being applied to the image.

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

set_filters(filters: List[SetAnalyzer] | Dict[str, SetAnalyzer]) → None

Set the analysis filter chain.

Parameters:

filters (List[SetAnalyzer] | Dict[str, SetAnalyzer]) – A list or dictionary of SetAnalyzer instances. If a list, class names (deduplicated by suffix) are used as keys.

Raises:

TypeError – If filters is neither a list nor a dictionary.

Return type:

None

set_meas(measurements: List[MeasureFeatures] | Dict[str, MeasureFeatures])

Sets the measurements to be used for further computation. The input can be either a list of MeasureFeatures objects or a dictionary with string keys and MeasureFeatures objects as values.

The method processes the given input to construct a dictionary mapping measurement names to MeasureFeatures instances. If a list is passed, unique class names of the MeasureFeatures instances in the list are used as keys.

Parameters:

measurements (List[MeasureFeatures] | Dict[str, MeasureFeatures]) – A collection of measurement features either as a list of MeasureFeatures objects, where class names are used as keys for dictionary creation, or as a dictionary where keys are predefined strings and values are MeasureFeatures objects.

Raises:

TypeError – If the measurements argument is neither a list nor a dictionary.

set_model(model: ModelFitter | None) → None

Set the analysis endpoint model.

Only one model can be configured per pipeline; assigning a new value replaces any prior model. Pass None to clear.

Parameters:

model (ModelFitter | None) – A ModelFitter instance, or None to clear.

Raises:

TypeError – If model is not a ModelFitter instance and not None.

Return type:

None

set_ops(ops: List[ImageOperation | ImagePipeline] | Dict[str, ImageOperation | ImagePipeline])

Sets the operations to be performed. The operations can be passed as either a list of ImageOperation or ImagePipeline instances or a dictionary mapping operation names to ImageOperation or ImagePipeline instances. This method ensures that each operation in the list has a unique name. Raises a TypeError if the input is neither a list nor a dictionary.

Parameters:

ops (List[ImageOperation | ImagePipeline] | Dict[str, ImageOperation | ImagePipeline]) – A list of ImageOperation or ImagePipeline objects, or a dictionary where keys are operation names and values are ImageOperation or ImagePipeline objects.

Raises:

TypeError – If the input is not a list or a dictionary.

set_post(post: List[PostMeasurement] | Dict[str, PostMeasurement])

Set the post-measurement transforms.

Parameters:

post (List[PostMeasurement] | Dict[str, PostMeasurement]) – A list or dictionary of PostMeasurement objects. If a list, class names are used as keys.

Raises:

TypeError – If post is neither a list nor a dictionary.

set_qc(qc: List[QcRecipeEntry] | None) → None

Set the QC config entry list.

Mirrors set_post() / set_filters() but the QC section is an ordered list of QcRecipeEntry (carrying stable instance_id/enabled metadata), not a name-keyed dict.

Parameters:

qc (List[QcRecipeEntry] | None) – A list of QcRecipeEntry, or None to clear.

Raises:

TypeError – If qc is neither a list nor None (raised by the _normalize_qc validator on assignment).

Return type:

None

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

Serialize the pipeline configuration to JSON format.

This method captures the pipeline’s operations and measurements. It excludes internal state (pydantic PrivateAttr fields) and pandas DataFrames to keep the serialization clean and focused on reproducible configuration.

Parameters:

filepath (str | Path | None) – Optional path to save the JSON. If None, returns JSON string. Can be a string or Path object.

Returns:

JSON string representation of the pipeline configuration.

Return type:

str

Example

Serialize a pipeline to JSON format:

>>> from phenotypic import ImagePipeline
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.measure import MeasureShape
>>> pipe = ImagePipeline(pipe_cfgs=[OtsuDetector()], meas=[MeasureShape()])
>>> json_str = pipe.to_json()
>>> pipe.to_json('my_pipeline')  # Save to typed config file

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.

benchmark: bool

property desc: str

Get pipeline description. Returns class docstring if no description set.

desc_value: str | None

filters: Dict[str, SetAnalyzer]

meas: Dict[str, MeasureFeatures]

model: ModelFitter | None

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True, 'validate_by_name': 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 = {'benchmark': FieldInfo(annotation=bool, required=False, default=False, description='Whether to enable execution time tracking for operations and measurements.'), 'desc_value': FieldInfo(annotation=Union[str, NoneType], required=False, default=None, alias='desc', alias_priority=2), 'filters': FieldInfo(annotation=Dict[str, SetAnalyzer], required=False, default={}), 'meas': FieldInfo(annotation=Dict[str, MeasureFeatures], required=False, default={}), 'model': FieldInfo(annotation=Union[ModelFitter, NoneType], required=False, default=None), 'name': FieldInfo(annotation=str, required=False, default_factory=<lambda>, description='A unique identifier for this pipeline. Defaults to a randomly generated UUID4 string if not provided during initialization.'), 'ncols': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'nrows': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'ops': FieldInfo(annotation=Dict[str, Union[ImageOperation, ImagePipelineCore]], required=False, default_factory=dict, alias_priority=2, validation_alias=AliasChoices(choices=['ops', 'pipe_cfgs'])), 'post': FieldInfo(annotation=Dict[str, PostMeasurement], required=False, default={}), 'qc': FieldInfo(annotation=List[QcRecipeEntry], required=False, default_factory=list, exclude=True), 'reset': FieldInfo(annotation=bool, required=False, default=False), 'verbose': FieldInfo(annotation=bool, required=False, default=False, description='Whether to enable verbose logging during pipeline execution.')}

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.

name: str

ncols: int | None

nrows: int | None

ops: Dict[str, ImageOperation | 'ImagePipelineCore']

post: Dict[str, PostMeasurement]

qc: List[QcRecipeEntry]

reset: bool

verbose: bool

class phenotypic.prefab.HeavyWatershedPipeline(gaussian_sigma: int = 5, gaussian_mode: str = 'reflect', gaussian_truncate: float = 4.0, watershed_footprint: ~typing.Literal['auto'] | ~numpy.ndarray | int | None = None, watershed_min_size: int = 50, watershed_compactness: float = 0.001, watershed_connectivity: int = 1, watershed_relabel: bool = True, watershed_ignore_zeros: bool = True, border_remover_size: int = 25, circularity_cutoff: float = 0.5, texture_scale: int = 5, texture_warn: bool = False, benchmark: bool = False, *, name: str = <factory>, desc: str | None = None, verbose: bool = False, reset: bool = False, nrows: int | None = None, ncols: int | None = None, ops: ~typing.Dict[str, ~phenotypic.abc_._image_operation.ImageOperation | ~phenotypic._core._pipeline_parts._image_pipeline_core.ImagePipelineCore] = <factory>, meas: ~typing.Dict[str, ~phenotypic.abc_._measure_features.MeasureFeatures] = {}, post: ~typing.Dict[str, ~phenotypic.abc_._post_measurement.PostMeasurement] = {}, filters: ~typing.Dict[str, ~phenotypic.analysis.abc_._set_analyzer.SetAnalyzer] = {}, model: ~phenotypic.analysis.abc_._model_fitter.ModelFitter | None = None, qc: ~typing.List[~phenotypic.sdk_._qc_recipe._recipe.QcRecipeEntry] = <factory>)

Bases: PrefabPipeline

Detect and measure colonies using watershed segmentation for touching colonies.

A robust pipeline that uses watershed region-growing to separate touching or overlapping colonies that single-threshold methods merge into one object. Includes multi-stage preprocessing, morphological refinement, and grid alignment.

Steps:

1. GaussianBlur — smooth noise

2. EnhanceLocalContrast — boost local contrast

3. MedianFilter — remove residual speckle

4. WatershedDetector — region-growing segmentation

5. RemoveBorderObjects — remove partial edge colonies

6. RemoveLowCircularity — remove low-circularity artifacts

7. GridOversizedObjectRemover — remove merged multi-well objects

8. ReduceSectionsByLine — keep one colony per well

9. GridAligner — straighten the grid

10. MaskFill — fill interior holes

Measurements: MeasureShape, MeasureColor, MeasureTexture, MeasureIntensity.

Best For:

• Dense plates where colonies touch or overlap.

• Late time-point plates with large, merging colonies.

• Plates where Otsu detection merges adjacent colonies into single objects.

Consider Also:

• HeavyOtsuPipeline when colonies are well-separated.

• RoundPeaksPipeline for a faster approach on round, non-touching colonies.

See also

Tutorial 8: Using Prefab Pipelines for a visual comparison of prefab pipelines. Prefab Pipelines: Which One for Which Organism for guidance on choosing a prefab pipeline.

Parameters:

• gaussian_sigma (int)

• gaussian_mode (str)

• gaussian_truncate (float)

• watershed_footprint (Literal['auto'] | ~numpy.ndarray | int | None)

• watershed_min_size (int)

• watershed_compactness (float)

• watershed_connectivity (int)

• watershed_relabel (bool)

• watershed_ignore_zeros (bool)

• border_remover_size (int)

• circularity_cutoff (float)

• texture_scale (int)

• texture_warn (bool)

• benchmark (bool)

• name (str)

• desc (str | None)

• verbose (bool)

• reset (bool)

• nrows (int | None)

• ncols (int | None)

• ops (Dict[str, ImageOperation | ImagePipelineCore])

• meas (Dict[str, MeasureFeatures])

• post (Dict[str, PostMeasurement])

• filters (Dict[str, SetAnalyzer])

• model (ModelFitter | None)

• qc (List[QcRecipeEntry])

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, benchmark: bool = False, verbose: bool = False) → PrefabPipeline

Deserialize a PrefabPipeline from JSON.

PrefabPipeline subclasses build their ops/meas inside __init__, so the base from_json (which passes ops= directly) would conflict. This override deserializes via ImagePipeline and re-tags the instance as the correct PrefabPipeline subclass.

Parameters:

• json_data (str | Path | dict) – A JSON string, path to a JSON file, or a pre-parsed dict.

• benchmark (bool) – Whether to enable benchmarking for the pipeline.

• verbose (bool) – Whether to enable verbose output.

Returns:

A PrefabPipeline (or subclass) instance with the loaded configuration.

Return type:

PrefabPipeline

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__(gaussian_sigma: int = 5, gaussian_mode: str = 'reflect', gaussian_truncate: float = 4.0, watershed_footprint: Literal['auto'] | ndarray | int | None = None, watershed_min_size: int = 50, watershed_compactness: float = 0.001, watershed_connectivity: int = 1, watershed_relabel: bool = True, watershed_ignore_zeros: bool = True, border_remover_size: int = 25, circularity_cutoff: float = 0.5, texture_scale: int = 5, texture_warn: bool = False, benchmark: bool = False, **kwargs)

Initializes an image processing pipeline for various image analysis tasks such as object detection, segmentation, and measurement. This pipeline uses a combination of operations, including filtering, segmentation, and morphological processing, followed by shape, intensity, texture, and color measurements.

Parameters:

• gaussian_sigma (int, optional) – Standard deviation for Gaussian blur filter. Defaults to 5.

• gaussian_mode (str, optional) – Mode parameter for Gaussian blur filter (e.g., ‘reflect’). Defaults to ‘reflect’.

• gaussian_truncate (float, optional) – Truncate value for Gaussian kernel to limit its size. Defaults to 4.0.

• watershed_footprint (Literal['auto'] | np.ndarray | int | None, optional) – Footprint size or structure for the watershed algorithm. Defaults to None.

• watershed_min_size (int, optional) – Minimum size of the objects to be retained after watershed segmentation. Defaults to 50.

• watershed_compactness (float, optional) – Compactness parameter for the watershed algorithm to control how tightly regions are formed. Defaults to 0.001.

• watershed_connectivity (int, optional) – Connectivity parameter for region connectivity in watershed segmentation. Defaults to 1.

• watershed_relabel (bool, optional) – Whether to relabel the regions after watershed segmentation. Defaults to True.

• watershed_ignore_zeros (bool, optional) – Whether to ignore zero-valued regions in the watershed algorithm. Defaults to True.

• border_remover_size (int, optional) – Size of the border in pixels to be removed during border object removal. Defaults to 25.

• circularity_cutoff (float, optional) – Threshold for object circularity below which objects will be removed. Defaults to 0.5.

• texture_scale (int, optional) – Scale parameter for texture measurement. Defaults to 5.

• texture_warn (bool, optional) – Whether to issue warnings for invalid texture measurements. Defaults to False.

• benchmark (bool, optional) – Whether to enable benchmarking of pipeline performance. Defaults to False.

• **kwargs – Additional keyword arguments for parent class initialization.

__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

__str__() → str

Return a JSON-formatted string representation of the pipeline.

The generated JSON string provides a structured representation of the object’s current state, including its operations and measurements. This output can be used for logging, debugging, or to recreate the object’s configuration in another context.

Returns:

A JSON-formatted string that encodes the object’s current configuration in a human-readable manner. This includes the phenotypic version, pipeline name, description, and the lists of operations and measurements.

Return type:

str

analyze(df: pandas.DataFrame) → pandas.DataFrame

Run the analysis chain (filters then model) against an aggregate frame.

Applies each filter in order — each transforms a DataFrame into another DataFrame — then runs the configured terminal model to produce a fit summary (typically one row per group).

The expected input is the post-applied, aggregated DataFrame the CLI seeds into measurements.parquet. analyze does not apply post itself: by default measure() runs self._post before returning, and the CLI applies post explicitly to a copy of the aggregated master before invoking analyze. Callers passing apply_post=False to measure() are responsible for applying post (or accepting that filters/model see pre-post data) before calling analyze.

Parameters:

df (pandas.DataFrame) – The aggregate measurements DataFrame.

Returns:

The model-fit output (one row per group, plus shared

MODEL_METRICS columns for fit quality).

Return type:

pd.DataFrame

Raises:

ValueError – If no model is configured. Configure via set_model() (or pass model= at construction).

apply(image: Image, inplace: bool = False, reset: bool | None = None) → GridImage | Image

The class provides an interface to process and apply a series of operations on an Image. The operations are maintained in a queue and executed sequentially when applied to the given Image.

Parameters:

• image (Image) – The arr Image to be processed. The type Image refers to an instance of the Image object to which transformations are applied.

• inplace (bool, optional) – A flag indicating whether to apply the transformations directly on the provided Image (True) or create a copy of the Image before performing transformations (False). Defaults to False.

• reset (bool, optional) – Whether to reset the image before applying the pipeline. If None (default), uses the pipeline’s reset setting from __init__. If explicitly set to True or False, overrides the pipeline setting.

Return type:

Union[GridImage, Image]

apply_and_measure(image: Image, inplace: bool = False, reset: bool | None = None, include_metadata: bool = True, apply_post: bool = True) → pd.DataFrame

Applies processing to the given image and measures the results.

This function first applies a processing method to the supplied image, adjusting it based on the given parameters. After processing, the resulting image is measured, and a DataFrame containing the measurement data is returned.

Parameters:

• image (Image) – The image to process and measure.

• inplace (bool) – Whether to modify the original image directly or work on a copy. Default is False.

• reset (bool, optional) – Whether to reset any previous processing on the image before applying the current method. If None (default), uses the pipeline’s reset setting. If explicitly set, overrides the pipeline setting.

• include_metadata (bool) – Whether to include metadata in the measurement results. Default is True.

• apply_post (bool) – Forwarded to measure(). When False, the returned DataFrame skips PostMeasurement ops. Defaults to True.

Returns:

A DataFrame containing measurement data for the processed image.

Return type:

pd.DataFrame

apply_napari(image: Image, inplace: bool = False, reset: bool | None = None, viewer: napari.Viewer | None = None) → NapariPipelineResult

Apply the pipeline and progressively add layers to a napari viewer.

Creates (or reuses) a napari viewer and adds the original image layers as a baseline, then adds the modified layer after each operation completes. Layer names follow the pattern {step:02d}_{OperationName}_{accessor}.

Parameters:

• image (Image) – The input image to process.

• inplace (bool) – If True the image is modified in place; otherwise a copy is made first. Defaults to False.

• reset (bool | None) – Whether to reset the image before applying operations. None (default) uses the pipeline-level setting.

• viewer (napari.Viewer | None) – An existing napari viewer to add layers to. If None (default), a new viewer is created.

Returns:

Named tuple with the final image and the napari viewer reference.

Return type:

NapariPipelineResult

Raises:

ImportError – If napari is not installed.

apply_with_intermediates(image: Image, inplace: bool = False, reset: bool | None = None, output_dir: str | Path | None = None, *, full_layers: bool = False) → IntermediateResult

Apply the pipeline and capture a snapshot of the image after each operation.

Behaves identically to apply() (respecting inplace, reset, benchmark timing, and verbose/tqdm progress) but additionally records the image state after every operation completes.

Parameters:

• image (Image) – The input image to process.

• inplace (bool) – If True the image is modified in place; otherwise a copy is made first. Defaults to False.

• reset (Optional[bool]) – Whether to reset the image before applying operations. None (default) uses the pipeline-level setting.

• output_dir (Optional[Union[str, Path]]) – Optional directory path. When provided, each intermediate image is persisted to an HDF5 file inside this directory (created automatically) and the corresponding dict value is set to None to conserve memory. When None, intermediates are kept in memory as Image copies.

• full_layers (bool) – When True and output_dir is set, each non-read-only operation’s full image state is written as a complete schema-v2 snapshot via save2hdf5 (all layers + class/grid metadata) instead of the delta layout. Used by the builder’s node-preview cache so any node’s HDF reconstructs a faithful Image/GridImage. Defaults to False.

Returns:

A named tuple containing the final image and a dictionary mapping operation names to intermediate snapshots (or None when output_dir is used).

Return type:

IntermediateResult

benchmark_results() → pandas.DataFrame

Return execution times and memory usage for operations and measurements.

This method should be called after applying the pipeline on an image to get the execution times and memory consumption of the different processes.

When an operation is itself an ImagePipelineCore (nested pipeline), its sub-operations are expanded as indented sub-rows beneath the parent entry with names like "ParentOp > ChildOp".

Returns:

A DataFrame with columns Process Type,

Process Name, Execution Time (s), Memory Delta (MB), and RSS After (MB).

Return type:

pd.DataFrame

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]

get_filters() → Dict[str, SetAnalyzer]

Get a copy of the analysis filter chain.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Ordered dict mapping filter names to

SetAnalyzer instances. Empty when no filters configured.

Return type:

Dict[str, SetAnalyzer]

get_meas() → Dict[str, MeasureFeatures]

Get a copy of the measurements dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping measurement names to

MeasureFeatures instances.

Return type:

Dict[str, MeasureFeatures]

get_model() → ModelFitter | None

Get the analysis endpoint model, if configured.

Returns:

The configured ModelFitter instance,

or None when no model is set.

Return type:

Optional[ModelFitter]

get_ops() → Dict[str, ImageOperation | ImagePipelineCore]

Get a copy of the operations dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping

operation names to ImageOperation instances (or nested pipelines).

Return type:

Dict[str, ImageOperation | ImagePipelineCore]

get_post() → Dict[str, PostMeasurement]

Get a copy of the post-measurement transforms dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping post-measurement

names to PostMeasurement instances.

Return type:

Dict[str, PostMeasurement]

get_qc() → List[QcRecipeEntry]

Get a copy of the QC config entry list.

Returns a shallow copy so callers cannot mutate the pipeline’s internal list by appending/removing. The entries themselves are shared (they are lightweight config dataclasses); run_qc and the GUI only read them and instantiate fresh checks from their params.

Returns:

Ordered QC config entries. Empty when no

checks are configured.

Return type:

List[QcRecipeEntry]

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

measure(image: Image, include_metadata: bool = True, apply_post: bool = True) → pd.DataFrame

Measures properties of a given image and optionally includes metadata. The method performs measurements using a set of predefined measurement operations. If benchmarking is enabled, the execution time of each measurement is recorded. When verbose mode is active, detailed logging of the measurement process is displayed. A progress bar is used to track progress if the tqdm library is available.

Parameters:

• image (Image) – The image object for which measurements are performed. It must support the info method and optionally a grid or objects attribute.

• include_metadata (bool, optional) – Indicates whether metadata should be included in the measurements. Defaults to True.

• apply_post (bool, optional) – Whether to apply the configured PostMeasurement operations to the merged frame before returning. Defaults to True. Pass False to obtain the pre-post merged DataFrame — useful when the caller (e.g. the CLI) wants to persist a clean copy and apply post separately.

Returns:

A DataFrame containing the results of all performed measurements combined

on the same index. Columns are ordered as [metadata] -> [measurements] -> [MetadataImage_] -> [info block]: user/experimental Metadata* columns first (in canonical REMBI order, present only when include_metadata is True), then the measurement columns, then the framework MetadataImage_* bookkeeping block (per-image provenance: UUID, ImageName, BitDepth, …), then the per-object image-info block (Object_Label followed by the Bbox_* / Grid_* geometry columns) last.

Return type:

pd.DataFrame

Raises:

Exception – An exception is raised if a measurement operation fails while being applied to the image.

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

set_filters(filters: List[SetAnalyzer] | Dict[str, SetAnalyzer]) → None

Set the analysis filter chain.

Parameters:

filters (List[SetAnalyzer] | Dict[str, SetAnalyzer]) – A list or dictionary of SetAnalyzer instances. If a list, class names (deduplicated by suffix) are used as keys.

Raises:

TypeError – If filters is neither a list nor a dictionary.

Return type:

None

set_meas(measurements: List[MeasureFeatures] | Dict[str, MeasureFeatures])

Sets the measurements to be used for further computation. The input can be either a list of MeasureFeatures objects or a dictionary with string keys and MeasureFeatures objects as values.

The method processes the given input to construct a dictionary mapping measurement names to MeasureFeatures instances. If a list is passed, unique class names of the MeasureFeatures instances in the list are used as keys.

Parameters:

measurements (List[MeasureFeatures] | Dict[str, MeasureFeatures]) – A collection of measurement features either as a list of MeasureFeatures objects, where class names are used as keys for dictionary creation, or as a dictionary where keys are predefined strings and values are MeasureFeatures objects.

Raises:

TypeError – If the measurements argument is neither a list nor a dictionary.

set_model(model: ModelFitter | None) → None

Set the analysis endpoint model.

Only one model can be configured per pipeline; assigning a new value replaces any prior model. Pass None to clear.

Parameters:

model (ModelFitter | None) – A ModelFitter instance, or None to clear.

Raises:

TypeError – If model is not a ModelFitter instance and not None.

Return type:

None

set_ops(ops: List[ImageOperation | ImagePipeline] | Dict[str, ImageOperation | ImagePipeline])

Sets the operations to be performed. The operations can be passed as either a list of ImageOperation or ImagePipeline instances or a dictionary mapping operation names to ImageOperation or ImagePipeline instances. This method ensures that each operation in the list has a unique name. Raises a TypeError if the input is neither a list nor a dictionary.

Parameters:

ops (List[ImageOperation | ImagePipeline] | Dict[str, ImageOperation | ImagePipeline]) – A list of ImageOperation or ImagePipeline objects, or a dictionary where keys are operation names and values are ImageOperation or ImagePipeline objects.

Raises:

TypeError – If the input is not a list or a dictionary.

set_post(post: List[PostMeasurement] | Dict[str, PostMeasurement])

Set the post-measurement transforms.

Parameters:

post (List[PostMeasurement] | Dict[str, PostMeasurement]) – A list or dictionary of PostMeasurement objects. If a list, class names are used as keys.

Raises:

TypeError – If post is neither a list nor a dictionary.

set_qc(qc: List[QcRecipeEntry] | None) → None

Set the QC config entry list.

Mirrors set_post() / set_filters() but the QC section is an ordered list of QcRecipeEntry (carrying stable instance_id/enabled metadata), not a name-keyed dict.

Parameters:

qc (List[QcRecipeEntry] | None) – A list of QcRecipeEntry, or None to clear.

Raises:

TypeError – If qc is neither a list nor None (raised by the _normalize_qc validator on assignment).

Return type:

None

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

Serialize the pipeline configuration to JSON format.

This method captures the pipeline’s operations and measurements. It excludes internal state (pydantic PrivateAttr fields) and pandas DataFrames to keep the serialization clean and focused on reproducible configuration.

Parameters:

filepath (str | Path | None) – Optional path to save the JSON. If None, returns JSON string. Can be a string or Path object.

Returns:

JSON string representation of the pipeline configuration.

Return type:

str

Example

Serialize a pipeline to JSON format:

>>> from phenotypic import ImagePipeline
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.measure import MeasureShape
>>> pipe = ImagePipeline(pipe_cfgs=[OtsuDetector()], meas=[MeasureShape()])
>>> json_str = pipe.to_json()
>>> pipe.to_json('my_pipeline')  # Save to typed config file

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.

benchmark: bool

property desc: str

Get pipeline description. Returns class docstring if no description set.

desc_value: str | None

filters: Dict[str, SetAnalyzer]

meas: Dict[str, MeasureFeatures]

model: ModelFitter | None

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True, 'validate_by_name': 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 = {'benchmark': FieldInfo(annotation=bool, required=False, default=False, description='Whether to enable execution time tracking for operations and measurements.'), 'desc_value': FieldInfo(annotation=Union[str, NoneType], required=False, default=None, alias='desc', alias_priority=2), 'filters': FieldInfo(annotation=Dict[str, SetAnalyzer], required=False, default={}), 'meas': FieldInfo(annotation=Dict[str, MeasureFeatures], required=False, default={}), 'model': FieldInfo(annotation=Union[ModelFitter, NoneType], required=False, default=None), 'name': FieldInfo(annotation=str, required=False, default_factory=<lambda>, description='A unique identifier for this pipeline. Defaults to a randomly generated UUID4 string if not provided during initialization.'), 'ncols': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'nrows': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'ops': FieldInfo(annotation=Dict[str, Union[ImageOperation, ImagePipelineCore]], required=False, default_factory=dict, alias_priority=2, validation_alias=AliasChoices(choices=['ops', 'pipe_cfgs'])), 'post': FieldInfo(annotation=Dict[str, PostMeasurement], required=False, default={}), 'qc': FieldInfo(annotation=List[QcRecipeEntry], required=False, default_factory=list, exclude=True), 'reset': FieldInfo(annotation=bool, required=False, default=False), 'verbose': FieldInfo(annotation=bool, required=False, default=False, description='Whether to enable verbose logging during pipeline execution.')}

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.

name: str

ncols: int | None

nrows: int | None

ops: Dict[str, ImageOperation | 'ImagePipelineCore']

post: Dict[str, PostMeasurement]

qc: List[QcRecipeEntry]

reset: bool

verbose: bool

class phenotypic.prefab.RoundPeaksPipeline(*, blur_sigma: int = 5, blur_mode: str = 'reflect', blur_cval: float = 0.0, blur_truncate: float = 4.0, detector_thresh_method: Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata'] = 'otsu', detector_subtract_background: bool = True, detector_remove_noise: bool = True, detector_footprint_radius: int = 5, detector_smoothing_sigma: float = 2.0, detector_min_peak_distance: int | None = None, detector_peak_prominence: float | None = None, detector_edge_refinement: bool = True, texture_scale: int | List[int] = 5, texture_quant_lvl: Literal[8, 16, 32, 64] = 32, texture_enhance: bool = False, texture_warn: bool = False, benchmark: bool = False, verbose: bool = False)

Bases: PrefabPipeline

Detect and measure round colonies using lightweight peak-based detection.

A fast, minimal pipeline that applies Gaussian smoothing and grid-aware peak detection for circular colonies. Fewer stages and parameters than the Heavy variants, making it the fastest prefab option.

Steps:

1. GaussianBlur — smooth noise

2. RoundPeaksDetector — grid-aware circular colony detection

Measurements: MeasureShape, MeasureIntensity, MeasureTexture, MeasureColor.

Parameters:

• blur_sigma (int) – Gaussian blur sigma. Typical range: 1–5. Default: 5.

• blur_mode (str) – Boundary handling ('reflect', 'constant', 'nearest'). Default: 'reflect'.

• blur_cval (float) – Fill value when blur_mode='constant'. Default: 0.0.

• blur_truncate (float) – Kernel extent in standard deviations. Default: 4.0.

• detector_thresh_method (Literal['otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata']) – Thresholding method ('otsu', 'mean', 'local', 'triangle', 'minimum', 'isodata'). Default: 'otsu'.

• detector_subtract_background (bool) – Normalize background before thresholding. Default: True.

• detector_remove_noise (bool) – Morphological opening to remove specks. Default: True.

• detector_footprint_radius (int) – Radius for morphological operations. Default: 5.

• detector_smoothing_sigma (float) – Sigma for grid profile smoothing. Default: 2.0.

• detector_min_peak_distance (int | None) – Minimum grid line spacing. None auto-estimates. Default: None.

• detector_peak_prominence (float | None) – Minimum peak prominence. None auto-estimates. Default: None.

• detector_edge_refinement (bool) – Refine grid edges using local profiles. Default: True.

• texture_scale (int | List[int]) – Scale(s) for Haralick texture features. Default: 5.

• texture_quant_lvl (Literal[8, 16, 32, 64]) – Quantization level (8, 16, 32, 64). Default: 32.

• texture_enhance (bool) – Enhance contrast before texture measurement. Default: False.

• texture_warn (bool) – Warn on unreliable texture measurements. Default: False.

• benchmark (bool) – Enable per-step timing. Default: False.

• verbose (bool) – Enable verbose logging. Default: False.

Best For:

• Well-separated round colonies on grid plates.

• High-throughput screening where speed matters.

• Plates with consistent colony sizes and regular spacing.

• Quick prototyping before switching to a heavier pipeline.

Consider Also:

• HeavyRoundPeaksPipeline when additional refinement stages are needed for cleaner results.

• HeavyOtsuPipeline for general-purpose detection with more robust preprocessing.

• FilamentousFungiPipeline for filamentous organisms.

See also

Tutorial 8: Using Prefab Pipelines for a visual comparison of prefab pipelines. Prefab Pipelines: Which One for Which Organism for guidance on choosing a prefab pipeline.

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, benchmark: bool = False, verbose: bool = False) → PrefabPipeline

Deserialize a PrefabPipeline from JSON.

PrefabPipeline subclasses build their ops/meas inside __init__, so the base from_json (which passes ops= directly) would conflict. This override deserializes via ImagePipeline and re-tags the instance as the correct PrefabPipeline subclass.

Parameters:

• json_data (str | Path | dict) – A JSON string, path to a JSON file, or a pre-parsed dict.

• benchmark (bool) – Whether to enable benchmarking for the pipeline.

• verbose (bool) – Whether to enable verbose output.

Returns:

A PrefabPipeline (or subclass) instance with the loaded configuration.

Return type:

PrefabPipeline

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.

__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

__str__() → str

Return a JSON-formatted string representation of the pipeline.

The generated JSON string provides a structured representation of the object’s current state, including its operations and measurements. This output can be used for logging, debugging, or to recreate the object’s configuration in another context.

Returns:

A JSON-formatted string that encodes the object’s current configuration in a human-readable manner. This includes the phenotypic version, pipeline name, description, and the lists of operations and measurements.

Return type:

str

analyze(df: pandas.DataFrame) → pandas.DataFrame

Run the analysis chain (filters then model) against an aggregate frame.

Applies each filter in order — each transforms a DataFrame into another DataFrame — then runs the configured terminal model to produce a fit summary (typically one row per group).

The expected input is the post-applied, aggregated DataFrame the CLI seeds into measurements.parquet. analyze does not apply post itself: by default measure() runs self._post before returning, and the CLI applies post explicitly to a copy of the aggregated master before invoking analyze. Callers passing apply_post=False to measure() are responsible for applying post (or accepting that filters/model see pre-post data) before calling analyze.

Parameters:

df (pandas.DataFrame) – The aggregate measurements DataFrame.

Returns:

The model-fit output (one row per group, plus shared

MODEL_METRICS columns for fit quality).

Return type:

pd.DataFrame

Raises:

ValueError – If no model is configured. Configure via set_model() (or pass model= at construction).

apply(image: Image, inplace: bool = False, reset: bool | None = None) → GridImage | Image

The class provides an interface to process and apply a series of operations on an Image. The operations are maintained in a queue and executed sequentially when applied to the given Image.

Parameters:

• image (Image) – The arr Image to be processed. The type Image refers to an instance of the Image object to which transformations are applied.

• inplace (bool, optional) – A flag indicating whether to apply the transformations directly on the provided Image (True) or create a copy of the Image before performing transformations (False). Defaults to False.

• reset (bool, optional) – Whether to reset the image before applying the pipeline. If None (default), uses the pipeline’s reset setting from __init__. If explicitly set to True or False, overrides the pipeline setting.

Return type:

Union[GridImage, Image]

apply_and_measure(image: Image, inplace: bool = False, reset: bool | None = None, include_metadata: bool = True, apply_post: bool = True) → pd.DataFrame

Applies processing to the given image and measures the results.

This function first applies a processing method to the supplied image, adjusting it based on the given parameters. After processing, the resulting image is measured, and a DataFrame containing the measurement data is returned.

Parameters:

• image (Image) – The image to process and measure.

• inplace (bool) – Whether to modify the original image directly or work on a copy. Default is False.

• reset (bool, optional) – Whether to reset any previous processing on the image before applying the current method. If None (default), uses the pipeline’s reset setting. If explicitly set, overrides the pipeline setting.

• include_metadata (bool) – Whether to include metadata in the measurement results. Default is True.

• apply_post (bool) – Forwarded to measure(). When False, the returned DataFrame skips PostMeasurement ops. Defaults to True.

Returns:

A DataFrame containing measurement data for the processed image.

Return type:

pd.DataFrame

apply_napari(image: Image, inplace: bool = False, reset: bool | None = None, viewer: napari.Viewer | None = None) → NapariPipelineResult

Apply the pipeline and progressively add layers to a napari viewer.

Creates (or reuses) a napari viewer and adds the original image layers as a baseline, then adds the modified layer after each operation completes. Layer names follow the pattern {step:02d}_{OperationName}_{accessor}.

Parameters:

• image (Image) – The input image to process.

• inplace (bool) – If True the image is modified in place; otherwise a copy is made first. Defaults to False.

• reset (bool | None) – Whether to reset the image before applying operations. None (default) uses the pipeline-level setting.

• viewer (napari.Viewer | None) – An existing napari viewer to add layers to. If None (default), a new viewer is created.

Returns:

Named tuple with the final image and the napari viewer reference.

Return type:

NapariPipelineResult

Raises:

ImportError – If napari is not installed.

apply_with_intermediates(image: Image, inplace: bool = False, reset: bool | None = None, output_dir: str | Path | None = None, *, full_layers: bool = False) → IntermediateResult

Apply the pipeline and capture a snapshot of the image after each operation.

Behaves identically to apply() (respecting inplace, reset, benchmark timing, and verbose/tqdm progress) but additionally records the image state after every operation completes.

Parameters:

• image (Image) – The input image to process.

• inplace (bool) – If True the image is modified in place; otherwise a copy is made first. Defaults to False.

• reset (Optional[bool]) – Whether to reset the image before applying operations. None (default) uses the pipeline-level setting.

• output_dir (Optional[Union[str, Path]]) – Optional directory path. When provided, each intermediate image is persisted to an HDF5 file inside this directory (created automatically) and the corresponding dict value is set to None to conserve memory. When None, intermediates are kept in memory as Image copies.

• full_layers (bool) – When True and output_dir is set, each non-read-only operation’s full image state is written as a complete schema-v2 snapshot via save2hdf5 (all layers + class/grid metadata) instead of the delta layout. Used by the builder’s node-preview cache so any node’s HDF reconstructs a faithful Image/GridImage. Defaults to False.

Returns:

A named tuple containing the final image and a dictionary mapping operation names to intermediate snapshots (or None when output_dir is used).

Return type:

IntermediateResult

benchmark_results() → pandas.DataFrame

Return execution times and memory usage for operations and measurements.

This method should be called after applying the pipeline on an image to get the execution times and memory consumption of the different processes.

When an operation is itself an ImagePipelineCore (nested pipeline), its sub-operations are expanded as indented sub-rows beneath the parent entry with names like "ParentOp > ChildOp".

Returns:

A DataFrame with columns Process Type,

Process Name, Execution Time (s), Memory Delta (MB), and RSS After (MB).

Return type:

pd.DataFrame

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]

get_filters() → Dict[str, SetAnalyzer]

Get a copy of the analysis filter chain.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Ordered dict mapping filter names to

SetAnalyzer instances. Empty when no filters configured.

Return type:

Dict[str, SetAnalyzer]

get_meas() → Dict[str, MeasureFeatures]

Get a copy of the measurements dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping measurement names to

MeasureFeatures instances.

Return type:

Dict[str, MeasureFeatures]

get_model() → ModelFitter | None

Get the analysis endpoint model, if configured.

Returns:

The configured ModelFitter instance,

or None when no model is set.

Return type:

Optional[ModelFitter]

get_ops() → Dict[str, ImageOperation | ImagePipelineCore]

Get a copy of the operations dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping

operation names to ImageOperation instances (or nested pipelines).

Return type:

Dict[str, ImageOperation | ImagePipelineCore]

get_post() → Dict[str, PostMeasurement]

Get a copy of the post-measurement transforms dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping post-measurement

names to PostMeasurement instances.

Return type:

Dict[str, PostMeasurement]

get_qc() → List[QcRecipeEntry]

Get a copy of the QC config entry list.

Returns a shallow copy so callers cannot mutate the pipeline’s internal list by appending/removing. The entries themselves are shared (they are lightweight config dataclasses); run_qc and the GUI only read them and instantiate fresh checks from their params.

Returns:

Ordered QC config entries. Empty when no

checks are configured.

Return type:

List[QcRecipeEntry]

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

measure(image: Image, include_metadata: bool = True, apply_post: bool = True) → pd.DataFrame

Measures properties of a given image and optionally includes metadata. The method performs measurements using a set of predefined measurement operations. If benchmarking is enabled, the execution time of each measurement is recorded. When verbose mode is active, detailed logging of the measurement process is displayed. A progress bar is used to track progress if the tqdm library is available.

Parameters:

• image (Image) – The image object for which measurements are performed. It must support the info method and optionally a grid or objects attribute.

• include_metadata (bool, optional) – Indicates whether metadata should be included in the measurements. Defaults to True.

• apply_post (bool, optional) – Whether to apply the configured PostMeasurement operations to the merged frame before returning. Defaults to True. Pass False to obtain the pre-post merged DataFrame — useful when the caller (e.g. the CLI) wants to persist a clean copy and apply post separately.

Returns:

A DataFrame containing the results of all performed measurements combined

on the same index. Columns are ordered as [metadata] -> [measurements] -> [MetadataImage_] -> [info block]: user/experimental Metadata* columns first (in canonical REMBI order, present only when include_metadata is True), then the measurement columns, then the framework MetadataImage_* bookkeeping block (per-image provenance: UUID, ImageName, BitDepth, …), then the per-object image-info block (Object_Label followed by the Bbox_* / Grid_* geometry columns) last.

Return type:

pd.DataFrame

Raises:

Exception – An exception is raised if a measurement operation fails while being applied to the image.

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

set_filters(filters: List[SetAnalyzer] | Dict[str, SetAnalyzer]) → None

Set the analysis filter chain.

Parameters:

filters (List[SetAnalyzer] | Dict[str, SetAnalyzer]) – A list or dictionary of SetAnalyzer instances. If a list, class names (deduplicated by suffix) are used as keys.

Raises:

TypeError – If filters is neither a list nor a dictionary.

Return type:

None

set_meas(measurements: List[MeasureFeatures] | Dict[str, MeasureFeatures])

Sets the measurements to be used for further computation. The input can be either a list of MeasureFeatures objects or a dictionary with string keys and MeasureFeatures objects as values.

The method processes the given input to construct a dictionary mapping measurement names to MeasureFeatures instances. If a list is passed, unique class names of the MeasureFeatures instances in the list are used as keys.

Parameters:

measurements (List[MeasureFeatures] | Dict[str, MeasureFeatures]) – A collection of measurement features either as a list of MeasureFeatures objects, where class names are used as keys for dictionary creation, or as a dictionary where keys are predefined strings and values are MeasureFeatures objects.

Raises:

TypeError – If the measurements argument is neither a list nor a dictionary.

set_model(model: ModelFitter | None) → None

Set the analysis endpoint model.

Only one model can be configured per pipeline; assigning a new value replaces any prior model. Pass None to clear.

Parameters:

model (ModelFitter | None) – A ModelFitter instance, or None to clear.

Raises:

TypeError – If model is not a ModelFitter instance and not None.

Return type:

None

set_ops(ops: List[ImageOperation | ImagePipeline] | Dict[str, ImageOperation | ImagePipeline])

Sets the operations to be performed. The operations can be passed as either a list of ImageOperation or ImagePipeline instances or a dictionary mapping operation names to ImageOperation or ImagePipeline instances. This method ensures that each operation in the list has a unique name. Raises a TypeError if the input is neither a list nor a dictionary.

Parameters:

ops (List[ImageOperation | ImagePipeline] | Dict[str, ImageOperation | ImagePipeline]) – A list of ImageOperation or ImagePipeline objects, or a dictionary where keys are operation names and values are ImageOperation or ImagePipeline objects.

Raises:

TypeError – If the input is not a list or a dictionary.

set_post(post: List[PostMeasurement] | Dict[str, PostMeasurement])

Set the post-measurement transforms.

Parameters:

post (List[PostMeasurement] | Dict[str, PostMeasurement]) – A list or dictionary of PostMeasurement objects. If a list, class names are used as keys.

Raises:

TypeError – If post is neither a list nor a dictionary.

set_qc(qc: List[QcRecipeEntry] | None) → None

Set the QC config entry list.

Mirrors set_post() / set_filters() but the QC section is an ordered list of QcRecipeEntry (carrying stable instance_id/enabled metadata), not a name-keyed dict.

Parameters:

qc (List[QcRecipeEntry] | None) – A list of QcRecipeEntry, or None to clear.

Raises:

TypeError – If qc is neither a list nor None (raised by the _normalize_qc validator on assignment).

Return type:

None

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

Serialize the pipeline configuration to JSON format.

This method captures the pipeline’s operations and measurements. It excludes internal state (pydantic PrivateAttr fields) and pandas DataFrames to keep the serialization clean and focused on reproducible configuration.

Parameters:

filepath (str | Path | None) – Optional path to save the JSON. If None, returns JSON string. Can be a string or Path object.

Returns:

JSON string representation of the pipeline configuration.

Return type:

str

Example

Serialize a pipeline to JSON format:

>>> from phenotypic import ImagePipeline
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.measure import MeasureShape
>>> pipe = ImagePipeline(pipe_cfgs=[OtsuDetector()], meas=[MeasureShape()])
>>> json_str = pipe.to_json()
>>> pipe.to_json('my_pipeline')  # Save to typed config file

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.

benchmark: bool

property desc: str

Get pipeline description. Returns class docstring if no description set.

desc_value: str | None

filters: Dict[str, SetAnalyzer]

meas: Dict[str, MeasureFeatures]

model: ModelFitter | None

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True, 'validate_by_name': 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 = {'benchmark': FieldInfo(annotation=bool, required=False, default=False, description='Whether to enable execution time tracking for operations and measurements.'), 'desc_value': FieldInfo(annotation=Union[str, NoneType], required=False, default=None, alias='desc', alias_priority=2), 'filters': FieldInfo(annotation=Dict[str, SetAnalyzer], required=False, default={}), 'meas': FieldInfo(annotation=Dict[str, MeasureFeatures], required=False, default={}), 'model': FieldInfo(annotation=Union[ModelFitter, NoneType], required=False, default=None), 'name': FieldInfo(annotation=str, required=False, default_factory=<lambda>, description='A unique identifier for this pipeline. Defaults to a randomly generated UUID4 string if not provided during initialization.'), 'ncols': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'nrows': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'ops': FieldInfo(annotation=Dict[str, Union[ImageOperation, ImagePipelineCore]], required=False, default_factory=dict, alias_priority=2, validation_alias=AliasChoices(choices=['ops', 'pipe_cfgs'])), 'post': FieldInfo(annotation=Dict[str, PostMeasurement], required=False, default={}), 'qc': FieldInfo(annotation=List[QcRecipeEntry], required=False, default_factory=list, exclude=True), 'reset': FieldInfo(annotation=bool, required=False, default=False), 'verbose': FieldInfo(annotation=bool, required=False, default=False, description='Whether to enable verbose logging during pipeline execution.')}

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.

name: str

ncols: int | None

nrows: int | None

ops: Dict[str, ImageOperation | 'ImagePipelineCore']

post: Dict[str, PostMeasurement]

qc: List[QcRecipeEntry]

reset: bool

verbose: bool

class phenotypic.prefab.SpImagerPipeline

Bases: PrefabPipeline

A prefabricated pipeline for light image processing task for images from the S&P Robotics Imager

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, benchmark: bool = False, verbose: bool = False) → PrefabPipeline

Deserialize a PrefabPipeline from JSON.

PrefabPipeline subclasses build their ops/meas inside __init__, so the base from_json (which passes ops= directly) would conflict. This override deserializes via ImagePipeline and re-tags the instance as the correct PrefabPipeline subclass.

Parameters:

• json_data (str | Path | dict) – A JSON string, path to a JSON file, or a pre-parsed dict.

• benchmark (bool) – Whether to enable benchmarking for the pipeline.

• verbose (bool) – Whether to enable verbose output.

Returns:

A PrefabPipeline (or subclass) instance with the loaded configuration.

Return type:

PrefabPipeline

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.

__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

__str__() → str

Return a JSON-formatted string representation of the pipeline.

The generated JSON string provides a structured representation of the object’s current state, including its operations and measurements. This output can be used for logging, debugging, or to recreate the object’s configuration in another context.

Returns:

A JSON-formatted string that encodes the object’s current configuration in a human-readable manner. This includes the phenotypic version, pipeline name, description, and the lists of operations and measurements.

Return type:

str

analyze(df: pandas.DataFrame) → pandas.DataFrame

Run the analysis chain (filters then model) against an aggregate frame.

Applies each filter in order — each transforms a DataFrame into another DataFrame — then runs the configured terminal model to produce a fit summary (typically one row per group).

The expected input is the post-applied, aggregated DataFrame the CLI seeds into measurements.parquet. analyze does not apply post itself: by default measure() runs self._post before returning, and the CLI applies post explicitly to a copy of the aggregated master before invoking analyze. Callers passing apply_post=False to measure() are responsible for applying post (or accepting that filters/model see pre-post data) before calling analyze.

Parameters:

df (pandas.DataFrame) – The aggregate measurements DataFrame.

Returns:

The model-fit output (one row per group, plus shared

MODEL_METRICS columns for fit quality).

Return type:

pd.DataFrame

Raises:

ValueError – If no model is configured. Configure via set_model() (or pass model= at construction).

apply(image: Image, inplace: bool = False, reset: bool | None = None) → GridImage | Image

The class provides an interface to process and apply a series of operations on an Image. The operations are maintained in a queue and executed sequentially when applied to the given Image.

Parameters:

• image (Image) – The arr Image to be processed. The type Image refers to an instance of the Image object to which transformations are applied.

• inplace (bool, optional) – A flag indicating whether to apply the transformations directly on the provided Image (True) or create a copy of the Image before performing transformations (False). Defaults to False.

• reset (bool, optional) – Whether to reset the image before applying the pipeline. If None (default), uses the pipeline’s reset setting from __init__. If explicitly set to True or False, overrides the pipeline setting.

Return type:

Union[GridImage, Image]

apply_and_measure(image: Image, inplace: bool = False, reset: bool | None = None, include_metadata: bool = True, apply_post: bool = True) → pd.DataFrame

Applies processing to the given image and measures the results.

This function first applies a processing method to the supplied image, adjusting it based on the given parameters. After processing, the resulting image is measured, and a DataFrame containing the measurement data is returned.

Parameters:

• image (Image) – The image to process and measure.

• inplace (bool) – Whether to modify the original image directly or work on a copy. Default is False.

• reset (bool, optional) – Whether to reset any previous processing on the image before applying the current method. If None (default), uses the pipeline’s reset setting. If explicitly set, overrides the pipeline setting.

• include_metadata (bool) – Whether to include metadata in the measurement results. Default is True.

• apply_post (bool) – Forwarded to measure(). When False, the returned DataFrame skips PostMeasurement ops. Defaults to True.

Returns:

A DataFrame containing measurement data for the processed image.

Return type:

pd.DataFrame

apply_napari(image: Image, inplace: bool = False, reset: bool | None = None, viewer: napari.Viewer | None = None) → NapariPipelineResult

Apply the pipeline and progressively add layers to a napari viewer.

Creates (or reuses) a napari viewer and adds the original image layers as a baseline, then adds the modified layer after each operation completes. Layer names follow the pattern {step:02d}_{OperationName}_{accessor}.

Parameters:

• image (Image) – The input image to process.

• inplace (bool) – If True the image is modified in place; otherwise a copy is made first. Defaults to False.

• reset (bool | None) – Whether to reset the image before applying operations. None (default) uses the pipeline-level setting.

• viewer (napari.Viewer | None) – An existing napari viewer to add layers to. If None (default), a new viewer is created.

Returns:

Named tuple with the final image and the napari viewer reference.

Return type:

NapariPipelineResult

Raises:

ImportError – If napari is not installed.

apply_with_intermediates(image: Image, inplace: bool = False, reset: bool | None = None, output_dir: str | Path | None = None, *, full_layers: bool = False) → IntermediateResult

Apply the pipeline and capture a snapshot of the image after each operation.

Behaves identically to apply() (respecting inplace, reset, benchmark timing, and verbose/tqdm progress) but additionally records the image state after every operation completes.

Parameters:

• image (Image) – The input image to process.

• inplace (bool) – If True the image is modified in place; otherwise a copy is made first. Defaults to False.

• reset (Optional[bool]) – Whether to reset the image before applying operations. None (default) uses the pipeline-level setting.

• output_dir (Optional[Union[str, Path]]) – Optional directory path. When provided, each intermediate image is persisted to an HDF5 file inside this directory (created automatically) and the corresponding dict value is set to None to conserve memory. When None, intermediates are kept in memory as Image copies.

• full_layers (bool) – When True and output_dir is set, each non-read-only operation’s full image state is written as a complete schema-v2 snapshot via save2hdf5 (all layers + class/grid metadata) instead of the delta layout. Used by the builder’s node-preview cache so any node’s HDF reconstructs a faithful Image/GridImage. Defaults to False.

Returns:

A named tuple containing the final image and a dictionary mapping operation names to intermediate snapshots (or None when output_dir is used).

Return type:

IntermediateResult

benchmark_results() → pandas.DataFrame

Return execution times and memory usage for operations and measurements.

This method should be called after applying the pipeline on an image to get the execution times and memory consumption of the different processes.

When an operation is itself an ImagePipelineCore (nested pipeline), its sub-operations are expanded as indented sub-rows beneath the parent entry with names like "ParentOp > ChildOp".

Returns:

A DataFrame with columns Process Type,

Process Name, Execution Time (s), Memory Delta (MB), and RSS After (MB).

Return type:

pd.DataFrame

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]

get_filters() → Dict[str, SetAnalyzer]

Get a copy of the analysis filter chain.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Ordered dict mapping filter names to

SetAnalyzer instances. Empty when no filters configured.

Return type:

Dict[str, SetAnalyzer]

get_meas() → Dict[str, MeasureFeatures]

Get a copy of the measurements dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping measurement names to

MeasureFeatures instances.

Return type:

Dict[str, MeasureFeatures]

get_model() → ModelFitter | None

Get the analysis endpoint model, if configured.

Returns:

The configured ModelFitter instance,

or None when no model is set.

Return type:

Optional[ModelFitter]

get_ops() → Dict[str, ImageOperation | ImagePipelineCore]

Get a copy of the operations dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping

operation names to ImageOperation instances (or nested pipelines).

Return type:

Dict[str, ImageOperation | ImagePipelineCore]

get_post() → Dict[str, PostMeasurement]

Get a copy of the post-measurement transforms dictionary.

Returns a shallow copy to prevent accidental mutation of internal state.

Returns:

Dictionary mapping post-measurement

names to PostMeasurement instances.

Return type:

Dict[str, PostMeasurement]

get_qc() → List[QcRecipeEntry]

Get a copy of the QC config entry list.

Returns a shallow copy so callers cannot mutate the pipeline’s internal list by appending/removing. The entries themselves are shared (they are lightweight config dataclasses); run_qc and the GUI only read them and instantiate fresh checks from their params.

Returns:

Ordered QC config entries. Empty when no

checks are configured.

Return type:

List[QcRecipeEntry]

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

measure(image: Image, include_metadata: bool = True, apply_post: bool = True) → pd.DataFrame

Measures properties of a given image and optionally includes metadata. The method performs measurements using a set of predefined measurement operations. If benchmarking is enabled, the execution time of each measurement is recorded. When verbose mode is active, detailed logging of the measurement process is displayed. A progress bar is used to track progress if the tqdm library is available.

Parameters:

• image (Image) – The image object for which measurements are performed. It must support the info method and optionally a grid or objects attribute.

• include_metadata (bool, optional) – Indicates whether metadata should be included in the measurements. Defaults to True.

• apply_post (bool, optional) – Whether to apply the configured PostMeasurement operations to the merged frame before returning. Defaults to True. Pass False to obtain the pre-post merged DataFrame — useful when the caller (e.g. the CLI) wants to persist a clean copy and apply post separately.

Returns:

A DataFrame containing the results of all performed measurements combined

on the same index. Columns are ordered as [metadata] -> [measurements] -> [MetadataImage_] -> [info block]: user/experimental Metadata* columns first (in canonical REMBI order, present only when include_metadata is True), then the measurement columns, then the framework MetadataImage_* bookkeeping block (per-image provenance: UUID, ImageName, BitDepth, …), then the per-object image-info block (Object_Label followed by the Bbox_* / Grid_* geometry columns) last.

Return type:

pd.DataFrame

Raises:

Exception – An exception is raised if a measurement operation fails while being applied to the image.

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

set_filters(filters: List[SetAnalyzer] | Dict[str, SetAnalyzer]) → None

Set the analysis filter chain.

Parameters:

filters (List[SetAnalyzer] | Dict[str, SetAnalyzer]) – A list or dictionary of SetAnalyzer instances. If a list, class names (deduplicated by suffix) are used as keys.

Raises:

TypeError – If filters is neither a list nor a dictionary.

Return type:

None

set_meas(measurements: List[MeasureFeatures] | Dict[str, MeasureFeatures])

Sets the measurements to be used for further computation. The input can be either a list of MeasureFeatures objects or a dictionary with string keys and MeasureFeatures objects as values.

The method processes the given input to construct a dictionary mapping measurement names to MeasureFeatures instances. If a list is passed, unique class names of the MeasureFeatures instances in the list are used as keys.

Parameters:

measurements (List[MeasureFeatures] | Dict[str, MeasureFeatures]) – A collection of measurement features either as a list of MeasureFeatures objects, where class names are used as keys for dictionary creation, or as a dictionary where keys are predefined strings and values are MeasureFeatures objects.

Raises:

TypeError – If the measurements argument is neither a list nor a dictionary.

set_model(model: ModelFitter | None) → None

Set the analysis endpoint model.

Only one model can be configured per pipeline; assigning a new value replaces any prior model. Pass None to clear.

Parameters:

model (ModelFitter | None) – A ModelFitter instance, or None to clear.

Raises:

TypeError – If model is not a ModelFitter instance and not None.

Return type:

None

set_ops(ops: List[ImageOperation | ImagePipeline] | Dict[str, ImageOperation | ImagePipeline])

Sets the operations to be performed. The operations can be passed as either a list of ImageOperation or ImagePipeline instances or a dictionary mapping operation names to ImageOperation or ImagePipeline instances. This method ensures that each operation in the list has a unique name. Raises a TypeError if the input is neither a list nor a dictionary.

Parameters:

ops (List[ImageOperation | ImagePipeline] | Dict[str, ImageOperation | ImagePipeline]) – A list of ImageOperation or ImagePipeline objects, or a dictionary where keys are operation names and values are ImageOperation or ImagePipeline objects.

Raises:

TypeError – If the input is not a list or a dictionary.

set_post(post: List[PostMeasurement] | Dict[str, PostMeasurement])

Set the post-measurement transforms.

Parameters:

post (List[PostMeasurement] | Dict[str, PostMeasurement]) – A list or dictionary of PostMeasurement objects. If a list, class names are used as keys.

Raises:

TypeError – If post is neither a list nor a dictionary.

set_qc(qc: List[QcRecipeEntry] | None) → None

Set the QC config entry list.

Mirrors set_post() / set_filters() but the QC section is an ordered list of QcRecipeEntry (carrying stable instance_id/enabled metadata), not a name-keyed dict.

Parameters:

qc (List[QcRecipeEntry] | None) – A list of QcRecipeEntry, or None to clear.

Raises:

TypeError – If qc is neither a list nor None (raised by the _normalize_qc validator on assignment).

Return type:

None

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

Serialize the pipeline configuration to JSON format.

This method captures the pipeline’s operations and measurements. It excludes internal state (pydantic PrivateAttr fields) and pandas DataFrames to keep the serialization clean and focused on reproducible configuration.

Parameters:

filepath (str | Path | None) – Optional path to save the JSON. If None, returns JSON string. Can be a string or Path object.

Returns:

JSON string representation of the pipeline configuration.

Return type:

str

Example

Serialize a pipeline to JSON format:

>>> from phenotypic import ImagePipeline
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.measure import MeasureShape
>>> pipe = ImagePipeline(pipe_cfgs=[OtsuDetector()], meas=[MeasureShape()])
>>> json_str = pipe.to_json()
>>> pipe.to_json('my_pipeline')  # Save to typed config file

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.

benchmark: bool

property desc: str

Get pipeline description. Returns class docstring if no description set.

desc_value: str | None

filters: Dict[str, SetAnalyzer]

meas: Dict[str, MeasureFeatures]

model: ModelFitter | None

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True, 'validate_by_name': 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 = {'benchmark': FieldInfo(annotation=bool, required=False, default=False, description='Whether to enable execution time tracking for operations and measurements.'), 'desc_value': FieldInfo(annotation=Union[str, NoneType], required=False, default=None, alias='desc', alias_priority=2), 'filters': FieldInfo(annotation=Dict[str, SetAnalyzer], required=False, default={}), 'meas': FieldInfo(annotation=Dict[str, MeasureFeatures], required=False, default={}), 'model': FieldInfo(annotation=Union[ModelFitter, NoneType], required=False, default=None), 'name': FieldInfo(annotation=str, required=False, default_factory=<lambda>, description='A unique identifier for this pipeline. Defaults to a randomly generated UUID4 string if not provided during initialization.'), 'ncols': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'nrows': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'ops': FieldInfo(annotation=Dict[str, Union[ImageOperation, ImagePipelineCore]], required=False, default_factory=dict, alias_priority=2, validation_alias=AliasChoices(choices=['ops', 'pipe_cfgs'])), 'post': FieldInfo(annotation=Dict[str, PostMeasurement], required=False, default={}), 'qc': FieldInfo(annotation=List[QcRecipeEntry], required=False, default_factory=list, exclude=True), 'reset': FieldInfo(annotation=bool, required=False, default=False), 'verbose': FieldInfo(annotation=bool, required=False, default=False, description='Whether to enable verbose logging during pipeline execution.')}

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.

name: str

ncols: int | None

nrows: int | None

ops: Dict[str, ImageOperation | 'ImagePipelineCore']

post: Dict[str, PostMeasurement]

qc: List[QcRecipeEntry]

reset: bool

verbose: bool