phenotypic.analysis #

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:

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:

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

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:

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

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:

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:

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:

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

__init__(**data: Any) → None

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

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

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

Parameters:: data (Any)
Return type:: None

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

So dict(model) works.

Return type:: Generator[tuple[str, Any], None, None]

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

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

Parameters:

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

Return type:

__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

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

Apply the edge-correction strategy group-by-group.

Validates the frame, stores the pre-correction copy on self._original_data, aggregates to one row per well per group, then dispatches each group to the static _apply2group_func() worker (serial for a single group, joblib-parallel otherwise) using the kwargs from _group_config().

Parameters:: data (pandas.DataFrame)
Return type:: pandas.DataFrame

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

dash(**kwargs)

Interactive Plotly visualization of analysis results.

Subclasses may override this method to provide an interactive Plotly figure equivalent to show().

Raises:: NotImplementedError – Unless overridden by a subclass.

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:

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:

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:

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

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

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

results() → pandas.DataFrame[source]

Return the corrected measurement DataFrame from the last analyze() call.

Retrieves the DataFrame with edge-corrected measurements produced by the most recent call to analyze(). Provides convenient access to results without retaining a local reference.

Returns:

Edge-corrected measurements with original data plus two new: correction columns: - EDGE_CORRECTION.NEW_VAL-{self.on}: Capped measurement values - EDGE_CORRECTION.CORRECTED_CAP-{self.on}: Threshold value used Original measurement column (self.on) is preserved unchanged. If analyze() has not been called, returns an empty DataFrame.

Return type:

pd.DataFrame

Examples

Retrieving corrected measurements after analysis:

>>> corrector = EdgeCorrector(
...     on='Area',
...     groupby=['ImageName']
... )
>>> corrected = corrector.analyze(data)
>>> results = corrector.results()
>>> assert results.equals(corrected)
>>> # Access corrected values
>>> corrected_areas = results['Size-Area']
>>> thresholds = results['Cap-Area']
>>> # Original 'Area' column also available for comparison
>>> original_areas = results['Area']

Notes

Returns the DataFrame stored in self._latest_measurements
Same as the return value of analyze()
Always use this method rather than direct attribute access

show(figsize: tuple[int, int] | None = None, max_groups: int = 20, collapsed: bool = True, criteria: dict[str, Any] | None = None, **kwargs) → tuple[Figure, TypeAliasForwardRef('matplotlib.axes.Axes')][source]

Visualize edge correction results with interior/edge colony comparisons.

Displays the distribution of measurements for the last time point per group, highlighting interior (surrounded) vs. edge colonies. Shows the calculated correction threshold and permutation test p-values. Interior colonies are shown in blue, edge colonies in red. Circles indicate measurements passing the threshold, X’s indicate capped measurements.

Parameters:

figsize (tuple[int, int], optional) – Figure size as (width, height) in inches. If None, auto-sized based on number of groups (single-group: 10x6, many groups: 10x max(6, 0.5*ngroups+2)).
max_groups (int, optional) – Maximum number of groups to display. Defaults to 20. If data has more groups, a warning is printed and only the first 20 are shown.
collapsed (bool, optional) – If True (default), show all groups stacked vertically on a single axis with y-offsets. If False, create a grid of subplots with one group per subplot.
criteria (dict[str, Any], optional) – Filter groups before visualization using column-value criteria (e.g., {‘Plate’: ‘P1’, ‘Condition’: [‘WT’, ‘KO’]}). Filtering uses SetAnalyzer._filter_by with AND logic across criteria.
**kwargs –
Additional matplotlib parameters:
- dpi (int): Figure resolution, passed to plt.subplots()
- facecolor (str): Figure background color
- edgecolor (str): Figure edge color
- legend_fontsize (int): Font size for legend (default 9 for collapsed, 8 for individual)

Returns:

Tuple of (matplotlib Figure, Axes object(s)):

If collapsed=True: (Figure, single Axes)

If collapsed=False: (Figure, array of Axes)

Return type:

tuple[Figure, plt.Axes]

Raises:

RuntimeError – If analyze() has not been called (no results to display).
ValueError – If criteria filter leaves no matching data.

Notes

Interior colonies are those with all orthogonal neighbors present (4-connectivity)
Edge colonies are detected but lack all orthogonal neighbors
Threshold line (orange) is derived from top interior colonies
P-values displayed between interior and edge means (if pvalue != 0)
Permutation test uses 1000 resamples with two-sided alternative
Call analyze() before show()

Examples

Basic visualization of edge correction results:

>>> corrector = EdgeCorrector(on='Area', groupby=['ImageName'])
>>> corrected = corrector.analyze(data)
>>> fig, ax = corrector.show()
>>> # Single collapsed plot with all groups stacked vertically

Individual subplots per group:

>>> fig, axes = corrector.show(
...     collapsed=False,
...     figsize=(15, 10)
... )
>>> # Grid of subplots, max 3 columns

Filtered visualization for specific plate:

>>> fig, ax = corrector.show(
...     criteria={'Plate': 'P1'},
...     max_groups=10,
...     figsize=(12, 8)
... )

agg_func: Callable | str | list | dict | None

connectivity: int

groupby: ColumnRefList

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

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

model_fields = {'agg_func': FieldInfo(annotation=Union[Callable, str, list, dict, NoneType], required=False, default='mean'), 'connectivity': FieldInfo(annotation=int, required=False, default=4, description='Neighbor pattern: 4 (orthogonal) or 8 (with diagonals).'), 'groupby': FieldInfo(annotation=list[str], required=True, description='Column names for grouping data by experiment/plate/condition.', metadata=[_ColumnRefMarker('measurements')]), 'n_jobs': FieldInfo(annotation=int, required=False, default=1, alias_priority=2, validation_alias=AliasChoices(choices=['n_jobs', 'num_workers'])), 'ncols': FieldInfo(annotation=int, required=False, default=12, description='Grid columns.'), 'nrows': FieldInfo(annotation=int, required=False, default=8, description='Grid rows.'), 'on': FieldInfo(annotation=str, required=True, description='Name of measurement column to analyze and correct.', metadata=[_ColumnRefMarker('measurements')]), 'pvalue': FieldInfo(annotation=float, required=False, default=0.05, description='P-value threshold for permutation test (0.0 disables test).'), 'time_label': FieldInfo(annotation=str, required=False, default='MetadataCulture_Time', description='Column holding the time point.', metadata=[_ColumnRefMarker('measurements')]), 'top_n': FieldInfo(annotation=int, required=False, default=3, description='Number of top-valued interior colonies to use for threshold calculation.')}

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.

n_jobs: int

ncols: int

nrows: int

on: ColumnRef

pvalue: float

time_label: ColumnRef

top_n: int

class phenotypic.analysis.ErrorCutoffFinder(*, min_error_n: int = 8, min_good_n: int = 8, measurement_prefixes: tuple[str, ...] = ('Size_', 'Shape_', 'Intensity_', 'Texture', 'SymZones_', 'GridSpatial_', 'RadialExpansion_'))[source]

Bases: BaseModel

Rank measurements by good-vs-error separability with suggested cutoffs.

Note

p_value/p_bh are reported for reference only — ranking and cutoffs are distribution-free (AUC / ROC + Youden’s J), because the ANOVA normality / equal-variance assumptions rarely hold on error subpopulations. good_n/error_n are the per-measurement non-NaN counts and may individually fall below min_good_n/min_error_n (which is a frame-level guard, not a per-measurement one).

Parameters:

min_error_n (int) – Minimum error-class sample size (>= 2); below it, analyze() returns an empty frame (the statistics are unstable).
min_good_n (int) – Minimum good-class sample size (>= 2); same behaviour.
measurement_prefixes (tuple[str, ...]) – Column-name prefixes treated as numeric measurements. Defaults to MEASUREMENT_PREFIXES.

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

This is intended to behave just like __init_subclass__, but is called by ModelMetaclass only after basic class initialization is complete. In particular, attributes like model_fields will be present when this is called, but forward annotations are not guaranteed to be resolved yet, meaning that creating an instance of the class may fail.

This is necessary because __init_subclass__ will always be called by type.__new__, and it would require a prohibitively large refactor to the ModelMetaclass to ensure that type.__new__ was called in such a manner that the class would already be sufficiently initialized.

This will receive the same kwargs that would be passed to the standard __init_subclass__, namely, any kwargs passed to the class definition that aren’t used internally by Pydantic.

Parameters:: **kwargs (Any) – Any keyword arguments passed to the class definition that aren’t used internally by Pydantic.
Return type:: None

Note

You may want to override [__pydantic_on_complete__()][pydantic.main.BaseModel.__pydantic_on_complete__] instead, which is called once the class and its fields are fully initialized and ready for validation.

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:

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:

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:

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

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:

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

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:

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:

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:

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

__init__(**data: Any) → None

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

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

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

Parameters:: data (Any)
Return type:: None

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

So dict(model) works.

Return type:: Generator[tuple[str, Any], None, None]

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

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

Parameters:

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

Return type:

__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

analyze(good: pandas.DataFrame, error: pandas.DataFrame) → pandas.DataFrame[source]

Screen every measurement for good-vs-error separation.

Parameters:

good (pandas.DataFrame) – The good-baseline frame (caller chooses all-unlabeled vs verified-only — the engine is agnostic).
error (pandas.DataFrame) – The frame of objects labelled with the target error category.

Returns:

A frame with one row per measurement, columns RESULT_COLUMNS, sorted by auc (separability) descending. Empty (0 rows, same columns) when enough_data() is False or no measurement column has enough non-NaN values in both classes.

Return type:

pandas.DataFrame

Examples

>>> import numpy as np, pandas as pd
>>> rng = np.random.default_rng(0)
>>> good = pd.DataFrame({"Size_Area": rng.normal(0, 1, 40)})
>>> error = pd.DataFrame({"Size_Area": rng.normal(5, 1, 12)})
>>> res = ErrorCutoffFinder().analyze(good, error)
>>> res.iloc[0]["measurement"], bool(res.iloc[0]["auc"] > 0.9)
('Size_Area', True)

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

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:

enough_data(good: pandas.DataFrame, error: pandas.DataFrame) → bool[source]

Return whether both classes meet their minimum sample sizes.

Parameters:

good (pandas.DataFrame)
error (pandas.DataFrame)

Return type:

bool

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:

measurement_columns(df: pandas.DataFrame) → list[str][source]

Return the numeric measurement columns of df in column order.

A column qualifies iff its name starts with one of measurement_prefixes and its dtype is numeric.

Parameters:: df (pandas.DataFrame) – A measurement frame (good or error).
Returns:: The qualifying measurement column names.
Return type:: list[str]

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”: [model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

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

Parameters:

update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.
deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

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

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

model_post_init(context: Any, /) → None

Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

Parameters:: context (Any)
Return type:: None

measurement_prefixes: tuple[str, ...]

min_error_n: int

min_good_n: int

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: 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 = {'measurement_prefixes': FieldInfo(annotation=tuple[str, ...], required=False, default=('Size_', 'Shape_', 'Intensity_', 'Texture', 'SymZones_', 'GridSpatial_', 'RadialExpansion_')), 'min_error_n': FieldInfo(annotation=int, required=False, default=8), 'min_good_n': FieldInfo(annotation=int, required=False, default=8)}

property model_fields_set: set[str]

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

Returns:

A set of strings representing the fields that have been set,: i.e. that were not filled from defaults.

class phenotypic.analysis.ExpectedVsDetectedCount(*, on: ~typing.Annotated[str, _ColumnRefMarker('measurements')] = 'Object_Label', groupby: ~typing.Annotated[list[str], _ColumnRefMarker('measurements')], agg_func: ~typing.Callable | str | list | dict | None = 'first', n_jobs: int = 1, warn_threshold: float = 0.05, fail_threshold: float = 0.1, unmatched_groups: list = <factory>, metadata: ~typing.Annotated[~pandas.core.frame.DataFrame | str, ~pydantic.json_schema.WithJsonSchema(json_schema={'oneOf': [{'type': 'string', 'description': 'Path to a .csv/.parquet layout file (the form that round-trips through JSON).'}, {'type': 'object', 'description': 'In-memory pandas DataFrame layout (runtime-only; not JSON-serializable).'}]}, mode=None)])[source]

Bases: QualityCheck

Flag groups whose detected colony count diverges from metadata.

For each groupby combination the check compares the number of rows in the measurement frame (detected) against the number of rows in the externally-provided metadata frame for the same key (expected). The signed difference and its normalized magnitude drive a tri-state pass/warn/fail label:

QC_Count_Metric = |detected - expected| / expected

QC_Count_Metric = numpy.inf when expected == 0 (i.e. the measurement group has no metadata counterpart). This always exceeds fail_threshold so the status becomes "fail" and the rows are flagged. The offending key tuple is recorded in unmatched_groups so the GUI can distinguish a real biology fail from a metadata-mismatch fail.

_HIGHER_IS_BAD is True: a larger normalized count divergence is worse, so the base class flags rows whose metric meets or exceeds fail_threshold (including the infinite metric of an unmatched group).

The check does not aggregate measurement values — it counts rows — so _exposes_agg_func is False and the GUI parameter-form rendering driver hides the agg_func field. The base SetAnalyzer.agg_func is pinned to "first" internally.

The single metadata argument accepts either an in-memory pandas.DataFrame (an “array”) or a path (Path or str) to a .csv/.parquet file. The value is stored verbatim — self.metadata echoes exactly what was passed — and the resolved frame is read once at construction time onto the private _metadata slot. Every column named in groupby must be present in the resolved frame; otherwise KeyError is raised at __init__ so the failure surfaces before analyze runs.

Serialization: only a path is JSON-native, so the path is the form that round-trips. When metadata is a path, model_dump / pipeline.json persist that path string under the same metadata key and a reloaded instance re-reads the file. When metadata is an in-memory DataFrame there is no source path to persist — the JSON form is None and the check cannot be rebuilt from JSON alone (it fails to instantiate with a clear error, surfaced as a skip-with-warning by the lazy QC instantiation path). Configure QC checks from a metadata path whenever the pipeline is meant to round-trip.
Args:

metadata: Layout whose row count per groupby key is the
expected colony count. Either an in-memory DataFrame or a path (Path/str) to a .csv/.parquet file. The path form is what serializes and round-trips through JSON; an in-memory frame is runtime-only.

groupby: Columns that define a comparison unit. Must be present
in both the metadata frame and the measurement frame passed to analyze().

on: Measurement column the check operates on. Defaults to
"Object_Label" since “detected” means “a measurement row exists”.

warn_threshold: Normalized count divergence at which Status
becomes "warn". Defaults to 0.05.

fail_threshold: Normalized count divergence at which Status
becomes "fail" and Flag=True. Defaults to 0.10.

n_jobs: Worker count. Currently unused by the base analyze
loop; kept on the signature for parity with SetAnalyzer.

Raises:
FileNotFoundError: If metadata is a path that does not exist. KeyError: If any column in groupby is absent from the

resolved metadata frame.

ValueError: If metadata is a path with an unsupported suffix,
or if it is None — i.e. reconstructing from JSON that was built from an in-memory frame, which has no source path to persist.

Attributes:

unmatched_groups: List of group-key tuples that appeared in the
measurement frame but had no counterpart in the metadata frame during the most recent analyze() call. Reset at the top of each analyze so re-runs do not accumulate.

Examples:
Basic match — 96-well metadata vs. a measurement frame missing one well:
>>> import pandas as pd
>>> from phenotypic.analysis.qc import (
...     ExpectedVsDetectedCount,
... )
>>> metadata = pd.DataFrame({
...     "MetadataImage_ImageName": ["plate1.png"] * 96,
...     "Object_Label": list(range(96)),
... })
>>> measurements = pd.DataFrame({
...     "MetadataImage_ImageName": ["plate1.png"] * 95,
...     "Object_Label": list(range(95)),
... })
>>> chk = ExpectedVsDetectedCount(
...     metadata=metadata,
...     groupby=["MetadataImage_ImageName"],
... )
>>> result = chk.analyze(measurements)
>>> "QC_Count_Metric" in result.columns
True
Advanced — a measurement group has no metadata counterpart, so the metric is infinite and the key is recorded:
>>> metadata = pd.DataFrame({
...     "MetadataImage_ImageName": ["plate1.png"] * 96,
...     "Object_Label": list(range(96)),
... })
>>> measurements = pd.DataFrame({
...     "MetadataImage_ImageName": ["plate2.png"] * 10,
...     "Object_Label": list(range(10)),
... })
>>> chk = ExpectedVsDetectedCount(
...     metadata=metadata,
...     groupby=["MetadataImage_ImageName"],
... )
>>> _ = chk.analyze(measurements)
>>> chk.unmatched_groups
[('plate2.png',)]

Category: **QC_Count**#
Name	Description	Type
`QC_Count_Flag`	True when the metric crosses fail_threshold in the bad direction; eligible for curation.	Quality
`QC_Count_Metric`	Headline metric in the check’s own units; the bad direction is set by the check’s _HIGHER_IS_BAD flag. Drives Status.	Quality
`QC_Count_Status`	Categorical: pass \| warn \| fail.	Quality

Category: **QC_Count**#
Name	Description	Type
`Detected`	Detected colony count in the group.	Quality
`Expected`	Expected colony count from the metadata frame.	Quality
`Delta`	Detected − Expected (signed; negative = missing).	Quality

Parameters:

on (Annotated[str, _ColumnRefMarker('measurements')])
groupby (Annotated[list[str], _ColumnRefMarker('measurements')])
agg_func (Callable | str | list | dict | None)
n_jobs (int)
warn_threshold (float)
fail_threshold (float)
unmatched_groups (list)
metadata (Annotated[DataFrame | str, WithJsonSchema(json_schema={'oneOf': [{'type': 'string', 'description': 'Path to a .csv/.parquet layout file (the form that round-trips through JSON).'}, {'type': 'object', 'description': 'In-memory pandas DataFrame layout (runtime-only; not JSON-serializable).'}]}, mode=None)])

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 __init_subclass__(**kwargs: Any) → None

Append QC and per-check RST tables to the subclass docstring.

Skips intermediate ABCs that have not yet bound name. When the subclass declares both a docstring and a name, the generic QUALITY_CHECK table is appended (substituting name into the column headers). If _measurement_infoclass is also set, its table is appended as well so check-specific columns are documented alongside the generic trio.

Parameters:: kwargs (Any)
Return type:: None

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, copying parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot.

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:

classmethod flag_col() → str

Return the flag column name for this check.

Return type:: str

classmethod from_orm(obj: Any) → Self

Parameters:: obj (Any)
Return type:: Self

classmethod metric_col() → str

Return the metric column name for this check.

Return type:: str

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:

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:

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

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:

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

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:

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:

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:

classmethod status_col() → str

Return the status column name for this check.

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

__init__(**data: Any) → None

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

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

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

Parameters:: data (Any)
Return type:: None

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

So dict(model) works.

Return type:: Generator[tuple[str, Any], None, None]

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

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

Parameters:

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

Return type:

__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

analyze(data: pandas.DataFrame) → pandas.DataFrame[source]

Reset unmatched_groups and run the base analyze.

Re-running the check on a different measurement frame must not carry over unmatched groups from a previous run, so the list is cleared before delegating to the base class.

Parameters:: data (pandas.DataFrame) – Measurement frame to evaluate.
Returns:: The augmented frame from QualityCheck.analyze().
Return type:: pandas.DataFrame

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

dash(**kwargs: Any) → Figure[source]

Render a horizontal lollipop chart of Delta per group.

Each group’s signed Delta is drawn as a horizontal stem from zero to Delta, with a marker at the tip colored by Status. The hover label exposes detected, expected, and the metric for the group.

Parameters:: **kwargs (Any) – Passed through to plotly.graph_objects.Figure() / Figure.update_layout — accepted keys are title and height.
Returns:: A plotly.graph_objects.Figure with one stem trace and one marker trace.
Raises:: RuntimeError – If analyze() has not been called yet.
Return type:: Figure

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:

flagged_keys() → list[tuple[str, int]]

Return (Metadata_ImageName, Object_Label) pairs to curate.

Used by the GUI “Mark all flagged for removal” button. Requires the analyzed frame to carry both Metadata_ImageName and Object_Label columns (the curation key used by STORE_REMOVED_KEYS). Returns an empty list when those columns are absent or when no rows were flagged.

Returns:: De-duplicated list of (image_file, object_label) tuples for rows where Flag=True.
Return type:: list[tuple[str, int]]

group_members() → dict[tuple, list[tuple[str, int, Any]]]

Map each group key to its member rows for worklists/galleries.

Walks the most recent analyzed frame and, for every group key produced by data.groupby(self.groupby, dropna=False), collects the rows that belong to it as (Metadata_ImageName, Object_Label, member_value) tuples, where member_value is the row’s self.on value (the column the check operates on). The mapping preserves group iteration order.

Mirrors flagged_keys()’s guard: if the analyzed frame lacks either Metadata_ImageName or the object-label column, an empty mapping is returned rather than raising.

Returns:: Ordered mapping of group key (always a tuple, even for a single groupby column) to a list of (image_file, object_label, member_value) tuples. Empty when the curation key columns are absent.
Return type:: dict[tuple, list[tuple[str, int, 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)
encoder (Callable[[Any], Any] | None)
models_as_dict (bool)
dumps_kwargs (Any)

Return type:

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:

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

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

model_post_init(_ExpectedVsDetectedCount__context: Any) → None[source]

Resolve the layout frame, validate columns, pre-compute counts.

Runs after pydantic has validated every field. Resolves self.metadata (a frame or a path) into the working frame on the private _metadata slot, verifies every groupby column is present, and caches the per-key expected colony counts.

Parameters:

__context – Pydantic post-init context (unused).
_ExpectedVsDetectedCount__context (Any)

Raises:

FileNotFoundError – If metadata is a path that does not exist.
ValueError – If metadata is a path with an unsupported suffix.
KeyError – If any column in groupby is absent from the resolved metadata frame.

Return type:

None

results() → pandas.DataFrame

Return the augmented frame stored by the most recent analyze().

Return type:: pandas.DataFrame

show(*args: Any, **kwargs: Any) → Any

QualityCheck plots are Plotly-only — see dash().

SetAnalyzer’s matplotlib show() is not implemented for QC because the QC tab is Plotly-driven. Raising rather than falling back to a placeholder so notebook users discover the right method.

Raises:

NotImplementedError – Always; use dash() instead.

Parameters:

args (Any)
kwargs (Any)

Return type:

summary() → pandas.DataFrame

Return a one-row-per-group summary of the most recent analyze.

The aggregate columns are prefixed with ``qc_`` so they can never collide with a groupby column on reset_index — a plate-layout column literally named status or num_rows would otherwise raise. The summary therefore always carries the group key columns plus the four prefixed aggregates.

Returns:: DataFrame with columns [*self.groupby, "qc_n_members", "qc_n_flagged", "qc_worst_metric", "qc_status"]. qc_worst_metric is the extreme metric value in the bad direction across the group: group[metric_col].max() when _HIGHER_IS_BAD is True, else group[metric_col].min(). qc_status is the worst status across the group: "fail" wins over "warn" which wins over "pass".
Return type:: pandas.DataFrame

table_spec(instance_id: str) → QcTableSpec

Return the catalog descriptor for this analyzed check.

Precondition: analyze() has run. Reads column roles from the class + instance config and derives extra_cols from the augmented frame.

Parameters:: instance_id (str) – The recipe entry id this check was built from.
Returns:: A populated QcTableSpec.
Return type:: QcTableSpec

to_table() → pandas.DataFrame

Return the module’s self-describing frame to persist to DuckDB.

Precondition: analyze() has run (this reads _latest_measurements). The default is member-level: the augmented frame projected to group-key + member-key + on + every QC_<name>_* column (metric/flag/status AND check-specific extras) + context columns (Metadata_Dataset and the column named by self.time_label) when those columns are present.

Diagnostic-only checks override to return a group-level frame.

Returns:: The projected DataFrame; columns vary per check (self-describing).
Return type:: pandas.DataFrame

agg_func: Callable | str | list | dict | None

fail_threshold: float

groupby: ColumnRefList

member_key_cols: ClassVar[tuple[str, ...]] = ('MetadataImage_ImageName', 'Object_Label'): Per-object curation-key columns. Empty tuple when the check has no per-object key. Subclasses may narrow this.

metadata: _MetadataField

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

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

model_fields = {'agg_func': FieldInfo(annotation=Union[Callable, str, list, dict, NoneType], required=False, default='first'), 'fail_threshold': FieldInfo(annotation=float, required=False, default=0.1, description='Normalized count divergence at which ``Status`` becomes ``"fail"`` and ``Flag=True``. Defaults to ``0.10``.'), 'groupby': FieldInfo(annotation=list[str], required=True, description='Columns that define a comparison unit. Must be present in both the metadata frame and the measurement frame passed', metadata=[_ColumnRefMarker('measurements')]), 'metadata': FieldInfo(annotation=Union[DataFrame, str], required=True, description='Layout whose row count per ``groupby`` key is the expected colony count. Either an in-memory DataFrame or a path (``Path``/``str``) to a ``.csv``/``.parquet`` file. The path form is what serializes and round-trips through JSON; an in-memory frame is runtime-only.', metadata=[WithJsonSchema(json_schema={'oneOf': [{'type': 'string', 'description': 'Path to a .csv/.parquet layout file (the form that round-trips through JSON).'}, {'type': 'object', 'description': 'In-memory pandas DataFrame layout (runtime-only; not JSON-serializable).'}]}, mode=None)]), 'n_jobs': FieldInfo(annotation=int, required=False, default=1, alias_priority=2, validation_alias=AliasChoices(choices=['n_jobs', 'num_workers']), description='Worker count. Currently unused by the base ``analyze`` loop; kept on the signature for parity with :class:`SetAnalyzer`.'), 'on': FieldInfo(annotation=str, required=False, default='Object_Label', description='Measurement column the check operates on. Defaults to ``"Object_Label"`` since "detected" means "a measurement row exists".', metadata=[_ColumnRefMarker('measurements')]), 'unmatched_groups': FieldInfo(annotation=list, required=False, default_factory=list, description='Groups that the check could not evaluate (for example, expected counts whose group key never appeared in the data). Populated by subclasses that need to report missing combinations; empty by default.'), 'warn_threshold': FieldInfo(annotation=float, required=False, default=0.05, description='Normalized count divergence at which ``Status`` becomes ``"warn"``. Defaults to ``0.05``.')}

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.

n_jobs: int

name: ClassVar[str] = 'Count'

on: ColumnRef

supports_object_curation: ClassVar[bool] = True: Whether this check’s rows map to curatable detected objects. False for diagnostic-only checks (e.g. GridOccupancy) — the Review tab hides the curation radial + tile gallery and verified-good skips them.

unmatched_groups: list

warn_threshold: float

class phenotypic.analysis.GridOccupancy(*, on: ~typing.Annotated[str, _ColumnRefMarker('measurements')] = 'Object_Label', groupby: ~typing.Annotated[list[str], _ColumnRefMarker('measurements')], agg_func: ~typing.Callable | str | list | dict | None = 'first', n_jobs: int = 1, warn_threshold: float = 0.95, fail_threshold: float = 0.9, unmatched_groups: list = <factory>, metadata: ~typing.Annotated[~pandas.core.frame.DataFrame | str, ~pydantic.json_schema.WithJsonSchema(json_schema={'oneOf': [{'type': 'string', 'description': 'Path to a .csv/.parquet layout file (the form that round-trips through JSON).'}, {'type': 'object', 'description': 'In-memory pandas DataFrame layout (runtime-only; not JSON-serializable).'}]}, mode=None)], cell_label: ~typing.Annotated[str, _ColumnRefMarker('measurements')] = 'Grid_RowMajorIdx')[source]

Bases: ExpectedVsDetectedCount

Flag groups whose grid occupancy (filled cells / expected) is low.

Inherits the entire metadata-form surface of ExpectedVsDetectedCount — the single metadata field (an in-memory DataFrame or a .csv/.parquet path), its store-verbatim coercion, the pipeline.json serialization round-trip (the source path persists under the metadata key and the frame re-reads on load), and the per-key expected-count precompute. The expected cell count for a group is the number of metadata rows for that groupby key (one row per expected pin position).

Where the parent counts len(group) (raw detections, doublets included), this check counts group[cell_label].nunique() distinct occupied cells, so a doublet (two colonies sharing one grid cell) still counts once. The two columns play distinct roles:

on (inherited default "Object_Label") is the base-class required/guard column and the curation member value — it is unique per colony, so it is not what occupancy counts over.

cell_label (default "Grid_RowMajorIdx") is the grid-cell id the occupancy nunique collapses doublets over. Counting distinct labels would count colonies, not cells; counting distinct cells is what makes the metric doublet-insensitive.

The metric is filled / expected. _HIGHER_IS_BAD is False: a lower occupancy is worse, so a row fails when metric <= fail_threshold and warns at metric <= warn_threshold (hence warn_threshold >= fail_threshold).

A group present in the measurements but absent from the metadata frame (expected == 0) is recorded in unmatched_groups and given metric = 0.0 so it fails — mirroring the parent’s “force a flag on a metadata mismatch” behavior, adapted to the lower-is-bad direction. The QC_Occupancy_Expected = 0 column distinguishes such a mismatch from a genuinely empty plate.
Args:

metadata: Layout (in-memory DataFrame or .csv/.parquet
path) whose row count per groupby key is the expected cell count. Same semantics, coercion, and serialization as ExpectedVsDetectedCount (the path form round-trips through JSON).

groupby: Columns that define one plate. Usually
["MetadataImage_ImageName"]. Must be present in both the metadata frame and the measurement frame.

on: Base-class required column and curation member value. Defaults
to "Object_Label"; occupancy does not count over it.

cell_label: Grid-cell id column whose distinct count is the filled
cell count. Defaults to "Grid_RowMajorIdx". Must be present in the measurement frame passed to analyze().

warn_threshold: Occupancy at/below which Status becomes
"warn". Defaults to 0.95.

fail_threshold: Occupancy at/below which Status becomes
"fail" and Flag=True. Defaults to 0.90.

Raises:

KeyError: If cell_label is absent from the measurement frame, or
(inherited) if any groupby column is absent from the metadata frame.

FileNotFoundError: (inherited) If metadata is a path that does
not exist.

ValueError: (inherited) If metadata is a path with an
unsupported suffix, or if it is None (a check serialized from an in-memory frame, which cannot round-trip).

Examples:
Basic — 96-cell metadata vs. a measurement frame with 92 colonies but only 90 distinct filled cells (two doublets). Occupancy reads the filled-cell count, not the colony count:
>>> import pandas as pd
>>> from phenotypic.analysis.qc import GridOccupancy
>>> metadata = pd.DataFrame({
...     "MetadataImage_ImageName": ["p1.png"] * 96,
...     "Object_Label": list(range(96)),
... })
>>> measurements = pd.DataFrame({
...     "MetadataImage_ImageName": ["p1.png"] * 92,
...     "Object_Label": list(range(92)),
...     "Grid_RowMajorIdx": list(range(90)) + [5, 17],
... })
>>> chk = GridOccupancy(
...     metadata=metadata, groupby=["MetadataImage_ImageName"]
... )
>>> out = chk.analyze(measurements)
>>> int(out["QC_Occupancy_Filled"].iloc[0])
90
>>> round(float(out["QC_Occupancy_Metric"].iloc[0]), 4)
0.9375

Category: **QC_Occupancy**#
Name	Description	Type
`QC_Occupancy_Flag`	True when the metric crosses fail_threshold in the bad direction; eligible for curation.	Quality
`QC_Occupancy_Metric`	Headline metric in the check’s own units; the bad direction is set by the check’s _HIGHER_IS_BAD flag. Drives Status.	Quality
`QC_Occupancy_Status`	Categorical: pass \| warn \| fail.	Quality

Category: **QC_Occupancy**#
Name	Description	Type
`Filled`	Distinct grid cells holding at least one colony (doublets count once).	Quality
`Expected`	Expected grid-cell count from the metadata frame (rows per group).	Quality
`Vacant`	Expected - Filled; empty/missing grid cells in the group.	Quality

Parameters:

on (Annotated[str, _ColumnRefMarker('measurements')])
groupby (Annotated[list[str], _ColumnRefMarker('measurements')])
agg_func (Callable | str | list | dict | None)
n_jobs (int)
warn_threshold (float)
fail_threshold (float)
unmatched_groups (list)
metadata (Annotated[DataFrame | str, WithJsonSchema(json_schema={'oneOf': [{'type': 'string', 'description': 'Path to a .csv/.parquet layout file (the form that round-trips through JSON).'}, {'type': 'object', 'description': 'In-memory pandas DataFrame layout (runtime-only; not JSON-serializable).'}]}, mode=None)])
cell_label (Annotated[str, _ColumnRefMarker('measurements')])

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 __init_subclass__(**kwargs: Any) → None

Append QC and per-check RST tables to the subclass docstring.

Skips intermediate ABCs that have not yet bound name. When the subclass declares both a docstring and a name, the generic QUALITY_CHECK table is appended (substituting name into the column headers). If _measurement_infoclass is also set, its table is appended as well so check-specific columns are documented alongside the generic trio.

Parameters:: kwargs (Any)
Return type:: None

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, copying parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot.

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:

classmethod flag_col() → str

Return the flag column name for this check.

Return type:: str

classmethod from_orm(obj: Any) → Self

Parameters:: obj (Any)
Return type:: Self

classmethod metric_col() → str

Return the metric column name for this check.

Return type:: str

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:

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:

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

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:

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

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:

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:

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:

classmethod status_col() → str

Return the status column name for this check.

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

__init__(**data: Any) → None

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

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

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

Parameters:: data (Any)
Return type:: None

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

So dict(model) works.

Return type:: Generator[tuple[str, Any], None, None]

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

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

Parameters:

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

Return type:

__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

analyze(data: pandas.DataFrame) → pandas.DataFrame[source]

Guard the cell-id column, then run the inherited analyze.

The base QualityCheck.analyze only guards self.on and self.groupby; occupancy additionally needs cell_label so it can collapse doublets, so its absence is surfaced here before the per-group loop runs.

Parameters:: data (pandas.DataFrame) – Measurement frame to evaluate.
Returns:: The augmented frame from the inherited analyze (which also resets unmatched_groups).
Raises:: KeyError – If cell_label is missing from data.
Return type:: pandas.DataFrame

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

dash(**kwargs: Any) → Figure[source]

Render a horizontal bar of per-group occupancy, colored by status.

Parameters:: **kwargs (Any) – Passed through to Figure.update_layout — accepted keys are title and height.
Returns:: A plotly.graph_objects.Figure with one bar trace and a dashed reference line at fail_threshold.
Raises:: RuntimeError – If analyze() has not been called yet.
Return type:: Figure

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:

flagged_keys() → list[tuple[str, int]]

Return (Metadata_ImageName, Object_Label) pairs to curate.

Used by the GUI “Mark all flagged for removal” button. Requires the analyzed frame to carry both Metadata_ImageName and Object_Label columns (the curation key used by STORE_REMOVED_KEYS). Returns an empty list when those columns are absent or when no rows were flagged.

Returns:: De-duplicated list of (image_file, object_label) tuples for rows where Flag=True.
Return type:: list[tuple[str, int]]

group_members() → dict[tuple, list[tuple[str, int, Any]]]

Map each group key to its member rows for worklists/galleries.

Walks the most recent analyzed frame and, for every group key produced by data.groupby(self.groupby, dropna=False), collects the rows that belong to it as (Metadata_ImageName, Object_Label, member_value) tuples, where member_value is the row’s self.on value (the column the check operates on). The mapping preserves group iteration order.

Mirrors flagged_keys()’s guard: if the analyzed frame lacks either Metadata_ImageName or the object-label column, an empty mapping is returned rather than raising.

Returns:: Ordered mapping of group key (always a tuple, even for a single groupby column) to a list of (image_file, object_label, member_value) tuples. Empty when the curation key columns are absent.
Return type:: dict[tuple, list[tuple[str, int, 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)
encoder (Callable[[Any], Any] | None)
models_as_dict (bool)
dumps_kwargs (Any)

Return type:

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:

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

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

model_post_init(_ExpectedVsDetectedCount__context: Any) → None

Resolve the layout frame, validate columns, pre-compute counts.

Runs after pydantic has validated every field. Resolves self.metadata (a frame or a path) into the working frame on the private _metadata slot, verifies every groupby column is present, and caches the per-key expected colony counts.

Parameters:

__context – Pydantic post-init context (unused).
_ExpectedVsDetectedCount__context (Any)

Raises:

FileNotFoundError – If metadata is a path that does not exist.
ValueError – If metadata is a path with an unsupported suffix.
KeyError – If any column in groupby is absent from the resolved metadata frame.

Return type:

None

results() → pandas.DataFrame

Return the augmented frame stored by the most recent analyze().

Return type:: pandas.DataFrame

show(*args: Any, **kwargs: Any) → Any

QualityCheck plots are Plotly-only — see dash().

SetAnalyzer’s matplotlib show() is not implemented for QC because the QC tab is Plotly-driven. Raising rather than falling back to a placeholder so notebook users discover the right method.

Raises:

NotImplementedError – Always; use dash() instead.

Parameters:

args (Any)
kwargs (Any)

Return type:

summary() → pandas.DataFrame

Return a one-row-per-group summary of the most recent analyze.

The aggregate columns are prefixed with ``qc_`` so they can never collide with a groupby column on reset_index — a plate-layout column literally named status or num_rows would otherwise raise. The summary therefore always carries the group key columns plus the four prefixed aggregates.

Returns:: DataFrame with columns [*self.groupby, "qc_n_members", "qc_n_flagged", "qc_worst_metric", "qc_status"]. qc_worst_metric is the extreme metric value in the bad direction across the group: group[metric_col].max() when _HIGHER_IS_BAD is True, else group[metric_col].min(). qc_status is the worst status across the group: "fail" wins over "warn" which wins over "pass".
Return type:: pandas.DataFrame

table_spec(instance_id: str) → QcTableSpec

Return the catalog descriptor for this analyzed check.

Precondition: analyze() has run. Reads column roles from the class + instance config and derives extra_cols from the augmented frame.

Parameters:: instance_id (str) – The recipe entry id this check was built from.
Returns:: A populated QcTableSpec.
Return type:: QcTableSpec

to_table() → pandas.DataFrame[source]

Return one group-level row per group (occupancy is per-plate).

Occupancy reports filled-vs-expected counts broadcast across a group’s rows, so per-colony rows carry no extra signal. Collapse to one row per group: the base summary() (renamed to the generic QC columns) plus the occupancy-specific counts.

Returns:: [*groupby, QC_Occupancy_Filled, QC_Occupancy_Expected, QC_Occupancy_Vacant, QC_Occupancy_Metric, QC_Occupancy_Status, QC_Occupancy_Flag].
Return type:: A group-level frame

agg_func: Callable | str | list | dict | None

cell_label: ColumnRef

fail_threshold: float

groupby: ColumnRefList

member_key_cols: ClassVar[tuple[str, ...]] = ('MetadataImage_ImageName', 'Object_Label'): Per-object curation-key columns. Empty tuple when the check has no per-object key. Subclasses may narrow this.

metadata: _MetadataField

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

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

model_fields = {'agg_func': FieldInfo(annotation=Union[Callable, str, list, dict, NoneType], required=False, default='first'), 'cell_label': FieldInfo(annotation=str, required=False, default='Grid_RowMajorIdx', description='Grid-cell id column whose distinct count is the filled cell count. Defaults to ``"Grid_RowMajorIdx"``. Must be present in the measurement frame passed to :meth:`analyze`.', metadata=[_ColumnRefMarker('measurements')]), 'fail_threshold': FieldInfo(annotation=float, required=False, default=0.9, description='Occupancy at/below which ``Status`` becomes ``"fail"`` and ``Flag=True``. Defaults to ``0.90``.'), 'groupby': FieldInfo(annotation=list[str], required=True, description='Columns that define a comparison unit. Must be present in both the metadata frame and the measurement frame passed', metadata=[_ColumnRefMarker('measurements')]), 'metadata': FieldInfo(annotation=Union[DataFrame, str], required=True, description='Layout whose row count per ``groupby`` key is the expected colony count. Either an in-memory DataFrame or a path (``Path``/``str``) to a ``.csv``/``.parquet`` file. The path form is what serializes and round-trips through JSON; an in-memory frame is runtime-only.', metadata=[WithJsonSchema(json_schema={'oneOf': [{'type': 'string', 'description': 'Path to a .csv/.parquet layout file (the form that round-trips through JSON).'}, {'type': 'object', 'description': 'In-memory pandas DataFrame layout (runtime-only; not JSON-serializable).'}]}, mode=None)]), 'n_jobs': FieldInfo(annotation=int, required=False, default=1, alias_priority=2, validation_alias=AliasChoices(choices=['n_jobs', 'num_workers']), description='Worker count. Currently unused by the base ``analyze`` loop; kept on the signature for parity with :class:`SetAnalyzer`.'), 'on': FieldInfo(annotation=str, required=False, default='Object_Label', description='Measurement column the check operates on. Defaults to ``"Object_Label"`` since "detected" means "a measurement row exists".', metadata=[_ColumnRefMarker('measurements')]), 'unmatched_groups': FieldInfo(annotation=list, required=False, default_factory=list, description='Groups that the check could not evaluate (for example, expected counts whose group key never appeared in the data). Populated by subclasses that need to report missing combinations; empty by default.'), 'warn_threshold': FieldInfo(annotation=float, required=False, default=0.95, description='Occupancy at/below which ``Status`` becomes ``"warn"``. Defaults to ``0.95``.')}

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.

n_jobs: int

name: ClassVar[str] = 'Occupancy'

on: ColumnRef

supports_object_curation: ClassVar[bool] = False: Whether this check’s rows map to curatable detected objects. False for diagnostic-only checks (e.g. GridOccupancy) — the Review tab hides the curation radial + tile gallery and verified-good skips them.

unmatched_groups: list

warn_threshold: float

class phenotypic.analysis.ICC(*, on: ~typing.Annotated[str, _ColumnRefMarker('measurements')], groupby: ~typing.Annotated[list[str], _ColumnRefMarker('measurements')], agg_func: ~typing.Callable | str | list | dict | None = 'mean', n_jobs: int = 1, warn_threshold: float = 0.75, fail_threshold: float = 0.5, unmatched_groups: list = <factory>, subject_label: ~typing.Annotated[str, _ColumnRefMarker('measurements')] = 'MetadataCulture_Time', rater_label: ~typing.Annotated[str, _ColumnRefMarker('measurements')] = 'MetadataSample_BioReplicate')[source]

Bases: QualityCheck

Flag groupby groups whose replicates have low ICC(2,1) agreement.

For each combination of self.groupby columns, this check builds a complete subjects × raters matrix — one row per subject_label value (the repeated-measure axis, by default "MetadataCulture_Time") and one column per rater_label value (the replicates that should agree, by default "MetadataSample_BioReplicate") — and computes the ICC(2,1) two-way random, absolute-agreement coefficient over it. With MetadataCulture_Time as the subject axis the between-timepoint (growth) variance dominates, so the ICC primarily flags replicate disagreement that is large relative to the growth signal. The single per-group ICC is the metric, broadcast to every member row so the GUI can pick up the flag from any row.

The estimator is the classic two-way mean-square decomposition:
ICC = (MSR - MSE)
      / (MSR + (k - 1) * MSE + (k / n) * (MSC - MSE))
where n is the subject count, k the rater count, MSR the between-subjects mean square, MSC the between-raters mean square, and MSE the residual mean square. Computed with NumPy only — no pingouin dependency.

_HIGHER_IS_BAD is False: the ICC is an agreement score where a smaller value is worse, so the base class flags rows whose metric is less than or equal to fail_threshold and warns at or below warn_threshold (with fail_threshold <= warn_threshold). This check is the reference implementation of the lower-is-bad direction. A negative ICC is a valid result, not an error: it signals agreement worse than chance (e.g. raters that anti-correlate across subjects) and correctly lands well inside the "fail" band.

Several guard paths short-circuit to metric = NaN so under-powered or degenerate groups never gate curation. NaN here means “insufficient data to estimate agreement” — it is not a passing grade of good agreement. The base class maps NaN to Status="pass" only so degenerate groups never gate curation; a reviewer reading the metric should treat NaN as “could not be computed”, never as “agreement is fine”. The guards are:

Missing axis column (LOUD) — subject_label or rater_label is absent from the input frame, so the two-way model cannot be built. The metric is NaN, but the group key is also recorded in unmatched_groups (mirroring ExpectedVsDetectedCount) so a not-evaluated check is visibly “could not run”, never a silent green pass. The other guards below are genuine “insufficient data” cases and do not populate unmatched_groups.

Incomplete matrix — at least one (subject, rater) cell is missing or duplicated after pivoting; a balanced two-way ANOVA requires exactly one observation per cell. A single missing cell NaNs the whole group — subjects and raters are never silently dropped to complete the design, and no rows are removed.

``n < 2`` subjects or ``k < 2`` raters — at least two of each are required for the between-source mean squares.

Zero variance — the total mean square is zero (all values identical), so the ICC is mathematically undefined. This is insufficient signal, explicitly not a perfect 1.0.

The check does not aggregate measurement values — it builds the two-way matrix inside _compute() — so _exposes_agg_func is False and the GUI parameter-form rendering driver hides the agg_func field. The base SetAnalyzer.agg_func is preserved on the signature for parity only.
Attributes:

subject_label: Column whose distinct values index the subject
(row) axis of the two-way model — the repeated-measure axis. Defaults to "MetadataCulture_Time" so each timepoint is a subject and the ICC flags replicates that disagree relative to the growth trend. Override (e.g. "MetadataGenetic_Strain") for a snapshot reliability design.

rater_label: Column whose distinct values index the rater
(column) axis of the two-way model — the replicates that should agree. Defaults to "MetadataSample_BioReplicate".

warn_threshold: ICC at or below which Status becomes
"warn". Defaults to 0.75.

fail_threshold: ICC at or below which Status becomes
"fail" and Flag=True. Defaults to 0.50.

unmatched_groups: Group keys whose subject_label or
rater_label axis column was absent, so the check could not be evaluated. Reset at the top of each analyze().

Examples:
Basic — three timepoints (subjects) × three replicates (raters) with tight replicate agreement at each timepoint; the check adds QC_ICC_Metric plus the per-group summary columns:
>>> import pandas as pd
>>> from phenotypic.analysis.qc import ICC
>>> data = pd.DataFrame({
...     "Plate": ["P1"] * 9,
...     "MetadataCulture_Time": [0, 0, 0, 1, 1, 1, 2, 2, 2],
...     "MetadataSample_BioReplicate": [1, 2, 3] * 3,
...     "Size_Area": [
...         10.0, 10.1, 9.9,
...         20.0, 20.2, 19.8,
...         40.0, 40.1, 39.9,
...     ],
... })
>>> chk = ICC(on="Size_Area", groupby=["Plate"])
>>> result = chk.analyze(data)
>>> "QC_ICC_Metric" in result.columns
True
Advanced — when the rater axis column is absent the two-way model cannot be built: the metric is NaN and the group is recorded as unmatched so the not-evaluated check is loud, not a silent pass:
>>> no_rater = pd.DataFrame({
...     "Plate": ["P1"] * 3,
...     "MetadataCulture_Time": [0, 1, 2],
...     "Size_Area": [10.0, 20.0, 40.0],
... })
>>> chk = ICC(on="Size_Area", groupby=["Plate"])
>>> result = chk.analyze(no_rater)
>>> bool(result["QC_ICC_Metric"].isna().all())
True
>>> chk.unmatched_groups
[('P1',)]

Category: **QC_ICC**#
Name	Description	Type
`QC_ICC_Flag`	True when the metric crosses fail_threshold in the bad direction; eligible for curation.	Quality
`QC_ICC_Metric`	Headline metric in the check’s own units; the bad direction is set by the check’s _HIGHER_IS_BAD flag. Drives Status.	Quality
`QC_ICC_Status`	Categorical: pass \| warn \| fail.	Quality

Parameters:

on (Annotated[str, _ColumnRefMarker('measurements')])
groupby (Annotated[list[str], _ColumnRefMarker('measurements')])
agg_func (Callable | str | list | dict | None)
n_jobs (int)
warn_threshold (float)
fail_threshold (float)
unmatched_groups (list)
subject_label (Annotated[str, _ColumnRefMarker('measurements')])
rater_label (Annotated[str, _ColumnRefMarker('measurements')])

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 __init_subclass__(**kwargs: Any) → None

Append QC and per-check RST tables to the subclass docstring.

Skips intermediate ABCs that have not yet bound name. When the subclass declares both a docstring and a name, the generic QUALITY_CHECK table is appended (substituting name into the column headers). If _measurement_infoclass is also set, its table is appended as well so check-specific columns are documented alongside the generic trio.

Parameters:: kwargs (Any)
Return type:: None

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, copying parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot.

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:

classmethod flag_col() → str

Return the flag column name for this check.

Return type:: str

classmethod from_orm(obj: Any) → Self

Parameters:: obj (Any)
Return type:: Self

classmethod metric_col() → str

Return the metric column name for this check.

Return type:: str

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:

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:

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

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:

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

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:

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:

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:

classmethod status_col() → str

Return the status column name for this check.

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

__init__(**data: Any) → None

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

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

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

Parameters:: data (Any)
Return type:: None

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

So dict(model) works.

Return type:: Generator[tuple[str, Any], None, None]

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

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

Parameters:

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

Return type:

__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

analyze(data: pandas.DataFrame) → pandas.DataFrame[source]

Reset unmatched_groups and run the base analyze.

Re-running the check on a different measurement frame must not carry over groups flagged as unmatched (missing axis column) from a previous run, so the list is cleared before delegating to the base class.

Parameters:: data (pandas.DataFrame) – Measurement frame to evaluate.
Returns:: The augmented frame from QualityCheck.analyze().
Return type:: pandas.DataFrame

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

dash(**kwargs)

Interactive Plotly visualization of analysis results.

Subclasses may override this method to provide an interactive Plotly figure equivalent to show().

Raises:: NotImplementedError – Unless overridden by a subclass.

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:

flagged_keys() → list[tuple[str, int]]

Return (Metadata_ImageName, Object_Label) pairs to curate.

Used by the GUI “Mark all flagged for removal” button. Requires the analyzed frame to carry both Metadata_ImageName and Object_Label columns (the curation key used by STORE_REMOVED_KEYS). Returns an empty list when those columns are absent or when no rows were flagged.

Returns:: De-duplicated list of (image_file, object_label) tuples for rows where Flag=True.
Return type:: list[tuple[str, int]]

group_members() → dict[tuple, list[tuple[str, int, Any]]]

Map each group key to its member rows for worklists/galleries.

Walks the most recent analyzed frame and, for every group key produced by data.groupby(self.groupby, dropna=False), collects the rows that belong to it as (Metadata_ImageName, Object_Label, member_value) tuples, where member_value is the row’s self.on value (the column the check operates on). The mapping preserves group iteration order.

Mirrors flagged_keys()’s guard: if the analyzed frame lacks either Metadata_ImageName or the object-label column, an empty mapping is returned rather than raising.

Returns:: Ordered mapping of group key (always a tuple, even for a single groupby column) to a list of (image_file, object_label, member_value) tuples. Empty when the curation key columns are absent.
Return type:: dict[tuple, list[tuple[str, int, 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)
encoder (Callable[[Any], Any] | None)
models_as_dict (bool)
dumps_kwargs (Any)

Return type:

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:

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

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

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

results() → pandas.DataFrame

Return the augmented frame stored by the most recent analyze().

Return type:: pandas.DataFrame

show(*args: Any, **kwargs: Any) → Any

QualityCheck plots are Plotly-only — see dash().

SetAnalyzer’s matplotlib show() is not implemented for QC because the QC tab is Plotly-driven. Raising rather than falling back to a placeholder so notebook users discover the right method.

Raises:

NotImplementedError – Always; use dash() instead.

Parameters:

args (Any)
kwargs (Any)

Return type:

summary() → pandas.DataFrame

Return a one-row-per-group summary of the most recent analyze.

The aggregate columns are prefixed with ``qc_`` so they can never collide with a groupby column on reset_index — a plate-layout column literally named status or num_rows would otherwise raise. The summary therefore always carries the group key columns plus the four prefixed aggregates.

Returns:: DataFrame with columns [*self.groupby, "qc_n_members", "qc_n_flagged", "qc_worst_metric", "qc_status"]. qc_worst_metric is the extreme metric value in the bad direction across the group: group[metric_col].max() when _HIGHER_IS_BAD is True, else group[metric_col].min(). qc_status is the worst status across the group: "fail" wins over "warn" which wins over "pass".
Return type:: pandas.DataFrame

table_spec(instance_id: str) → QcTableSpec

Return the catalog descriptor for this analyzed check.

Precondition: analyze() has run. Reads column roles from the class + instance config and derives extra_cols from the augmented frame.

Parameters:: instance_id (str) – The recipe entry id this check was built from.
Returns:: A populated QcTableSpec.
Return type:: QcTableSpec

to_table() → pandas.DataFrame

Return the module’s self-describing frame to persist to DuckDB.

Precondition: analyze() has run (this reads _latest_measurements). The default is member-level: the augmented frame projected to group-key + member-key + on + every QC_<name>_* column (metric/flag/status AND check-specific extras) + context columns (Metadata_Dataset and the column named by self.time_label) when those columns are present.

Diagnostic-only checks override to return a group-level frame.

Returns:: The projected DataFrame; columns vary per check (self-describing).
Return type:: pandas.DataFrame

agg_func: Callable | str | list | dict | None

fail_threshold: float

groupby: ColumnRefList

member_key_cols: ClassVar[tuple[str, ...]] = ('MetadataImage_ImageName', 'Object_Label'): Per-object curation-key columns. Empty tuple when the check has no per-object key. Subclasses may narrow this.

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

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

model_fields = {'agg_func': FieldInfo(annotation=Union[Callable, str, list, dict, NoneType], required=False, default='mean'), 'fail_threshold': FieldInfo(annotation=float, required=False, default=0.5, description='ICC at or below which ``Status`` becomes ``"fail"`` and ``Flag=True``. Defaults to ``0.50``.'), 'groupby': FieldInfo(annotation=list[str], required=True, metadata=[_ColumnRefMarker('measurements')]), 'n_jobs': FieldInfo(annotation=int, required=False, default=1, alias_priority=2, validation_alias=AliasChoices(choices=['n_jobs', 'num_workers'])), 'on': FieldInfo(annotation=str, required=True, metadata=[_ColumnRefMarker('measurements')]), 'rater_label': FieldInfo(annotation=str, required=False, default='MetadataSample_BioReplicate', description='Column whose distinct values index the *rater* (column) axis of the two-way model — the replicates that should agree. Defaults to ``"MetadataSample_BioReplicate"``.', metadata=[_ColumnRefMarker('measurements')]), 'subject_label': FieldInfo(annotation=str, required=False, default='MetadataCulture_Time', description='Column whose distinct values index the *subject* (row) axis of the two-way model — the repeated-measure axis. Defaults to ``"MetadataCulture_Time"`` so each timepoint is a subject and the ICC flags replicates that disagree relative to the growth trend. Override (e.g. ``"MetadataGenetic_Strain"``) for a snapshot reliability design.', metadata=[_ColumnRefMarker('measurements')]), 'unmatched_groups': FieldInfo(annotation=list, required=False, default_factory=list, description='Groups that the check could not evaluate (for example, expected counts whose group key never appeared in the data). Populated by subclasses that need to report missing combinations; empty by default.'), 'warn_threshold': FieldInfo(annotation=float, required=False, default=0.75, description='ICC at or below which ``Status`` becomes ``"warn"``. Defaults to ``0.75``.')}

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.

n_jobs: int

name: ClassVar[str] = 'ICC'

on: ColumnRef

rater_label: ColumnRef

subject_label: ColumnRef

supports_object_curation: ClassVar[bool] = True: Whether this check’s rows map to curatable detected objects. False for diagnostic-only checks (e.g. GridOccupancy) — the Review tab hides the curation radial + tile gallery and verified-good skips them.

unmatched_groups: list

warn_threshold: float

class phenotypic.analysis.LinearCapAndLagModel(*, on: Annotated[str, _ColumnRefMarker('measurements')], groupby: Annotated[list[str], _ColumnRefMarker('measurements')], agg_func: Callable | str | list | dict | None = 'mean', n_jobs: int = 1, time_label: Annotated[str, _ColumnRefMarker('measurements')] = 'MetadataCulture_Time', loss: Literal['linear', 'soft_l1', 'huber', 'cauchy', 'arctan'] = 'huber', f_scale: Annotated[float, Gt(gt=0), _PydanticGeneralMetadata(allow_inf_nan=False)] = 1.0, verbose: bool = False, stderr_label: str | None = None, s0_prior: Any = None, s0_prior_cv: float | None = None, s0_prior_sigma: float | None = None, s0_prior_groupby: list[str] | None = None, smax: float | None = None, beta: float | None = None, shoulder_slope_ratio: float = 0.05)[source]

Bases: _LinearSoftplusBase

Linear-softplus growth fitter with a softplus saturation ceiling.

Fits a linear post-lag growth phase with a softplus lag transition and a softplus saturation ceiling:

\[s_{\text{unclamped}}(t) = \frac{v}{\alpha}\, \ln\!\bigl(1 + e^{\alpha(t-\lambda)}\bigr) + s_0\]

\[s(t) = s_{\max} - \frac{1}{\beta}\,\ln\!\bigl(1 + e^{\beta(s_{\max} - s_{\text{unclamped}}(t))}\bigr)\]

Use this class when colonies show a clear carrying-capacity plateau in the observation window. For pre-saturation linear growth, use LinearLagModel instead.

Per-group mode dispatch:
The fit picks one of two variants per fit group, recorded in LINEAR_CAP_AND_LAG_MODEL.mode:

"fitted_beta" — 5-parameter fit. Triggered when beta is None and a saturation shoulder is detected in the group (smoothed tail slope flattens below shoulder_slope_ratio times the peak slope).

"fixed_beta" — 4-parameter fit with beta held constant. Triggered when the user supplied an explicit scalar beta, or when no shoulder is detected. The effective beta is self.beta when set, else the module default (10.0).

Pruning is intentionally not exposed on this class — the saturation plateau IS the model, so dropping the tail would defeat the fit.

Attributes:

smax (float | None): Fixed carrying capacity. None falls back
to the per-group observed max.

beta (float | None): Saturation transition sharpness. None
(default) opts into per-group mode dispatch — fit when a shoulder is present, otherwise held at the module default. Set a positive scalar to force "fixed_beta" mode unconditionally.

stderr_label (str | None): Column providing per-timepoint standard
errors used as weights. Same semantics as LinearLagModel.

s0_prior (bool | float | str | None): Unified Gaussian-prior
source for s0. Same dispatch as LinearLagModel.

s0_prior_cv (float | None): CV coefficient for the prior σ
(σ = cv × µ). Mutually exclusive with s0_prior_sigma. Defaults to None; if neither knob is set and the prior is engaged, CV=0.05 is applied.

s0_prior_sigma (float | None): Absolute σ for the prior.
Mutually exclusive with s0_prior_cv.

s0_prior_groupby (List[str] | None): Optional coarser grouping
for empirical-Bayes pooling of the per-group prior µ.

shoulder_slope_ratio (float): Fraction of peak ds/dt below
which the tail slope counts as a saturation shoulder for mode dispatch. Defaults to 0.05.

Output column naming:
analyze emits metric-qualified columns LinearCapAndLagModel_<metric>_<parameter> (e.g. fitting on="Shape_Area" yields LinearCapAndLagModel_Area_v), plus qualified fit-quality columns ModelMetrics_<metric>_<label>. The <metric> segment is self.on with a recognized measurement-category prefix stripped.

Note

``f_scale`` is unit-sensitive only on the unweighted fit path. The inherited f_scale (see ModelFitter) is the Huber/robust inlier–outlier threshold expressed in residual units, and those units depend on whether the fit is weighted:

Weighted (stderr_label set, or the default auto-derived replicate SEM when timepoints carry ≥2 replicates): residuals are divided by σ and are therefore dimensionless, so f_scale=1.0 means “one standard error” and is invariant to the units of on. No retuning is needed when the measurement scale changes.

Unweighted (no σ — e.g. single-replicate timepoints): residuals are in the native units of on, so f_scale is an absolute size threshold. If those units change (e.g. radius in px → mm, which shrinks residuals ~50×) f_scale must be rescaled to match, or the default robust loss="huber" never reaches its linear arm and silently degrades to ordinary least squares — losing all outlier suppression. loss="linear" ignores f_scale and is unaffected.

Category: **LinearCapAndLagModel**#
Name	Description	Type
`v`	The post-lag phase growth rate.	Tier 1 · Direct phenotype
`s0`	The initial size	Tier 1 · Direct phenotype
`lambda`	The duration of the lag phase	Tier 1 · Direct phenotype
`alpha`	lag phase transition sharpness	Tier 2 · Descriptive trait
`smax`	Carrying capacity used by the model. Either the user-provided scalar or the per-group observed maximum.	Tier 1 · Direct phenotype
`beta`	Saturation transition sharpness. Fitted per-group when a saturation shoulder is detected and `beta` is `None` at construction; held at the user-provided scalar (or the module default) when no shoulder is present.	Tier 2 · Descriptive trait
`mode`	Fit variant selected per-group: ‘fixed_beta’ (beta held at the user-provided or module-default value) or ‘fitted_beta’ (beta fitted as a 5th free parameter when a saturation shoulder is detected).	Quality

Parameters:

on (Annotated[str, _ColumnRefMarker('measurements')])
groupby (Annotated[list[str], _ColumnRefMarker('measurements')])
agg_func (Callable | str | list | dict | None)
n_jobs (int)
time_label (Annotated[str, _ColumnRefMarker('measurements')])
loss (Literal['linear', 'soft_l1', 'huber', 'cauchy', 'arctan'])
f_scale (float)
verbose (bool)
stderr_label (str | None)
s0_prior (Any)
s0_prior_cv (float | None)
s0_prior_sigma (float | None)
s0_prior_groupby (list[str] | None)
smax (float | None)
beta (float | None)
shoulder_slope_ratio (float)

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, copying parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot.

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:

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:

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:

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

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:

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

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:

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:

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:

classmethod update_forward_refs(**localns: Any) → None

Parameters:: localns (Any)
Return type:: None

classmethod validate(value: Any) → Self

Parameters:: value (Any)
Return type:: Self

static model_func(t: np.ndarray | float, v: float, s0: float, lam: float, alpha: float, smax: float, beta: float = 10.0) → float | np.ndarray[source]

Linear-softplus growth curve with softplus saturation ceiling.

Parameters:

t (np.ndarray | float) – Time (scalar or array).
v (float) – Post-lag growth rate.
s0 (float) – Initial size.
lam (float) – Lag duration.
alpha (float) – Lag transition sharpness.
smax (float) – Carrying capacity (saturation ceiling).
beta (float) – Saturation transition sharpness.

Returns:

Predicted size at t; scalar when t is scalar, otherwise an array.

Return type:

float | np.ndarray

__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

__init__(**data: Any) → None

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

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

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

Parameters:: data (Any)
Return type:: None

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

So dict(model) works.

Return type:: Generator[tuple[str, Any], None, None]

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

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

Parameters:

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

Return type:

__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

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

Pre-broadcast helper columns, then delegate to the base pipeline.

When stderr_label is None, a replicate-SEM column derived via groupby.transform("sem") so the weighted loss can downweight noisy timepoints automatically, plus a per-fit-group pooled point-level std column (f"{on}_std_pool") computed as the median of per- timepoint stds across the group’s n≥2 timepoints. The pool gives _resolve_y_stderr() a principled fallback σ for n=1 timepoints (σ ≈ typical point noise) instead of the vanishingly-small ε fill. Fit groups with zero multi- replicate timepoints produce NaN here and inherit the unweighted-residual fallback.
When the inoculum prior is column-based, a per-group median of inoc_size_label at the earliest observed timepoint is broadcast into a f"{label}_group_mean" column — the source of µ for the Gaussian prior on s0 (_InoculumPrior).

Each helper is constant within its effective group, so the base-class dict-style aggregation carries it through as a flat column without MultiIndex juggling.

Raises:: ValueError – If the inoculum prior is configured with an inoc_groupby that is not a subset of self.groupby, or references columns absent from data.
Parameters:: data (pandas.DataFrame)
Return type:: pandas.DataFrame

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

Interactive Plotly version of show().

Hover tooltips are populated from _hover_fields so subclasses can expose whichever fitted parameters and metrics are most meaningful for their model.

Parameters:

legend (bool | str) – Controls legend rendering. True (default) renders the legend with one entry per groupby combination (joined with ", "). False hides the legend. A string must be one of self.groupby; groups sharing a value in that column share both color and a single legend entry.
tmax (int | float | None)
criteria (Dict[str, Union[Any, List[Any]]] | None)
cmap (str | None)

Raises:

ImportError – If plotly is not installed.

Return type:

go.Figure

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:

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:

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:

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

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

model_post_init(_LinearSoftplusBase__context: Any) → None

Build the inoculum-prior helper from the resolved fields.

Runs after pydantic has validated every field. Constructing _InoculumPrior here preserves the original __init__-time validation: it raises TypeError for an unsupported s0_prior type and ValueError for a non-positive scalar, a mutually-exclusive σ pair, or an empty s0_prior_groupby list.

Parameters:

__context – Pydantic post-init context (unused).
_LinearSoftplusBase__context (Any)

Return type:

None

results() → pandas.DataFrame

Return the most recent fit results produced by analyze().

Return type:: pandas.DataFrame

Plot model predictions alongside measurements with optional filtering.

Parameters:

tmax (int | float | None) – Upper bound of the prediction curve. If None, uses the maximum observed time.
criteria (Dict[str, Union[Any, List[Any]]] | None) – Column/value filter applied to both fitted results and raw measurements before plotting.
figsize – Matplotlib figure size. Used only when ax is None.
cmap (str | None) – Matplotlib colormap name, a single color string, or None for matplotlib’s default color cycle.
legend (bool | str) – Controls legend rendering. True (default) renders the legend with one entry per groupby combination, labeled by the first groupby column. False hides the legend. A string must be one of self.groupby; groups sharing a value in that column share both color and a single legend entry. The legend is auto-removed if it is larger than the axes.
ax (plt.Axes | None) – Existing axes to draw into. A new figure is created when omitted.
**kwargs – Styling overrides — dpi, facecolor, edgecolor, line_width, marker_size, elinewidth, capsize, legend_loc, legend_fontsize, label.

Returns:

A (Figure, Axes) pair.

Return type:

Tuple[plt.Figure, plt.Axes]

agg_func: Callable | str | list | dict | None

beta: float | None

f_scale: float

groupby: ColumnRefList

loss: LossKind

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

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

model_fields = {'agg_func': FieldInfo(annotation=Union[Callable, str, list, dict, NoneType], required=False, default='mean'), 'beta': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Saturation transition sharpness. ``None`` (default) opts into per-group mode dispatch — fit when a shoulder is present, otherwise held at the module default. Set a positive scalar to force ``"fixed_beta"`` mode unconditionally.'), 'f_scale': FieldInfo(annotation=float, required=False, default=1.0, description='Soft margin between inlier and outlier residuals handed to :func:`scipy.optimize.least_squares`. Only affects robust ``loss`` choices; ignored when ``loss="linear"``. Must be positive and finite.', metadata=[Gt(gt=0), _PydanticGeneralMetadata(allow_inf_nan=False)]), 'groupby': FieldInfo(annotation=list[str], required=True, metadata=[_ColumnRefMarker('measurements')]), 'loss': FieldInfo(annotation=Literal['linear', 'soft_l1', 'huber', 'cauchy', 'arctan'], required=False, default='huber', description='Loss calculation method passed through to :func:`scipy.optimize.least_squares`. Defaults to ``"huber"`` — quadratic near zero and linear past ``f_scale``, so the fit behaves like standard least-squares on inliers but downweights rare large residuals (bubble artifacts, contamination spikes, mis-segmented timepoints). Pass ``"linear"`` to recover the classical unweighted-squared-residual loss, or ``"soft_l1"`` / ``"cauchy"`` / ``"arctan"`` for progressively more aggressive outlier suppression.'), 'n_jobs': FieldInfo(annotation=int, required=False, default=1, alias_priority=2, validation_alias=AliasChoices(choices=['n_jobs', 'num_workers'])), 'on': FieldInfo(annotation=str, required=True, metadata=[_ColumnRefMarker('measurements')]), 's0_prior': FieldInfo(annotation=Any, required=False, default=None, description='Unified Gaussian-prior source for ``s0``. Same dispatch as :class:`LinearLagModel`.'), 's0_prior_cv': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='CV coefficient for the prior σ (``σ = cv × µ``). Mutually exclusive with ``s0_prior_sigma``. Defaults to ``None``; if neither knob is set and the prior is engaged, CV=0.05 is applied.'), 's0_prior_groupby': FieldInfo(annotation=Union[list[str], NoneType], required=False, default=None, description='Optional coarser grouping for empirical-Bayes pooling of the per-group prior ``µ``.'), 's0_prior_sigma': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Absolute σ for the prior. Mutually exclusive with ``s0_prior_cv``.'), 'shoulder_slope_ratio': FieldInfo(annotation=float, required=False, default=0.05, description='Fraction of peak ``ds/dt`` below which the tail slope counts as a saturation shoulder for mode dispatch. Defaults to ``0.05``. Output column naming: ``analyze`` emits metric-qualified columns ``LinearCapAndLagModel_<metric>_<parameter>`` (e.g. fitting ``on="Shape_Area"`` yields ``LinearCapAndLagModel_Area_v``), plus qualified fit-quality columns ``ModelMetrics_<metric>_<label>``. The ``<metric>`` segment is ``self.on`` with a recognized measurement-category prefix stripped. .. note:: **``f_scale`` is unit-sensitive only on the unweighted fit path.** The inherited ``f_scale`` (see :class:`ModelFitter`) is the Huber/robust inlier–outlier threshold expressed in *residual units*, and those units depend on whether the fit is weighted: - **Weighted** (``stderr_label`` set, or the default auto-derived replicate SEM when timepoints carry ≥2 replicates): residuals are divided by σ and are therefore dimensionless, so ``f_scale=1.0`` means "one standard error" and is invariant to the units of ``on``. No retuning is needed when the measurement scale changes. - **Unweighted** (no σ — e.g. single-replicate timepoints): residuals are in the native units of ``on``, so ``f_scale`` is an absolute size threshold. If those units change (e.g. radius in px → mm, which shrinks residuals ~50×) ``f_scale`` must be rescaled to match, or the default robust ``loss="huber"`` never reaches its linear arm and silently degrades to ordinary least squares — losing all outlier suppression. ``loss="linear"`` ignores ``f_scale`` and is unaffected.'), 'smax': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Fixed carrying capacity. ``None`` falls back to the per-group observed max.'), 'stderr_label': FieldInfo(annotation=Union[str, NoneType], required=False, default=None, description='Column providing per-timepoint standard errors used as weights. Same semantics as :class:`LinearLagModel`.'), 'time_label': FieldInfo(annotation=str, required=False, default='MetadataCulture_Time', description='Column name representing the independent variable (typically time).', metadata=[_ColumnRefMarker('measurements')]), 'verbose': FieldInfo(annotation=bool, required=False, default=False, description='Whether to print detailed optimizer output.')}

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.

n_jobs: int

on: ColumnRef

s0_prior: Any

s0_prior_cv: float | None

s0_prior_groupby: list[str] | None

s0_prior_sigma: float | None

shoulder_slope_ratio: float

smax: float | None

stderr_label: str | None

time_label: ColumnRef

verbose: bool

class phenotypic.analysis.LinearLagModel(*, on: Annotated[str, _ColumnRefMarker('measurements')], groupby: Annotated[list[str], _ColumnRefMarker('measurements')], agg_func: Callable | str | list | dict | None = 'mean', n_jobs: int = 1, time_label: Annotated[str, _ColumnRefMarker('measurements')] = 'MetadataCulture_Time', loss: Literal['linear', 'soft_l1', 'huber', 'cauchy', 'arctan'] = 'huber', f_scale: Annotated[float, Gt(gt=0), _PydanticGeneralMetadata(allow_inf_nan=False)] = 1.0, verbose: bool = False, stderr_label: str | None = None, s0_prior: Any = None, s0_prior_cv: float | None = None, s0_prior_sigma: float | None = None, s0_prior_groupby: list[str] | None = None, prune_saturated: bool = True)[source]

Bases: _LinearSoftplusBase

Linear-with-softplus lag-phase growth fitter (no saturation).

Fits a 4-parameter linear post-lag growth model with a softplus lag transition:

\[s(t) = \frac{v}{\alpha}\, \ln\!\bigl(1 + e^{\alpha(t-\lambda)}\bigr) + s_0\]

Use this class when colonies are still in the linear-growth regime or when you want the saturation tail discarded as observation noise. For data with a clear carrying-capacity plateau, use LinearCapAndLagModel instead.

Pruning is ON by default — post-saturation timepoints are dropped from the fit so the linear regime is recovered cleanly. Disable with prune_saturated=False if your data is fully pre-saturation.

Attributes:

stderr_label (str | None): Column providing per-timepoint standard
errors used as weights in the fit. When None, the fit auto-derives a replicate-SE column during aggregation and a per-fit-group pooled point-level std (median across the n≥2 timepoints’ stds) that fills σ for any n=1 timepoints in the group. This keeps single-replicate rows from dominating the 1/σ² weighting — they get σ ≈ typical point noise instead of ε.

s0_prior (bool | float | str | None): Unified Gaussian-prior
source for s0. Dispatch (by type):

None or False → no prior (default).

True → ground on data: µ = median of self.on at the earliest observed timepoint within the effective group.

str → ground on named column: µ = median of data[s0_prior] at the earliest timepoint within the effective group.

positive float / int → scalar prior mean applied uniformly to every fit group.

s0_prior_cv (float | None): CV coefficient for the prior σ
(σ = cv × µ). Mutually exclusive with s0_prior_sigma. Defaults to None; if both s0_prior_cv and s0_prior_sigma are None and the prior is engaged, the helper applies CV=0.05 as a moderately informative default.

s0_prior_sigma (float | None): Absolute σ for the prior.
Mutually exclusive with s0_prior_cv. Use when the data scale makes a CV-based σ awkward (e.g. fractional / normalized data where µ < 1).

s0_prior_groupby (List[str] | None): Optional coarser grouping
(must be a subset of groupby) used for the per-group µ estimation on column-backed priors. When supplied, µ is pooled across replicate fits within each coarser group — an empirical-Bayes move appropriate when inoculation spread varies across conditions (e.g. per media). Only meaningful when s0_prior is True or a string.

prune_saturated (bool): Whether to drop post-saturation timepoints
before fitting. Defaults to True.

Output column naming:
analyze emits metric-qualified columns LinearLagModel_<metric>_<parameter> (e.g. fitting on="Shape_Area" yields LinearLagModel_Area_v), plus qualified fit-quality columns ModelMetrics_<metric>_<label>. The <metric> segment is self.on with a recognized measurement-category prefix stripped.

Note

``f_scale`` is unit-sensitive only on the unweighted fit path. The inherited f_scale (see ModelFitter) is the Huber/robust inlier–outlier threshold expressed in residual units, and those units depend on whether the fit is weighted:

Weighted (stderr_label set, or the default auto-derived replicate SEM when timepoints carry ≥2 replicates): residuals are divided by σ and are therefore dimensionless, so f_scale=1.0 means “one standard error” and is invariant to the units of on. No retuning is needed when the measurement scale changes.

Unweighted (no σ — e.g. single-replicate timepoints): residuals are in the native units of on, so f_scale is an absolute size threshold. If those units change (e.g. radius in px → mm, which shrinks residuals ~50×) f_scale must be rescaled to match, or the default robust loss="huber" never reaches its linear arm and silently degrades to ordinary least squares — losing all outlier suppression. loss="linear" ignores f_scale and is unaffected.

Category: **LinearLagModel**#
Name	Description	Type	Biology
`v`	The post-lag phase growth rate.	Tier 1 · Direct phenotype	The post-lag phase growth rate using the target metric (usually radius)
`s0`	The initial value of the target metric	Tier 1 · Direct phenotype	The initial size
`lambda`	The duration of the lag phase	Tier 1 · Direct phenotype
`alpha`	lag phase transition sharpness	Tier 2 · Descriptive trait

Parameters:

on (Annotated[str, _ColumnRefMarker('measurements')])
groupby (Annotated[list[str], _ColumnRefMarker('measurements')])
agg_func (Callable | str | list | dict | None)
n_jobs (int)
time_label (Annotated[str, _ColumnRefMarker('measurements')])
loss (Literal['linear', 'soft_l1', 'huber', 'cauchy', 'arctan'])
f_scale (float)
verbose (bool)
stderr_label (str | None)
s0_prior (Any)
s0_prior_cv (float | None)
s0_prior_sigma (float | None)
s0_prior_groupby (list[str] | None)
prune_saturated (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, copying parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot.

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:

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:

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:

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

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:

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

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:

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:

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:

classmethod update_forward_refs(**localns: Any) → None

Parameters:: localns (Any)
Return type:: None

classmethod validate(value: Any) → Self

Parameters:: value (Any)
Return type:: Self

static model_func(t: np.ndarray | float, v: float, s0: float, lam: float, alpha: float) → float | np.ndarray[source]

Linear-softplus growth curve, no saturation ceiling.

\[s(t) = \frac{v}{\alpha}\, \ln\!\bigl(1 + e^{\alpha(t-\lambda)}\bigr) + s_0\]

Parameters:

t (np.ndarray | float) – Time (scalar or array).
v (float) – Post-lag growth rate.
s0 (float) – Initial size.
lam (float) – Lag duration.
alpha (float) – Lag transition sharpness.

Returns:

Predicted size at t; scalar when t is scalar, otherwise an array.

Return type:

float | np.ndarray

__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

__init__(**data: Any) → None

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

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

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

Parameters:: data (Any)
Return type:: None

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

So dict(model) works.

Return type:: Generator[tuple[str, Any], None, None]

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

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

Parameters:

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

Return type:

__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

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

Pre-broadcast helper columns, then delegate to the base pipeline.

When stderr_label is None, a replicate-SEM column derived via groupby.transform("sem") so the weighted loss can downweight noisy timepoints automatically, plus a per-fit-group pooled point-level std column (f"{on}_std_pool") computed as the median of per- timepoint stds across the group’s n≥2 timepoints. The pool gives _resolve_y_stderr() a principled fallback σ for n=1 timepoints (σ ≈ typical point noise) instead of the vanishingly-small ε fill. Fit groups with zero multi- replicate timepoints produce NaN here and inherit the unweighted-residual fallback.
When the inoculum prior is column-based, a per-group median of inoc_size_label at the earliest observed timepoint is broadcast into a f"{label}_group_mean" column — the source of µ for the Gaussian prior on s0 (_InoculumPrior).

Each helper is constant within its effective group, so the base-class dict-style aggregation carries it through as a flat column without MultiIndex juggling.

Raises:: ValueError – If the inoculum prior is configured with an inoc_groupby that is not a subset of self.groupby, or references columns absent from data.
Parameters:: data (pandas.DataFrame)
Return type:: pandas.DataFrame

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

Interactive Plotly version of show().

Hover tooltips are populated from _hover_fields so subclasses can expose whichever fitted parameters and metrics are most meaningful for their model.

Parameters:

legend (bool | str) – Controls legend rendering. True (default) renders the legend with one entry per groupby combination (joined with ", "). False hides the legend. A string must be one of self.groupby; groups sharing a value in that column share both color and a single legend entry.
tmax (int | float | None)
criteria (Dict[str, Union[Any, List[Any]]] | None)
cmap (str | None)

Raises:

ImportError – If plotly is not installed.

Return type:

go.Figure

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:

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:

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:

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

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

model_post_init(_LinearSoftplusBase__context: Any) → None

Build the inoculum-prior helper from the resolved fields.

Runs after pydantic has validated every field. Constructing _InoculumPrior here preserves the original __init__-time validation: it raises TypeError for an unsupported s0_prior type and ValueError for a non-positive scalar, a mutually-exclusive σ pair, or an empty s0_prior_groupby list.

Parameters:

__context – Pydantic post-init context (unused).
_LinearSoftplusBase__context (Any)

Return type:

None

results() → pandas.DataFrame

Return the most recent fit results produced by analyze().

Return type:: pandas.DataFrame

Plot model predictions alongside measurements with optional filtering.

Parameters:

tmax (int | float | None) – Upper bound of the prediction curve. If None, uses the maximum observed time.
criteria (Dict[str, Union[Any, List[Any]]] | None) – Column/value filter applied to both fitted results and raw measurements before plotting.
figsize – Matplotlib figure size. Used only when ax is None.
cmap (str | None) – Matplotlib colormap name, a single color string, or None for matplotlib’s default color cycle.
legend (bool | str) – Controls legend rendering. True (default) renders the legend with one entry per groupby combination, labeled by the first groupby column. False hides the legend. A string must be one of self.groupby; groups sharing a value in that column share both color and a single legend entry. The legend is auto-removed if it is larger than the axes.
ax (plt.Axes | None) – Existing axes to draw into. A new figure is created when omitted.
**kwargs – Styling overrides — dpi, facecolor, edgecolor, line_width, marker_size, elinewidth, capsize, legend_loc, legend_fontsize, label.

Returns:

A (Figure, Axes) pair.

Return type:

Tuple[plt.Figure, plt.Axes]

agg_func: Callable | str | list | dict | None

f_scale: float

groupby: ColumnRefList

loss: LossKind

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

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

model_fields = {'agg_func': FieldInfo(annotation=Union[Callable, str, list, dict, NoneType], required=False, default='mean'), 'f_scale': FieldInfo(annotation=float, required=False, default=1.0, description='Soft margin between inlier and outlier residuals handed to :func:`scipy.optimize.least_squares`. Only affects robust ``loss`` choices; ignored when ``loss="linear"``. Must be positive and finite.', metadata=[Gt(gt=0), _PydanticGeneralMetadata(allow_inf_nan=False)]), 'groupby': FieldInfo(annotation=list[str], required=True, metadata=[_ColumnRefMarker('measurements')]), 'loss': FieldInfo(annotation=Literal['linear', 'soft_l1', 'huber', 'cauchy', 'arctan'], required=False, default='huber', description='Loss calculation method passed through to :func:`scipy.optimize.least_squares`. Defaults to ``"huber"`` — quadratic near zero and linear past ``f_scale``, so the fit behaves like standard least-squares on inliers but downweights rare large residuals (bubble artifacts, contamination spikes, mis-segmented timepoints). Pass ``"linear"`` to recover the classical unweighted-squared-residual loss, or ``"soft_l1"`` / ``"cauchy"`` / ``"arctan"`` for progressively more aggressive outlier suppression.'), 'n_jobs': FieldInfo(annotation=int, required=False, default=1, alias_priority=2, validation_alias=AliasChoices(choices=['n_jobs', 'num_workers'])), 'on': FieldInfo(annotation=str, required=True, metadata=[_ColumnRefMarker('measurements')]), 'prune_saturated': FieldInfo(annotation=bool, required=False, default=True, description='Whether to drop post-saturation timepoints before fitting. Defaults to ``True``. Output column naming: ``analyze`` emits metric-qualified columns ``LinearLagModel_<metric>_<parameter>`` (e.g. fitting ``on="Shape_Area"`` yields ``LinearLagModel_Area_v``), plus qualified fit-quality columns ``ModelMetrics_<metric>_<label>``. The ``<metric>`` segment is ``self.on`` with a recognized measurement-category prefix stripped. .. note:: **``f_scale`` is unit-sensitive only on the unweighted fit path.** The inherited ``f_scale`` (see :class:`ModelFitter`) is the Huber/robust inlier–outlier threshold expressed in *residual units*, and those units depend on whether the fit is weighted: - **Weighted** (``stderr_label`` set, or the default auto-derived replicate SEM when timepoints carry ≥2 replicates): residuals are divided by σ and are therefore dimensionless, so ``f_scale=1.0`` means "one standard error" and is invariant to the units of ``on``. No retuning is needed when the measurement scale changes. - **Unweighted** (no σ — e.g. single-replicate timepoints): residuals are in the native units of ``on``, so ``f_scale`` is an absolute size threshold. If those units change (e.g. radius in px → mm, which shrinks residuals ~50×) ``f_scale`` must be rescaled to match, or the default robust ``loss="huber"`` never reaches its linear arm and silently degrades to ordinary least squares — losing all outlier suppression. ``loss="linear"`` ignores ``f_scale`` and is unaffected.'), 's0_prior': FieldInfo(annotation=Any, required=False, default=None, description='Unified Gaussian-prior source for ``s0``. Dispatch (by type): - ``None`` or ``False`` → no prior (default). - ``True`` → ground on data: ``µ`` = median of ``self.on`` at the earliest observed timepoint within the effective group. - ``str`` → ground on named column: ``µ`` = median of ``data[s0_prior]`` at the earliest timepoint within the effective group. - positive ``float`` / ``int`` → scalar prior mean applied uniformly to every fit group.'), 's0_prior_cv': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='CV coefficient for the prior σ (``σ = cv × µ``). Mutually exclusive with ``s0_prior_sigma``. Defaults to ``None``; if both ``s0_prior_cv`` and ``s0_prior_sigma`` are ``None`` and the prior is engaged, the helper applies CV=0.05 as a moderately informative default.'), 's0_prior_groupby': FieldInfo(annotation=Union[list[str], NoneType], required=False, default=None, description='Optional coarser grouping (must be a subset of ``groupby``) used for the per-group ``µ`` estimation on column-backed priors. When supplied, ``µ`` is pooled across replicate fits within each coarser group — an empirical-Bayes move appropriate when inoculation spread varies across conditions (e.g. per media). Only meaningful when ``s0_prior`` is ``True`` or a string.'), 's0_prior_sigma': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Absolute σ for the prior. Mutually exclusive with ``s0_prior_cv``. Use when the data scale makes a CV-based σ awkward (e.g. fractional / normalized data where ``µ < 1``).'), 'stderr_label': FieldInfo(annotation=Union[str, NoneType], required=False, default=None, description="Column providing per-timepoint standard errors used as weights in the fit. When ``None``, the fit auto-derives a replicate-SE column during aggregation *and* a per-fit-group pooled point-level std (median across the n≥2 timepoints' stds) that fills σ for any n=1 timepoints in the group. This keeps single-replicate rows from dominating the 1/σ² weighting — they get σ ≈ typical point noise instead of ε."), 'time_label': FieldInfo(annotation=str, required=False, default='MetadataCulture_Time', description='Column name representing the independent variable (typically time).', metadata=[_ColumnRefMarker('measurements')]), 'verbose': FieldInfo(annotation=bool, required=False, default=False, description='Whether to print detailed optimizer output.')}

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.

n_jobs: int

on: ColumnRef

prune_saturated: bool

s0_prior: Any

s0_prior_cv: float | None

s0_prior_groupby: list[str] | None

s0_prior_sigma: float | None

stderr_label: str | None

time_label: ColumnRef

verbose: bool

class phenotypic.analysis.LogGrowthModel(*, on: Annotated[str, _ColumnRefMarker('measurements')], groupby: Annotated[list[str], _ColumnRefMarker('measurements')], agg_func: Callable | str | list | dict | None = 'mean', n_jobs: int = 1, time_label: Annotated[str, _ColumnRefMarker('measurements')] = 'MetadataCulture_Time', loss: Literal['linear', 'soft_l1', 'huber', 'cauchy', 'arctan'] = 'huber', f_scale: Annotated[float, Gt(gt=0), _PydanticGeneralMetadata(allow_inf_nan=False)] = 1.0, verbose: bool = False, lam: float = 1.2, beta: int | float = 2, Kmax_label: Annotated[str, _ColumnRefMarker('measurements')] | None = None)[source]

Bases: ModelFitter

Logistic-growth model fitter with regularized least-squares objective.

Logistic Kinetics Model:

\[N(t) = \frac{K}{1 + \frac{K - N_0}{N_0} e^{-rt}}\]

$N_t$: population size at time $t$

$N_0$: initial population size at time $t$

$r$: growth rate

$K$: carrying capacity (maximum population size)

From this we derive:

\[\mu_{\max} = \frac{K r}{4}\]

$\mu_{\max}$: maximum specific growth rate

Loss Function:

To solve for the parameters, we use the following loss function with the SciPy linear least-squares solver:

\[J(K, N_0, r) = \frac{1}{n}\sum_{i=1}^{n} \frac{1}{2}\left(f_{K,N_0,r}(t^{(i)}) - N_t^{(i)}\right)^2 + \lambda\left(\left(\frac{dN}{dt}\right)^2 + N_0^2\right) + \beta \frac{\lvert K - \max(N_t) \rvert}{N_t}\]

$\lambda$: regularization term for growth rate and initial population size

$\beta$: penalty term for deviations in carrying capacity relative to
the largest measurement

Output column naming:
analyze emits metric-qualified columns LogGrowthModel_<metric>_<parameter> (e.g. fitting on="Shape_Area" yields LogGrowthModel_Area_r and LogGrowthModel_Area_µmax), plus qualified fit-quality columns ModelMetrics_<metric>_<label>. The <metric> segment is self.on with a recognized measurement-category prefix stripped.

Attributes:
lam (float): The penalty factor applied to growth rates. beta (float): The maximum penalty factor applied to the carrying

capacity.

Kmax_label (str | None): The column name for the maximum carrying capacity
values, if provided.

Category: **LogGrowthModel**#
Name	Description	Type
`r`	The intrinsic growth rate	Tier 1 · Direct phenotype
`K`	The carrying capacity	Tier 1 · Direct phenotype
`N0`	The initial number of the colony size metric being fitted	Tier 1 · Direct phenotype
`lambda`	The regularization factor applied to the max specific growth rate and initial population size	Quality
`beta`	The penalty factor applied to relative difference of the carrying capacity from the largest measurement	Quality
`µmax`	The growth rate of the colony calculated as (K*r)/4	Tier 1 · Direct phenotype
`Kmax`	The upper bound of the carrying capacity for model fitting	Quality

Parameters:

on (Annotated[str, _ColumnRefMarker('measurements')])
groupby (Annotated[list[str], _ColumnRefMarker('measurements')])
agg_func (Callable | str | list | dict | None)
n_jobs (int)
time_label (Annotated[str, _ColumnRefMarker('measurements')])
loss (Literal['linear', 'soft_l1', 'huber', 'cauchy', 'arctan'])
f_scale (float)
verbose (bool)
lam (float)
beta (int | float)
Kmax_label (Annotated[str, _ColumnRefMarker('measurements')] | None)

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, copying parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot.

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:

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:

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:

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

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:

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

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:

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:

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:

classmethod update_forward_refs(**localns: Any) → None

Parameters:: localns (Any)
Return type:: None

classmethod validate(value: Any) → Self

Parameters:: value (Any)
Return type:: Self

static model_func(t: ndarray | float, r: float, K: float, N0: float)[source]

Logistic growth model evaluated at t.

\[N(t) = K / \left(1 + \frac{K - N_0}{N_0} e^{-rt}\right)\]

Parameters:

t (ndarray | float) – Time at which the population is evaluated (scalar or array).
r (float) – Growth rate.
K (float) – Carrying capacity.
N0 (float) – Initial population size at t = 0.

Returns:

Population size at t. Scalar when t is scalar, otherwise an array.

__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

__init__(**data: Any) → None

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

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

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

Parameters:: data (Any)
Return type:: None

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

So dict(model) works.

Return type:: Generator[tuple[str, Any], None, None]

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

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

Parameters:

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

Return type:

__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

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

Fit the model to every group of data and return the results.

Standard template: copy, float-coerce the time column, aggregate to one sample per timepoint, dispatch per-group fits (serial or parallel via joblib.Parallel), concatenate, and append constant hyperparameter columns from _post_fit_columns.

Parameters:: data (pandas.DataFrame)
Return type:: pandas.DataFrame

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

Interactive Plotly version of show().

Hover tooltips are populated from _hover_fields so subclasses can expose whichever fitted parameters and metrics are most meaningful for their model.

Parameters:

legend (bool | str) – Controls legend rendering. True (default) renders the legend with one entry per groupby combination (joined with ", "). False hides the legend. A string must be one of self.groupby; groups sharing a value in that column share both color and a single legend entry.
tmax (int | float | None)
criteria (Dict[str, Union[Any, List[Any]]] | None)
cmap (str | None)

Raises:

ImportError – If plotly is not installed.

Return type:

go.Figure

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:

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:

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:

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

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

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

results() → pandas.DataFrame

Return the most recent fit results produced by analyze().

Return type:: pandas.DataFrame

Plot model predictions alongside measurements with optional filtering.

Parameters:

tmax (int | float | None) – Upper bound of the prediction curve. If None, uses the maximum observed time.
criteria (Dict[str, Union[Any, List[Any]]] | None) – Column/value filter applied to both fitted results and raw measurements before plotting.
figsize – Matplotlib figure size. Used only when ax is None.
cmap (str | None) – Matplotlib colormap name, a single color string, or None for matplotlib’s default color cycle.
legend (bool | str) – Controls legend rendering. True (default) renders the legend with one entry per groupby combination, labeled by the first groupby column. False hides the legend. A string must be one of self.groupby; groups sharing a value in that column share both color and a single legend entry. The legend is auto-removed if it is larger than the axes.
ax (plt.Axes | None) – Existing axes to draw into. A new figure is created when omitted.
**kwargs – Styling overrides — dpi, facecolor, edgecolor, line_width, marker_size, elinewidth, capsize, legend_loc, legend_fontsize, label.

Returns:

A (Figure, Axes) pair.

Return type:

Tuple[plt.Figure, plt.Axes]

Kmax_label: Annotated[str, _ColumnRefMarker('measurements')] | None

agg_func: Callable | str | list | dict | None

beta: int | float

f_scale: float

groupby: ColumnRefList

lam: float

loss: LossKind

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

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

model_fields = {'Kmax_label': FieldInfo(annotation=Union[Annotated[str, _ColumnRefMarker], NoneType], required=False, default=None, description='The column name for the maximum carrying capacity values, if provided.'), 'agg_func': FieldInfo(annotation=Union[Callable, str, list, dict, NoneType], required=False, default='mean'), 'beta': FieldInfo(annotation=Union[int, float], required=False, default=2, description='The maximum penalty factor applied to the carrying capacity.'), 'f_scale': FieldInfo(annotation=float, required=False, default=1.0, description='Soft margin between inlier and outlier residuals handed to :func:`scipy.optimize.least_squares`. Only affects robust ``loss`` choices; ignored when ``loss="linear"``. Must be positive and finite.', metadata=[Gt(gt=0), _PydanticGeneralMetadata(allow_inf_nan=False)]), 'groupby': FieldInfo(annotation=list[str], required=True, metadata=[_ColumnRefMarker('measurements')]), 'lam': FieldInfo(annotation=float, required=False, default=1.2, description='The penalty factor applied to growth rates.'), 'loss': FieldInfo(annotation=Literal['linear', 'soft_l1', 'huber', 'cauchy', 'arctan'], required=False, default='huber', description='Loss calculation method passed through to :func:`scipy.optimize.least_squares`. Defaults to ``"huber"`` — quadratic near zero and linear past ``f_scale``, so the fit behaves like standard least-squares on inliers but downweights rare large residuals (bubble artifacts, contamination spikes, mis-segmented timepoints). Pass ``"linear"`` to recover the classical unweighted-squared-residual loss, or ``"soft_l1"`` / ``"cauchy"`` / ``"arctan"`` for progressively more aggressive outlier suppression.'), 'n_jobs': FieldInfo(annotation=int, required=False, default=1, alias_priority=2, validation_alias=AliasChoices(choices=['n_jobs', 'num_workers'])), 'on': FieldInfo(annotation=str, required=True, metadata=[_ColumnRefMarker('measurements')]), 'time_label': FieldInfo(annotation=str, required=False, default='MetadataCulture_Time', description='Column name representing the independent variable (typically time).', metadata=[_ColumnRefMarker('measurements')]), 'verbose': FieldInfo(annotation=bool, required=False, default=False, description='Whether to print detailed optimizer output.')}

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.

n_jobs: int

on: ColumnRef

time_label: ColumnRef

verbose: bool

class phenotypic.analysis.MADOutlierRemover(*, on: Annotated[str, _ColumnRefMarker('measurements')], groupby: Annotated[list[str], _ColumnRefMarker('measurements')], agg_func: Callable | str | list | dict | None = None, n_jobs: int = 1, threshold: float = 3.5)[source]

Bases: SetAnalyzer

Analyzer for removing outliers using the modified Z-score (MAD) method.

This class removes outliers from measurement data by applying the Iglewicz-Hoaglin modified Z-score test within groups. For each group it computes the median and the median absolute deviation (MAD) of the measurement column, scores every row as 0.6745 * |value - median| / MAD, and removes rows whose score exceeds threshold.

Unlike Tukey’s fence (see TukeyOutlierRemover), the MAD method estimates spread from the median absolute deviation, which has a 50% breakdown point: the test stays accurate even when up to half the rows in a group are contaminated. This makes it a robust default for small or skewed colony-measurement groups.

If MAD is zero for a group (all values identical, or a > 50% tie), the test falls back to the raw absolute deviation from the median scaled by the mean absolute deviation, preserving the breakdown point while avoiding division by zero. If every value is identical, no rows are removed.

Parameters:

on (Annotated[str, _ColumnRefMarker('measurements')]) – Name of measurement column to test for outliers (e.g., ‘Shape_Area’, ‘Intensity_IntegratedIntensity’).
groupby (Annotated[list[str], _ColumnRefMarker('measurements')]) – List of column names to group by (e.g., [‘StrainID’, ‘Time’]).
threshold (float) – Modified Z-score cutoff. Iglewicz & Hoaglin (1993) recommend 3.5 for general use. Lower values (e.g., 2.5) are more aggressive; higher values (e.g., 5.0) more conservative. Default is 3.5.
n_jobs (int) – Number of parallel workers. Default is 1.
agg_func (Callable | str | list | dict | None)

on

Column to test for outliers.

Type:: str

groupby

List of column names to group by.

Type:: list[str]

threshold

Modified Z-score cutoff used for outlier identification.

Type:: float

n_jobs

Number of parallel workers. Default is 1.

Type:: int

Examples

Remove outliers and visualize results:

>>> import pandas as pd
>>> import numpy as np
>>> from phenotypic.analysis import MADOutlierRemover
>>> # Create sample data with some outliers
>>> np.random.seed(42)
>>> data = pd.DataFrame({
...     'ImageName': ['img1'] * 50 + ['img2'] * 50,
...     'Area': np.concatenate([
...         np.random.normal(200, 30, 48),
...         [500, 550],  # outliers in img1
...         np.random.normal(180, 25, 48),
...         [50, 600]  # outliers in img2
...     ])
... })
>>> # Initialize detector
>>> detector = MADOutlierRemover(
...     on='Area',
...     groupby=['ImageName'],
...     threshold=3.5
... )
>>> # Remove outliers
>>> filtered_data = detector.analyze(data)
>>> # Check how many were removed
>>> print(f"Original: {len(data)}, Filtered: {len(filtered_data)}")
>>> # Visualize removed outliers
>>> fig = detector.show()

References

Iglewicz, B., & Hoaglin, D. C. (1993). How to Detect and Handle Outliers. ASQC Quality Press.

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, copying parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot.

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:

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:

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:

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

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:

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

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:

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:

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:

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

__init__(**data: Any) → None

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

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

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

Parameters:: data (Any)
Return type:: None

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

So dict(model) works.

Return type:: Generator[tuple[str, Any], None, None]

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

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

Parameters:

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

Return type:

__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

analyze(data: pandas.DataFrame) → pandas.DataFrame[source]

Remove outliers from data using the modified Z-score (MAD) method.

This method processes the input DataFrame by grouping according to specified columns and removing outliers within each group independently. Outliers are identified using the Iglewicz-Hoaglin modified Z-score and filtered out. The original data is stored internally for visualization purposes.

Parameters:

data (pandas.DataFrame) – DataFrame containing measurement data. Must include all columns specified in self.groupby and self.on.

Returns:

DataFrame with outliers removed. Contains only the original columns (no additional outlier flag columns).

Raises:

KeyError – If required columns are missing from input DataFrame.
ValueError – If data is empty or malformed.

Return type:

pandas.DataFrame

Examples

Analyze and filter outliers from measurement data:

>>> import pandas as pd
>>> import numpy as np
>>> from phenotypic.analysis import MADOutlierRemover
>>> # Create sample data
>>> np.random.seed(42)
>>> data = pd.DataFrame({
...     'ImageName': ['img1'] * 100,
...     'Area': np.concatenate([
...         np.random.normal(200, 30, 98),
...         [500, 50]  # outliers
...     ])
... })
>>> # Remove outliers
>>> detector = MADOutlierRemover(
...     on='Area',
...     groupby=['ImageName'],
...     threshold=3.5
... )
>>> filtered_data = detector.analyze(data)
>>> # Check results
>>> print(f"Original: {len(data)} rows, Filtered: {len(filtered_data)} rows")
>>> print(f"Removed {len(data) - len(filtered_data)} outliers")

Notes

Stores original data in self._original_data for visualization
Stores filtered results in self._latest_measurements for retrieval
Groups are processed independently with their own median and MAD
NaN values in measurement column are preserved in output

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

dash(**kwargs)

Interactive Plotly visualization of analysis results.

Subclasses may override this method to provide an interactive Plotly figure equivalent to show().

Raises:: NotImplementedError – Unless overridden by a subclass.

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:

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:

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:

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

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

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

results() → pandas.DataFrame[source]

Return the filtered results (outliers removed).

Returns the DataFrame with outliers removed from the most recent call to analyze().

Returns:: DataFrame with outliers filtered out. Contains only the original columns without additional outlier flag columns. If analyze() has not been called, returns an empty DataFrame.
Return type:: pandas.DataFrame

Examples

Retrieve filtered results after analysis:

>>> detector = MADOutlierRemover(
...     on='Area',
...     groupby=['ImageName']
... )
>>> filtered_data = detector.analyze(data)
>>> results_copy = detector.results()  # Same as filtered_data
>>> assert results_copy.equals(filtered_data)

Notes

Returns the DataFrame stored in self._latest_measurements
Contains only inliers (outliers have been removed)
Use this method to retrieve results after calling analyze()

show(figsize: tuple[int, int] | None = None, max_groups: int = 20, collapsed: bool = True, criteria: dict[str, Any] | None = None, **kwargs) → tuple[TypeAliasForwardRef('matplotlib.figure.Figure'), TypeAliasForwardRef('matplotlib.axes.Axes')][source]

Visualize outlier detection results.

Creates a visualization showing the distribution of values with outliers highlighted and modified Z-score bounds displayed. Can display as individual subplots or as a collapsed stacked view with all groups in a single plot. Outlier flags are computed dynamically for visualization only.

Parameters:

figsize (tuple[int, int] | None) – Figure size as (width, height). If None, automatically determined based on number of groups and mode.
max_groups (int) – Maximum number of groups to display. If there are more groups, only the first max_groups will be shown. Default is 20.
collapsed (bool) – If True, show all groups stacked vertically in a single plot. If False, show each group in its own subplot. Default is True.
criteria (dict[str, Any] | None) – Optional dictionary specifying filtering criteria for data selection. When provided, only groups matching the criteria will be displayed. Format: {‘column_name’: value} or {‘column_name’: [value1, value2]}. Default is None (show all groups).
**kwargs – Additional matplotlib parameters to customize the plot. Common options include: - dpi: Figure resolution (default 100) - facecolor: Figure background color - edgecolor: Figure edge color - grid_alpha: Alpha value for grid lines (default 0.3) - grid_axis: Which axis to apply grid to (‘both’, ‘x’, ‘y’) - legend_loc: Legend location (default ‘best’) - legend_fontsize: Font size for legend (default 8)

Returns:

Tuple of (Figure, Axes) containing the visualization.

Raises:

ValueError – If analyze() has not been called yet (no results to display).
KeyError – If criteria references columns not present in the data.

Return type:

tuple[TypeAliasForwardRef(‘matplotlib.figure.Figure’), TypeAliasForwardRef(‘matplotlib.axes.Axes’)]

Examples

Visualize outlier detection with multiple grouping options:

>>> import pandas as pd
>>> import numpy as np
>>> from phenotypic.analysis import MADOutlierRemover
>>> # Create sample data with multiple grouping columns
>>> np.random.seed(42)
>>> data = pd.DataFrame({
...     'ImageName': ['img1', 'img2'] * 50,
...     'Plate': ['P1'] * 50 + ['P2'] * 50,
...     'Area': np.concatenate([
...         np.random.normal(200, 30, 48), [500, 550],
...         np.random.normal(180, 25, 48), [50, 600]
...     ])
... })
>>> # Remove outliers and visualize all groups
>>> detector = MADOutlierRemover(
...     on='Area',
...     groupby=['Plate', 'ImageName'],
...     threshold=3.5
... )
>>> results = detector.analyze(data)
>>> fig, axes = detector.show(figsize=(12, 5))
>>> # Visualize only specific plate
>>> fig, axes = detector.show(criteria={'Plate': 'P1'})

Notes

Individual mode (collapsed=False): - Each group gets its own subplot with box plot - Outliers shown in red, normal values in blue - Horizontal lines show the modified Z-score bounds

Collapsed mode (collapsed=True): - All groups stacked vertically in single plot - Each group shown as horizontal line with median marker - Vertical bars show the modified Z-score bounds - Normal points as circles, outliers as diamonds

Filtering with criteria: - Only groups matching all criteria are displayed - Useful for focusing on specific plates, conditions, or subsets

agg_func: Callable | str | list | dict | None

groupby: ColumnRefList

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

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

model_fields = {'agg_func': FieldInfo(annotation=Union[Callable, str, list, dict, NoneType], required=False, default=None), 'groupby': FieldInfo(annotation=list[str], required=True, description='List of column names to group by.', metadata=[_ColumnRefMarker('measurements')]), 'n_jobs': FieldInfo(annotation=int, required=False, default=1, alias_priority=2, validation_alias=AliasChoices(choices=['n_jobs', 'num_workers']), description='Number of parallel workers. Default is 1.'), 'on': FieldInfo(annotation=str, required=True, description='Column to test for outliers.', metadata=[_ColumnRefMarker('measurements')]), 'threshold': FieldInfo(annotation=float, required=False, default=3.5, description='Modified Z-score cutoff used for outlier identification.')}

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.

n_jobs: int

on: ColumnRef

threshold: float

class phenotypic.analysis.MaxModifiedZScore(*, on: ~typing.Annotated[str, _ColumnRefMarker('measurements')], groupby: ~typing.Annotated[list[str], _ColumnRefMarker('measurements')], agg_func: ~typing.Callable | str | list | dict | None = 'mean', n_jobs: int = 1, warn_threshold: float = 3.5, fail_threshold: float = 5.0, unmatched_groups: list = <factory>, time_label: ~typing.Annotated[str, _ColumnRefMarker('measurements')] = 'MetadataCulture_Time', min_replicates: int = 2)[source]

Bases: QualityCheck

Flag (group, time) bins whose worst member is a robust outlier.

For each combination of self.groupby columns, this check splits the group by self.time_label and computes the Iglewicz-Hoaglin modified Z-score 0.6745 * |x - median| / MAD of every member at each timepoint. The per-bin metric is the maximum of those scores — the deviation of the single most-disagreeing member — so a bin fails as soon as one colony is far enough from the others. The per-bin scalars are broadcast back to every replicate row in the bin so the GUI can pick up the flag from any row.

_HIGHER_IS_BAD is True: a larger maximum modified Z-score means a worse outlier, so the base class flags rows whose metric meets or exceeds fail_threshold.

Two guard paths short-circuit to metric = NaN so under-powered or degenerate bins never gate curation (the base class treats NaN metric as Status="pass"):

``n < min_replicates`` — too few members for a meaningful robust Z-score. Defaults to min_replicates=2; raising it lets callers demand more statistical power.

All members identical — the bin median equals every value, so the MAD is zero and every modified Z-score is zero. A maximum of zero is reported as metric = NaN (perfect agreement is not an outlier and should never gate curation), matching the “no outliers” semantics of modified_z_scores().

When self.time_label is absent from the input data, the entire group is treated as a single timepoint bin so the check remains usable on snapshot (non-time-course) measurement frames.

The check does not aggregate measurement values — it builds the median/MAD summary statistics inside _compute() — so _exposes_agg_func is False and the GUI parameter-form rendering driver hides the agg_func field. The base SetAnalyzer.agg_func is preserved on the signature for parity only.
Attributes:

time_label: Column name carrying the timepoint within each
group. Defaults to "MetadataCulture_Time".

min_replicates: Minimum member count required before the modified
Z-score is considered meaningful. Bins below this threshold receive metric = NaN.

warn_threshold: Maximum modified Z-score at which Status
becomes "warn". Defaults to 3.5.

fail_threshold: Maximum modified Z-score at which Status
becomes "fail" and Flag=True. Defaults to 5.0.

Examples:
Basic — four members per timepoint, the check adds QC_ZMax_Metric plus the per-bin summary columns:
>>> import pandas as pd
>>> from phenotypic.analysis.qc import MaxModifiedZScore
>>> data = pd.DataFrame({
...     "Plate": ["P1"] * 8,
...     "MetadataCulture_Time": [0, 0, 0, 0, 1, 1, 1, 1],
...     "Size_Area": [
...         10.0, 10.1, 9.9, 10.2,
...         20.0, 20.1, 19.9, 60.0,
...     ],
... })
>>> chk = MaxModifiedZScore(
...     on="Size_Area",
...     groupby=["Plate"],
...     time_label="MetadataCulture_Time",
... )
>>> result = chk.analyze(data)
>>> "QC_ZMax_Metric" in result.columns
True
Advanced — only one member per (group, time) bin with min_replicates=2 triggers the under-powered guard:
>>> singleton = pd.DataFrame({
...     "Plate": ["P1", "P1"],
...     "MetadataCulture_Time": [0, 1],
...     "Size_Area": [10.0, 20.0],
... })
>>> chk = MaxModifiedZScore(
...     on="Size_Area",
...     groupby=["Plate"],
...     min_replicates=2,
... )
>>> result = chk.analyze(singleton)
>>> bool(result["QC_ZMax_Metric"].isna().all())
True

Category: **QC_ZMax**#
Name	Description	Type
`QC_ZMax_Flag`	True when the metric crosses fail_threshold in the bad direction; eligible for curation.	Quality
`QC_ZMax_Metric`	Headline metric in the check’s own units; the bad direction is set by the check’s _HIGHER_IS_BAD flag. Drives Status.	Quality
`QC_ZMax_Status`	Categorical: pass \| warn \| fail.	Quality

Parameters:

on (Annotated[str, _ColumnRefMarker('measurements')])
groupby (Annotated[list[str], _ColumnRefMarker('measurements')])
agg_func (Callable | str | list | dict | None)
n_jobs (int)
warn_threshold (float)
fail_threshold (float)
unmatched_groups (list)
time_label (Annotated[str, _ColumnRefMarker('measurements')])
min_replicates (int)

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 __init_subclass__(**kwargs: Any) → None

Append QC and per-check RST tables to the subclass docstring.

Skips intermediate ABCs that have not yet bound name. When the subclass declares both a docstring and a name, the generic QUALITY_CHECK table is appended (substituting name into the column headers). If _measurement_infoclass is also set, its table is appended as well so check-specific columns are documented alongside the generic trio.

Parameters:: kwargs (Any)
Return type:: None

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, copying parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot.

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:

classmethod flag_col() → str

Return the flag column name for this check.

Return type:: str

classmethod from_orm(obj: Any) → Self

Parameters:: obj (Any)
Return type:: Self

classmethod metric_col() → str

Return the metric column name for this check.

Return type:: str

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:

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:

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

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:

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

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:

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:

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:

classmethod status_col() → str

Return the status column name for this check.

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

__init__(**data: Any) → None

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

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

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

Parameters:: data (Any)
Return type:: None

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

So dict(model) works.

Return type:: Generator[tuple[str, Any], None, None]

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

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

Parameters:

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

Return type:

__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

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

Run the check on every group and return the augmented frame.

Iterates over data.groupby(self.groupby, dropna=False), delegates per-group computation to _compute(), and adds three generic columns derived from the metric:

QC_<name>_Metric (carry-through from _compute)
QC_<name>_Flag (bool)
QC_<name>_Status ("pass" / "warn" / "fail")

Flag and Status are directional. With _HIGHER_IS_BAD=True a row fails when metric >= fail_threshold and warns when metric >= warn_threshold; with _HIGHER_IS_BAD=False the comparisons invert to <=. A NaN metric always yields Status="pass" and Flag=False.

Rows are never dropped. The augmented frame is stored on _latest_measurements and returned.

Parameters:: data (pandas.DataFrame) – Input measurement frame. Must contain self.on and every column in self.groupby.
Returns:: The input frame with the three generic QC columns appended plus whatever _compute contributed.
Raises:: KeyError – If self.on or any column in self.groupby is missing from data.
Return type:: pandas.DataFrame

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

dash(**kwargs)

Interactive Plotly visualization of analysis results.

Subclasses may override this method to provide an interactive Plotly figure equivalent to show().

Raises:: NotImplementedError – Unless overridden by a subclass.

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:

flagged_keys() → list[tuple[str, int]]

Return (Metadata_ImageName, Object_Label) pairs to curate.

Used by the GUI “Mark all flagged for removal” button. Requires the analyzed frame to carry both Metadata_ImageName and Object_Label columns (the curation key used by STORE_REMOVED_KEYS). Returns an empty list when those columns are absent or when no rows were flagged.

Returns:: De-duplicated list of (image_file, object_label) tuples for rows where Flag=True.
Return type:: list[tuple[str, int]]

group_members() → dict[tuple, list[tuple[str, int, Any]]]

Map each group key to its member rows for worklists/galleries.

Walks the most recent analyzed frame and, for every group key produced by data.groupby(self.groupby, dropna=False), collects the rows that belong to it as (Metadata_ImageName, Object_Label, member_value) tuples, where member_value is the row’s self.on value (the column the check operates on). The mapping preserves group iteration order.

Mirrors flagged_keys()’s guard: if the analyzed frame lacks either Metadata_ImageName or the object-label column, an empty mapping is returned rather than raising.

Returns:: Ordered mapping of group key (always a tuple, even for a single groupby column) to a list of (image_file, object_label, member_value) tuples. Empty when the curation key columns are absent.
Return type:: dict[tuple, list[tuple[str, int, 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)
encoder (Callable[[Any], Any] | None)
models_as_dict (bool)
dumps_kwargs (Any)

Return type:

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:

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

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

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

results() → pandas.DataFrame

Return the augmented frame stored by the most recent analyze().

Return type:: pandas.DataFrame

show(*args: Any, **kwargs: Any) → Any

QualityCheck plots are Plotly-only — see dash().

SetAnalyzer’s matplotlib show() is not implemented for QC because the QC tab is Plotly-driven. Raising rather than falling back to a placeholder so notebook users discover the right method.

Raises:

NotImplementedError – Always; use dash() instead.

Parameters:

args (Any)
kwargs (Any)

Return type:

summary() → pandas.DataFrame

Return a one-row-per-group summary of the most recent analyze.

The aggregate columns are prefixed with ``qc_`` so they can never collide with a groupby column on reset_index — a plate-layout column literally named status or num_rows would otherwise raise. The summary therefore always carries the group key columns plus the four prefixed aggregates.

Returns:: DataFrame with columns [*self.groupby, "qc_n_members", "qc_n_flagged", "qc_worst_metric", "qc_status"]. qc_worst_metric is the extreme metric value in the bad direction across the group: group[metric_col].max() when _HIGHER_IS_BAD is True, else group[metric_col].min(). qc_status is the worst status across the group: "fail" wins over "warn" which wins over "pass".
Return type:: pandas.DataFrame

table_spec(instance_id: str) → QcTableSpec

Return the catalog descriptor for this analyzed check.

Precondition: analyze() has run. Reads column roles from the class + instance config and derives extra_cols from the augmented frame.

Parameters:: instance_id (str) – The recipe entry id this check was built from.
Returns:: A populated QcTableSpec.
Return type:: QcTableSpec

to_table() → pandas.DataFrame

Return the module’s self-describing frame to persist to DuckDB.

Precondition: analyze() has run (this reads _latest_measurements). The default is member-level: the augmented frame projected to group-key + member-key + on + every QC_<name>_* column (metric/flag/status AND check-specific extras) + context columns (Metadata_Dataset and the column named by self.time_label) when those columns are present.

Diagnostic-only checks override to return a group-level frame.

Returns:: The projected DataFrame; columns vary per check (self-describing).
Return type:: pandas.DataFrame

agg_func: Callable | str | list | dict | None

fail_threshold: float

groupby: ColumnRefList

member_key_cols: ClassVar[tuple[str, ...]] = ('MetadataImage_ImageName', 'Object_Label'): Per-object curation-key columns. Empty tuple when the check has no per-object key. Subclasses may narrow this.

min_replicates: int

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

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

model_fields = {'agg_func': FieldInfo(annotation=Union[Callable, str, list, dict, NoneType], required=False, default='mean'), 'fail_threshold': FieldInfo(annotation=float, required=False, default=5.0, description='Maximum modified Z-score at which ``Status`` becomes ``"fail"`` and ``Flag=True``. Defaults to ``5.0``.'), 'groupby': FieldInfo(annotation=list[str], required=True, metadata=[_ColumnRefMarker('measurements')]), 'min_replicates': FieldInfo(annotation=int, required=False, default=2, description='Minimum member count required before the modified Z-score is considered meaningful. Bins below this threshold receive ``metric = NaN``.'), 'n_jobs': FieldInfo(annotation=int, required=False, default=1, alias_priority=2, validation_alias=AliasChoices(choices=['n_jobs', 'num_workers'])), 'on': FieldInfo(annotation=str, required=True, metadata=[_ColumnRefMarker('measurements')]), 'time_label': FieldInfo(annotation=str, required=False, default='MetadataCulture_Time', description='Column name carrying the timepoint within each group. Defaults to ``"MetadataCulture_Time"``.', metadata=[_ColumnRefMarker('measurements')]), 'unmatched_groups': FieldInfo(annotation=list, required=False, default_factory=list, description='Groups that the check could not evaluate (for example, expected counts whose group key never appeared in the data). Populated by subclasses that need to report missing combinations; empty by default.'), 'warn_threshold': FieldInfo(annotation=float, required=False, default=3.5, description='Maximum modified Z-score at which ``Status`` becomes ``"warn"``. Defaults to ``3.5``.')}

property model_fields_set: set[str]

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

Returns:

A set of strings representing the fields that have been set,: i.e. that were not filled from defaults.

n_jobs: int

name: ClassVar[str] = 'ZMax'

on: ColumnRef

supports_object_curation: ClassVar[bool] = True: Whether this check’s rows map to curatable detected objects. False for diagnostic-only checks (e.g. GridOccupancy) — the Review tab hides the curation radial + tile gallery and verified-good skips them.

time_label: ColumnRef

unmatched_groups: list

warn_threshold: float

class phenotypic.analysis.RelativeMAD(*, on: ~typing.Annotated[str, _ColumnRefMarker('measurements')], groupby: ~typing.Annotated[list[str], _ColumnRefMarker('measurements')], agg_func: ~typing.Callable | str | list | dict | None = 'mean', n_jobs: int = 1, warn_threshold: float = 0.1, fail_threshold: float = 0.2, unmatched_groups: list = <factory>, time_label: ~typing.Annotated[str, _ColumnRefMarker('measurements')] = 'MetadataCulture_Time', min_replicates: int = 2, eps: float = 1e-09)[source]

Bases: QualityCheck

Flag (group, time) bins with poor robust agreement across replicates.

For each combination of self.groupby columns, this check splits the group by self.time_label and computes the median absolute deviation (MAD) of the measurement across replicates at every timepoint. The relative MAD metric = MAD / |median| is the per-bin metric; bins whose metric exceeds the warn/fail thresholds are surfaced for curation. The per-bin scalars are broadcast back to every replicate row in the bin so the GUI can pick up the flag from any row.

Because the MAD has a 50% breakdown point, the metric stays accurate even when up to half the replicates in a bin are contaminated — a single mis-segmented or contaminated colony will not inflate it the way it inflates the relative standard error. It is therefore the robust counterpart to ReplicateAgreement.

_HIGHER_IS_BAD is True: a larger relative MAD means worse replicate agreement, so the base class flags rows whose metric meets or exceeds fail_threshold.

Three guard paths short-circuit to metric = NaN so under-powered or degenerate bins never gate curation (the base class treats NaN metric as Status="pass"):

``n < min_replicates`` — too few replicates for a meaningful spread estimate. Defaults to min_replicates=2; raising it lets callers demand more statistical power.

``|median| < eps`` — the relative-MAD ratio blows up at zero median, so near-zero baseline measurements (t=0 wells, blank wells, true-zero conditions) would otherwise flag every row. The default eps=1e-9 catches sensor-zero readouts without losing genuinely-above-noise-floor measurements.

``MAD == 0`` and ``median == 0`` — degenerate bin (all replicates exactly zero); mathematically undefined. Treated as pass.

When self.time_label is absent from the input data, the entire group is treated as a single timepoint bin so the check remains usable on snapshot (non-time-course) measurement frames.

The check does not aggregate measurement values — it builds the median/MAD summary statistics inside _compute() — so _exposes_agg_func is False and the GUI parameter-form rendering driver hides the agg_func field. The base SetAnalyzer.agg_func is preserved on the signature for parity only.
Attributes:

time_label: Column name carrying the timepoint within each
group. Defaults to "MetadataCulture_Time".

min_replicates: Minimum replicate count required before the MAD
is considered meaningful. Bins below this threshold receive metric = NaN.

eps: Floor on |median| below which the relative-MAD ratio is
considered undefined. Bins below this floor receive metric = NaN.

warn_threshold: Relative MAD at which Status becomes
"warn". Defaults to 0.10.

fail_threshold: Relative MAD at which Status becomes
"fail" and Flag=True. Defaults to 0.20.

Examples:
Basic — three-replicate, four-timepoint synthetic frame; the check adds QC_MAD_Metric plus the per-bin summary columns:
>>> import pandas as pd
>>> from phenotypic.analysis.qc import RelativeMAD
>>> times = [0, 1, 2, 3]
>>> data = pd.DataFrame({
...     "Plate": ["P1"] * 12,
...     "MetadataCulture_Time": [t for t in times for _ in range(3)],
...     "Replicate": [1, 2, 3] * 4,
...     "Size_Area": [
...         10.0, 10.1, 9.9,
...         20.0, 20.2, 19.8,
...         40.0, 40.4, 39.6,
...         80.0, 80.8, 79.2,
...     ],
... })
>>> chk = RelativeMAD(
...     on="Size_Area",
...     groupby=["Plate"],
...     time_label="MetadataCulture_Time",
... )
>>> result = chk.analyze(data)
>>> "QC_MAD_Metric" in result.columns
True
Advanced — only one replicate per (group, time) bin with min_replicates=2 triggers the under-powered guard:
>>> singleton = pd.DataFrame({
...     "Plate": ["P1", "P1"],
...     "MetadataCulture_Time": [0, 1],
...     "Size_Area": [10.0, 20.0],
... })
>>> chk = RelativeMAD(
...     on="Size_Area",
...     groupby=["Plate"],
...     min_replicates=2,
... )
>>> result = chk.analyze(singleton)
>>> bool(result["QC_MAD_Metric"].isna().all())
True

Category: **QC_MAD**#
Name	Description	Type
`QC_MAD_Flag`	True when the metric crosses fail_threshold in the bad direction; eligible for curation.	Quality
`QC_MAD_Metric`	Headline metric in the check’s own units; the bad direction is set by the check’s _HIGHER_IS_BAD flag. Drives Status.	Quality
`QC_MAD_Status`	Categorical: pass \| warn \| fail.	Quality

Parameters:

on (Annotated[str, _ColumnRefMarker('measurements')])
groupby (Annotated[list[str], _ColumnRefMarker('measurements')])
agg_func (Callable | str | list | dict | None)
n_jobs (int)
warn_threshold (float)
fail_threshold (float)
unmatched_groups (list)
time_label (Annotated[str, _ColumnRefMarker('measurements')])
min_replicates (int)
eps (float)

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 __init_subclass__(**kwargs: Any) → None

Append QC and per-check RST tables to the subclass docstring.

Skips intermediate ABCs that have not yet bound name. When the subclass declares both a docstring and a name, the generic QUALITY_CHECK table is appended (substituting name into the column headers). If _measurement_infoclass is also set, its table is appended as well so check-specific columns are documented alongside the generic trio.

Parameters:: kwargs (Any)
Return type:: None

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, copying parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot.

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:

classmethod flag_col() → str

Return the flag column name for this check.

Return type:: str

classmethod from_orm(obj: Any) → Self

Parameters:: obj (Any)
Return type:: Self

classmethod metric_col() → str

Return the metric column name for this check.

Return type:: str

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:

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:

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

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:

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

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:

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:

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:

classmethod status_col() → str

Return the status column name for this check.

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

__init__(**data: Any) → None

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

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

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

Parameters:: data (Any)
Return type:: None

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

So dict(model) works.

Return type:: Generator[tuple[str, Any], None, None]

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

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

Parameters:

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

Return type:

__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

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

Run the check on every group and return the augmented frame.

Iterates over data.groupby(self.groupby, dropna=False), delegates per-group computation to _compute(), and adds three generic columns derived from the metric:

QC_<name>_Metric (carry-through from _compute)
QC_<name>_Flag (bool)
QC_<name>_Status ("pass" / "warn" / "fail")

Flag and Status are directional. With _HIGHER_IS_BAD=True a row fails when metric >= fail_threshold and warns when metric >= warn_threshold; with _HIGHER_IS_BAD=False the comparisons invert to <=. A NaN metric always yields Status="pass" and Flag=False.

Rows are never dropped. The augmented frame is stored on _latest_measurements and returned.

Parameters:: data (pandas.DataFrame) – Input measurement frame. Must contain self.on and every column in self.groupby.
Returns:: The input frame with the three generic QC columns appended plus whatever _compute contributed.
Raises:: KeyError – If self.on or any column in self.groupby is missing from data.
Return type:: pandas.DataFrame

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

dash(**kwargs)

Interactive Plotly visualization of analysis results.

Subclasses may override this method to provide an interactive Plotly figure equivalent to show().

Raises:: NotImplementedError – Unless overridden by a subclass.

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:

flagged_keys() → list[tuple[str, int]]

Return (Metadata_ImageName, Object_Label) pairs to curate.

Used by the GUI “Mark all flagged for removal” button. Requires the analyzed frame to carry both Metadata_ImageName and Object_Label columns (the curation key used by STORE_REMOVED_KEYS). Returns an empty list when those columns are absent or when no rows were flagged.

Returns:: De-duplicated list of (image_file, object_label) tuples for rows where Flag=True.
Return type:: list[tuple[str, int]]

group_members() → dict[tuple, list[tuple[str, int, Any]]]

Map each group key to its member rows for worklists/galleries.

Walks the most recent analyzed frame and, for every group key produced by data.groupby(self.groupby, dropna=False), collects the rows that belong to it as (Metadata_ImageName, Object_Label, member_value) tuples, where member_value is the row’s self.on value (the column the check operates on). The mapping preserves group iteration order.

Mirrors flagged_keys()’s guard: if the analyzed frame lacks either Metadata_ImageName or the object-label column, an empty mapping is returned rather than raising.

Returns:: Ordered mapping of group key (always a tuple, even for a single groupby column) to a list of (image_file, object_label, member_value) tuples. Empty when the curation key columns are absent.
Return type:: dict[tuple, list[tuple[str, int, 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)
encoder (Callable[[Any], Any] | None)
models_as_dict (bool)
dumps_kwargs (Any)

Return type:

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:

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

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

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

results() → pandas.DataFrame

Return the augmented frame stored by the most recent analyze().

Return type:: pandas.DataFrame

show(*args: Any, **kwargs: Any) → Any

QualityCheck plots are Plotly-only — see dash().

SetAnalyzer’s matplotlib show() is not implemented for QC because the QC tab is Plotly-driven. Raising rather than falling back to a placeholder so notebook users discover the right method.

Raises:

NotImplementedError – Always; use dash() instead.

Parameters:

args (Any)
kwargs (Any)

Return type:

summary() → pandas.DataFrame

Return a one-row-per-group summary of the most recent analyze.

The aggregate columns are prefixed with ``qc_`` so they can never collide with a groupby column on reset_index — a plate-layout column literally named status or num_rows would otherwise raise. The summary therefore always carries the group key columns plus the four prefixed aggregates.

Returns:: DataFrame with columns [*self.groupby, "qc_n_members", "qc_n_flagged", "qc_worst_metric", "qc_status"]. qc_worst_metric is the extreme metric value in the bad direction across the group: group[metric_col].max() when _HIGHER_IS_BAD is True, else group[metric_col].min(). qc_status is the worst status across the group: "fail" wins over "warn" which wins over "pass".
Return type:: pandas.DataFrame

table_spec(instance_id: str) → QcTableSpec

Return the catalog descriptor for this analyzed check.

Precondition: analyze() has run. Reads column roles from the class + instance config and derives extra_cols from the augmented frame.

Parameters:: instance_id (str) – The recipe entry id this check was built from.
Returns:: A populated QcTableSpec.
Return type:: QcTableSpec

to_table() → pandas.DataFrame

Return the module’s self-describing frame to persist to DuckDB.

Precondition: analyze() has run (this reads _latest_measurements). The default is member-level: the augmented frame projected to group-key + member-key + on + every QC_<name>_* column (metric/flag/status AND check-specific extras) + context columns (Metadata_Dataset and the column named by self.time_label) when those columns are present.

Diagnostic-only checks override to return a group-level frame.

Returns:: The projected DataFrame; columns vary per check (self-describing).
Return type:: pandas.DataFrame

agg_func: Callable | str | list | dict | None

eps: float

fail_threshold: float

groupby: ColumnRefList

member_key_cols: ClassVar[tuple[str, ...]] = ('MetadataImage_ImageName', 'Object_Label'): Per-object curation-key columns. Empty tuple when the check has no per-object key. Subclasses may narrow this.

min_replicates: int

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

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

model_fields = {'agg_func': FieldInfo(annotation=Union[Callable, str, list, dict, NoneType], required=False, default='mean'), 'eps': FieldInfo(annotation=float, required=False, default=1e-09, description='Floor on ``|median|`` below which the relative-MAD ratio is considered undefined. Bins below this floor receive ``metric = NaN``.'), 'fail_threshold': FieldInfo(annotation=float, required=False, default=0.2, description='Relative MAD at which ``Status`` becomes ``"fail"`` and ``Flag=True``. Defaults to ``0.20``.'), 'groupby': FieldInfo(annotation=list[str], required=True, metadata=[_ColumnRefMarker('measurements')]), 'min_replicates': FieldInfo(annotation=int, required=False, default=2, description='Minimum replicate count required before the MAD is considered meaningful. Bins below this threshold receive ``metric = NaN``.'), 'n_jobs': FieldInfo(annotation=int, required=False, default=1, alias_priority=2, validation_alias=AliasChoices(choices=['n_jobs', 'num_workers'])), 'on': FieldInfo(annotation=str, required=True, metadata=[_ColumnRefMarker('measurements')]), 'time_label': FieldInfo(annotation=str, required=False, default='MetadataCulture_Time', description='Column name carrying the timepoint within each group. Defaults to ``"MetadataCulture_Time"``.', metadata=[_ColumnRefMarker('measurements')]), 'unmatched_groups': FieldInfo(annotation=list, required=False, default_factory=list, description='Groups that the check could not evaluate (for example, expected counts whose group key never appeared in the data). Populated by subclasses that need to report missing combinations; empty by default.'), 'warn_threshold': FieldInfo(annotation=float, required=False, default=0.1, description='Relative MAD at which ``Status`` becomes ``"warn"``. Defaults to ``0.10``.')}

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.

n_jobs: int

name: ClassVar[str] = 'MAD'

on: ColumnRef

supports_object_curation: ClassVar[bool] = True: Whether this check’s rows map to curatable detected objects. False for diagnostic-only checks (e.g. GridOccupancy) — the Review tab hides the curation radial + tile gallery and verified-good skips them.

time_label: ColumnRef

unmatched_groups: list

warn_threshold: float

class phenotypic.analysis.ReplicateAgreement(*, on: ~typing.Annotated[str, _ColumnRefMarker('measurements')], groupby: ~typing.Annotated[list[str], _ColumnRefMarker('measurements')], agg_func: ~typing.Callable | str | list | dict | None = 'mean', n_jobs: int = 1, warn_threshold: float = 0.1, fail_threshold: float = 0.2, unmatched_groups: list = <factory>, time_label: ~typing.Annotated[str, _ColumnRefMarker('measurements')] = 'MetadataCulture_Time', min_replicates: int = 2, eps: float = 1e-09)[source]

Bases: QualityCheck

Flag (group, time) bins with poor agreement across replicates.

For each combination of self.groupby columns, this check splits the group by self.time_label and computes the standard error of the measurement across replicates at every timepoint. The relative standard error metric = |SE| / |mean| is the per-bin metric; bins whose metric exceeds the warn/fail thresholds are surfaced for curation. The per-bin scalars are broadcast back to every replicate row in the bin so the GUI can pick up the flag from any row.

_HIGHER_IS_BAD is True: a larger relative SE means worse replicate agreement, so the base class flags rows whose metric meets or exceeds fail_threshold.

Three guard paths short-circuit to metric = NaN so under-powered or degenerate bins never gate curation (the base class treats NaN metric as Status="pass"):

``n < min_replicates`` — too few replicates for a meaningful standard error. Defaults to min_replicates=2; raising it lets callers demand more statistical power.

``|mean| < eps`` — the relative-SE ratio blows up at zero mean, so near-zero baseline measurements (t=0 wells, blank wells, true-zero conditions) would otherwise flag every row. The default eps=1e-9 catches sensor-zero readouts without losing genuinely-above-noise-floor measurements.

``stddev == 0`` and ``mean == 0`` — degenerate bin (all replicates exactly zero); mathematically undefined. Treated as pass.

When self.time_label is absent from the input data, the entire group is treated as a single timepoint bin so the check remains usable on snapshot (non-time-course) measurement frames.

The check does not aggregate measurement values — it builds the SE/Mean/CV summary statistics inside _compute() — so _exposes_agg_func is False and the GUI parameter-form rendering driver hides the agg_func field. The base SetAnalyzer.agg_func is preserved on the signature for parity only.
Attributes:

time_label: Column name carrying the timepoint within each
group. Defaults to "MetadataCulture_Time".

min_replicates: Minimum replicate count required before SE is
considered meaningful. Bins below this threshold receive metric = NaN.

eps: Floor on |mean| below which the relative-SE ratio is
considered undefined. Bins below this floor receive metric = NaN.

warn_threshold: Relative SE at which Status becomes
"warn". Defaults to 0.10.

fail_threshold: Relative SE at which Status becomes
"fail" and Flag=True. Defaults to 0.20.

Examples:
Basic — three-replicate, four-timepoint synthetic frame; the check adds QC_SE_Metric plus the per-bin summary columns:
>>> import pandas as pd
>>> from phenotypic.analysis.qc import (
...     ReplicateAgreement,
... )
>>> times = [0, 1, 2, 3]
>>> data = pd.DataFrame({
...     "Plate": ["P1"] * 12,
...     "MetadataCulture_Time": [t for t in times for _ in range(3)],
...     "Replicate": [1, 2, 3] * 4,
...     "Size_Area": [
...         10.0, 10.1, 9.9,
...         20.0, 20.2, 19.8,
...         40.0, 40.4, 39.6,
...         80.0, 80.8, 79.2,
...     ],
... })
>>> chk = ReplicateAgreement(
...     on="Size_Area",
...     groupby=["Plate"],
...     time_label="MetadataCulture_Time",
... )
>>> result = chk.analyze(data)
>>> "QC_SE_Metric" in result.columns
True
Advanced — only one replicate per (group, time) bin with min_replicates=2 triggers the under-powered guard:
>>> singleton = pd.DataFrame({
...     "Plate": ["P1", "P1"],
...     "MetadataCulture_Time": [0, 1],
...     "Size_Area": [10.0, 20.0],
... })
>>> chk = ReplicateAgreement(
...     on="Size_Area",
...     groupby=["Plate"],
...     min_replicates=2,
... )
>>> result = chk.analyze(singleton)
>>> bool(result["QC_SE_Metric"].isna().all())
True

Category: **QC_SE**#
Name	Description	Type
`QC_SE_Flag`	True when the metric crosses fail_threshold in the bad direction; eligible for curation.	Quality
`QC_SE_Metric`	Headline metric in the check’s own units; the bad direction is set by the check’s _HIGHER_IS_BAD flag. Drives Status.	Quality
`QC_SE_Status`	Categorical: pass \| warn \| fail.	Quality

Parameters:

on (Annotated[str, _ColumnRefMarker('measurements')])
groupby (Annotated[list[str], _ColumnRefMarker('measurements')])
agg_func (Callable | str | list | dict | None)
n_jobs (int)
warn_threshold (float)
fail_threshold (float)
unmatched_groups (list)
time_label (Annotated[str, _ColumnRefMarker('measurements')])
min_replicates (int)
eps (float)

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 __init_subclass__(**kwargs: Any) → None

Append QC and per-check RST tables to the subclass docstring.

Skips intermediate ABCs that have not yet bound name. When the subclass declares both a docstring and a name, the generic QUALITY_CHECK table is appended (substituting name into the column headers). If _measurement_infoclass is also set, its table is appended as well so check-specific columns are documented alongside the generic trio.

Parameters:: kwargs (Any)
Return type:: None

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, copying parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot.

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:

classmethod flag_col() → str

Return the flag column name for this check.

Return type:: str

classmethod from_orm(obj: Any) → Self

Parameters:: obj (Any)
Return type:: Self

classmethod metric_col() → str

Return the metric column name for this check.

Return type:: str

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:

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:

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

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:

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

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:

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:

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:

classmethod status_col() → str

Return the status column name for this check.

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

__init__(**data: Any) → None

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

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

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

Parameters:: data (Any)
Return type:: None

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

So dict(model) works.

Return type:: Generator[tuple[str, Any], None, None]

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

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

Parameters:

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

Return type:

__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

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

Run the check on every group and return the augmented frame.

Iterates over data.groupby(self.groupby, dropna=False), delegates per-group computation to _compute(), and adds three generic columns derived from the metric:

QC_<name>_Metric (carry-through from _compute)
QC_<name>_Flag (bool)
QC_<name>_Status ("pass" / "warn" / "fail")

Flag and Status are directional. With _HIGHER_IS_BAD=True a row fails when metric >= fail_threshold and warns when metric >= warn_threshold; with _HIGHER_IS_BAD=False the comparisons invert to <=. A NaN metric always yields Status="pass" and Flag=False.

Rows are never dropped. The augmented frame is stored on _latest_measurements and returned.

Parameters:: data (pandas.DataFrame) – Input measurement frame. Must contain self.on and every column in self.groupby.
Returns:: The input frame with the three generic QC columns appended plus whatever _compute contributed.
Raises:: KeyError – If self.on or any column in self.groupby is missing from data.
Return type:: pandas.DataFrame

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

dash(**kwargs: Any) → Figure[source]

Render mean ± SE bands per group across time.

For each self.groupby combination the plot draws the per-timepoint mean as a connected line with vertical error-bars sized to the per-bin SE. The line’s color is the worst status observed across that group’s timepoints: "pass" is green, "warn" is gold, "fail" is red.

Parameters:: **kwargs (Any) – Passed through to plotly.graph_objects.Figure / Figure.update_layout. Accepted keys are title and height.
Returns:: A plotly.graph_objects.Figure with one line + error bar trace per group.
Raises:: RuntimeError – If analyze() has not been called yet.
Return type:: Figure

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:

flagged_keys() → list[tuple[str, int]]

Return (Metadata_ImageName, Object_Label) pairs to curate.

Used by the GUI “Mark all flagged for removal” button. Requires the analyzed frame to carry both Metadata_ImageName and Object_Label columns (the curation key used by STORE_REMOVED_KEYS). Returns an empty list when those columns are absent or when no rows were flagged.

Returns:: De-duplicated list of (image_file, object_label) tuples for rows where Flag=True.
Return type:: list[tuple[str, int]]

group_members() → dict[tuple, list[tuple[str, int, Any]]]

Map each group key to its member rows for worklists/galleries.

Walks the most recent analyzed frame and, for every group key produced by data.groupby(self.groupby, dropna=False), collects the rows that belong to it as (Metadata_ImageName, Object_Label, member_value) tuples, where member_value is the row’s self.on value (the column the check operates on). The mapping preserves group iteration order.

Mirrors flagged_keys()’s guard: if the analyzed frame lacks either Metadata_ImageName or the object-label column, an empty mapping is returned rather than raising.

Returns:: Ordered mapping of group key (always a tuple, even for a single groupby column) to a list of (image_file, object_label, member_value) tuples. Empty when the curation key columns are absent.
Return type:: dict[tuple, list[tuple[str, int, 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)
encoder (Callable[[Any], Any] | None)
models_as_dict (bool)
dumps_kwargs (Any)

Return type:

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:

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

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

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

results() → pandas.DataFrame

Return the augmented frame stored by the most recent analyze().

Return type:: pandas.DataFrame

show(*args: Any, **kwargs: Any) → Any

QualityCheck plots are Plotly-only — see dash().

SetAnalyzer’s matplotlib show() is not implemented for QC because the QC tab is Plotly-driven. Raising rather than falling back to a placeholder so notebook users discover the right method.

Raises:

NotImplementedError – Always; use dash() instead.

Parameters:

args (Any)
kwargs (Any)

Return type:

summary() → pandas.DataFrame

Return a one-row-per-group summary of the most recent analyze.

The aggregate columns are prefixed with ``qc_`` so they can never collide with a groupby column on reset_index — a plate-layout column literally named status or num_rows would otherwise raise. The summary therefore always carries the group key columns plus the four prefixed aggregates.

Returns:: DataFrame with columns [*self.groupby, "qc_n_members", "qc_n_flagged", "qc_worst_metric", "qc_status"]. qc_worst_metric is the extreme metric value in the bad direction across the group: group[metric_col].max() when _HIGHER_IS_BAD is True, else group[metric_col].min(). qc_status is the worst status across the group: "fail" wins over "warn" which wins over "pass".
Return type:: pandas.DataFrame

table_spec(instance_id: str) → QcTableSpec

Return the catalog descriptor for this analyzed check.

Precondition: analyze() has run. Reads column roles from the class + instance config and derives extra_cols from the augmented frame.

Parameters:: instance_id (str) – The recipe entry id this check was built from.
Returns:: A populated QcTableSpec.
Return type:: QcTableSpec

to_table() → pandas.DataFrame

Return the module’s self-describing frame to persist to DuckDB.

Precondition: analyze() has run (this reads _latest_measurements). The default is member-level: the augmented frame projected to group-key + member-key + on + every QC_<name>_* column (metric/flag/status AND check-specific extras) + context columns (Metadata_Dataset and the column named by self.time_label) when those columns are present.

Diagnostic-only checks override to return a group-level frame.

Returns:: The projected DataFrame; columns vary per check (self-describing).
Return type:: pandas.DataFrame

agg_func: Callable | str | list | dict | None

eps: float

fail_threshold: float

groupby: ColumnRefList

member_key_cols: ClassVar[tuple[str, ...]] = ('MetadataImage_ImageName', 'Object_Label'): Per-object curation-key columns. Empty tuple when the check has no per-object key. Subclasses may narrow this.

min_replicates: int

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

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

model_fields = {'agg_func': FieldInfo(annotation=Union[Callable, str, list, dict, NoneType], required=False, default='mean'), 'eps': FieldInfo(annotation=float, required=False, default=1e-09, description='Floor on ``|mean|`` below which the relative-SE ratio is considered undefined. Bins below this floor receive ``metric = NaN``.'), 'fail_threshold': FieldInfo(annotation=float, required=False, default=0.2, description='Relative SE at which ``Status`` becomes ``"fail"`` and ``Flag=True``. Defaults to ``0.20``.'), 'groupby': FieldInfo(annotation=list[str], required=True, metadata=[_ColumnRefMarker('measurements')]), 'min_replicates': FieldInfo(annotation=int, required=False, default=2, description='Minimum replicate count required before SE is considered meaningful. Bins below this threshold receive ``metric = NaN``.'), 'n_jobs': FieldInfo(annotation=int, required=False, default=1, alias_priority=2, validation_alias=AliasChoices(choices=['n_jobs', 'num_workers'])), 'on': FieldInfo(annotation=str, required=True, metadata=[_ColumnRefMarker('measurements')]), 'time_label': FieldInfo(annotation=str, required=False, default='MetadataCulture_Time', description='Column name carrying the timepoint within each group. Defaults to ``"MetadataCulture_Time"``.', metadata=[_ColumnRefMarker('measurements')]), 'unmatched_groups': FieldInfo(annotation=list, required=False, default_factory=list, description='Groups that the check could not evaluate (for example, expected counts whose group key never appeared in the data). Populated by subclasses that need to report missing combinations; empty by default.'), 'warn_threshold': FieldInfo(annotation=float, required=False, default=0.1, description='Relative SE at which ``Status`` becomes ``"warn"``. Defaults to ``0.10``.')}

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.

n_jobs: int

name: ClassVar[str] = 'SE'

on: ColumnRef

supports_object_curation: ClassVar[bool] = True: Whether this check’s rows map to curatable detected objects. False for diagnostic-only checks (e.g. GridOccupancy) — the Review tab hides the curation radial + tile gallery and verified-good skips them.

time_label: ColumnRef

unmatched_groups: list

warn_threshold: float

class phenotypic.analysis.TukeyOutlierFraction(*, on: ~typing.Annotated[str, _ColumnRefMarker('measurements')], groupby: ~typing.Annotated[list[str], _ColumnRefMarker('measurements')], agg_func: ~typing.Callable | str | list | dict | None = 'mean', n_jobs: int = 1, warn_threshold: float = 0.1, fail_threshold: float = 0.25, unmatched_groups: list = <factory>, time_label: ~typing.Annotated[str, _ColumnRefMarker('measurements')] = 'MetadataCulture_Time', k: float = 1.5, min_replicates: int = 4)[source]

Bases: QualityCheck

Flag (group, time) bins with a high fraction of Tukey outliers.

For each combination of self.groupby columns, this check splits the group by self.time_label and computes Tukey’s fences Q1 - k*IQR / Q3 + k*IQR at every timepoint. The per-bin metric is the fraction of members that fall strictly outside the fences; bins whose metric exceeds the warn/fail thresholds are surfaced for curation. The per-bin scalars are broadcast back to every replicate row in the bin so the GUI can pick up the flag from any row.

_HIGHER_IS_BAD is True: a larger outlier fraction means a noisier group, so the base class flags rows whose metric meets or exceeds fail_threshold.

One guard path short-circuits to metric = NaN so under-powered bins never gate curation (the base class treats NaN metric as Status="pass"):

``n < min_replicates`` — quartiles and the IQR are not meaningful for tiny bins, and a single member would otherwise read as a 0% or 100% outlier fraction. Defaults to min_replicates=4 (the smallest bin where Tukey’s quartile rule is informative); raising it lets callers demand more statistical power.

When self.time_label is absent from the input data, the entire group is treated as a single timepoint bin so the check remains usable on snapshot (non-time-course) measurement frames.

The check does not aggregate measurement values — it builds the fence/outlier summary statistics inside _compute() — so _exposes_agg_func is False and the GUI parameter-form rendering driver hides the agg_func field. The base SetAnalyzer.agg_func is preserved on the signature for parity only.
Attributes:

time_label: Column name carrying the timepoint within each
group. Defaults to "MetadataCulture_Time".

k: IQR multiplier for the fences. 1.5 flags standard outliers;
3.0 flags only extreme outliers. Defaults to 1.5.

min_replicates: Minimum member count required before the outlier
fraction is considered meaningful. Bins below this threshold receive metric = NaN. Defaults to 4.

warn_threshold: Outlier fraction at which Status becomes
"warn". Defaults to 0.10.

fail_threshold: Outlier fraction at which Status becomes
"fail" and Flag=True. Defaults to 0.25.

Examples:
Basic — ten members per timepoint with one extreme outlier; the check adds QC_Tukey_Metric plus the per-bin summary columns:
>>> import pandas as pd
>>> from phenotypic.analysis.qc import (
...     TukeyOutlierFraction,
... )
>>> data = pd.DataFrame({
...     "Plate": ["P1"] * 10,
...     "MetadataCulture_Time": [0] * 10,
...     "Size_Area": [
...         10.0, 11.0, 12.0, 13.0, 14.0,
...         10.5, 11.5, 12.5, 13.5, 200.0,
...     ],
... })
>>> chk = TukeyOutlierFraction(
...     on="Size_Area",
...     groupby=["Plate"],
...     time_label="MetadataCulture_Time",
... )
>>> result = chk.analyze(data)
>>> "QC_Tukey_Metric" in result.columns
True
Advanced — only three members per (group, time) bin with the default min_replicates=4 triggers the under-powered guard:
>>> sparse = pd.DataFrame({
...     "Plate": ["P1", "P1", "P1"],
...     "MetadataCulture_Time": [0, 0, 0],
...     "Size_Area": [10.0, 11.0, 12.0],
... })
>>> chk = TukeyOutlierFraction(on="Size_Area", groupby=["Plate"])
>>> result = chk.analyze(sparse)
>>> bool(result["QC_Tukey_Metric"].isna().all())
True

Category: **QC_Tukey**#
Name	Description	Type
`QC_Tukey_Flag`	True when the metric crosses fail_threshold in the bad direction; eligible for curation.	Quality
`QC_Tukey_Metric`	Headline metric in the check’s own units; the bad direction is set by the check’s _HIGHER_IS_BAD flag. Drives Status.	Quality
`QC_Tukey_Status`	Categorical: pass \| warn \| fail.	Quality

Parameters:

on (Annotated[str, _ColumnRefMarker('measurements')])
groupby (Annotated[list[str], _ColumnRefMarker('measurements')])
agg_func (Callable | str | list | dict | None)
n_jobs (int)
warn_threshold (float)
fail_threshold (float)
unmatched_groups (list)
time_label (Annotated[str, _ColumnRefMarker('measurements')])
k (float)
min_replicates (int)

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 __init_subclass__(**kwargs: Any) → None

Append QC and per-check RST tables to the subclass docstring.

Skips intermediate ABCs that have not yet bound name. When the subclass declares both a docstring and a name, the generic QUALITY_CHECK table is appended (substituting name into the column headers). If _measurement_infoclass is also set, its table is appended as well so check-specific columns are documented alongside the generic trio.

Parameters:: kwargs (Any)
Return type:: None

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, copying parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot.

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:

classmethod flag_col() → str

Return the flag column name for this check.

Return type:: str

classmethod from_orm(obj: Any) → Self

Parameters:: obj (Any)
Return type:: Self

classmethod metric_col() → str

Return the metric column name for this check.

Return type:: str

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:

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:

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

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:

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

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:

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:

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:

classmethod status_col() → str

Return the status column name for this check.

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

__init__(**data: Any) → None

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

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

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

Parameters:: data (Any)
Return type:: None

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

So dict(model) works.

Return type:: Generator[tuple[str, Any], None, None]

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

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

Parameters:

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

Return type:

__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

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

Run the check on every group and return the augmented frame.

Iterates over data.groupby(self.groupby, dropna=False), delegates per-group computation to _compute(), and adds three generic columns derived from the metric:

QC_<name>_Metric (carry-through from _compute)
QC_<name>_Flag (bool)
QC_<name>_Status ("pass" / "warn" / "fail")

Flag and Status are directional. With _HIGHER_IS_BAD=True a row fails when metric >= fail_threshold and warns when metric >= warn_threshold; with _HIGHER_IS_BAD=False the comparisons invert to <=. A NaN metric always yields Status="pass" and Flag=False.

Rows are never dropped. The augmented frame is stored on _latest_measurements and returned.

Parameters:: data (pandas.DataFrame) – Input measurement frame. Must contain self.on and every column in self.groupby.
Returns:: The input frame with the three generic QC columns appended plus whatever _compute contributed.
Raises:: KeyError – If self.on or any column in self.groupby is missing from data.
Return type:: pandas.DataFrame

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

dash(**kwargs)

Interactive Plotly visualization of analysis results.

Subclasses may override this method to provide an interactive Plotly figure equivalent to show().

Raises:: NotImplementedError – Unless overridden by a subclass.

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:

flagged_keys() → list[tuple[str, int]]

Return (Metadata_ImageName, Object_Label) pairs to curate.

Used by the GUI “Mark all flagged for removal” button. Requires the analyzed frame to carry both Metadata_ImageName and Object_Label columns (the curation key used by STORE_REMOVED_KEYS). Returns an empty list when those columns are absent or when no rows were flagged.

Returns:: De-duplicated list of (image_file, object_label) tuples for rows where Flag=True.
Return type:: list[tuple[str, int]]

group_members() → dict[tuple, list[tuple[str, int, Any]]]

Map each group key to its member rows for worklists/galleries.

Walks the most recent analyzed frame and, for every group key produced by data.groupby(self.groupby, dropna=False), collects the rows that belong to it as (Metadata_ImageName, Object_Label, member_value) tuples, where member_value is the row’s self.on value (the column the check operates on). The mapping preserves group iteration order.

Mirrors flagged_keys()’s guard: if the analyzed frame lacks either Metadata_ImageName or the object-label column, an empty mapping is returned rather than raising.

Returns:: Ordered mapping of group key (always a tuple, even for a single groupby column) to a list of (image_file, object_label, member_value) tuples. Empty when the curation key columns are absent.
Return type:: dict[tuple, list[tuple[str, int, 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)
encoder (Callable[[Any], Any] | None)
models_as_dict (bool)
dumps_kwargs (Any)

Return type:

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:

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

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

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

results() → pandas.DataFrame

Return the augmented frame stored by the most recent analyze().

Return type:: pandas.DataFrame

show(*args: Any, **kwargs: Any) → Any

QualityCheck plots are Plotly-only — see dash().

SetAnalyzer’s matplotlib show() is not implemented for QC because the QC tab is Plotly-driven. Raising rather than falling back to a placeholder so notebook users discover the right method.

Raises:

NotImplementedError – Always; use dash() instead.

Parameters:

args (Any)
kwargs (Any)

Return type:

summary() → pandas.DataFrame

Return a one-row-per-group summary of the most recent analyze.

The aggregate columns are prefixed with ``qc_`` so they can never collide with a groupby column on reset_index — a plate-layout column literally named status or num_rows would otherwise raise. The summary therefore always carries the group key columns plus the four prefixed aggregates.

Returns:: DataFrame with columns [*self.groupby, "qc_n_members", "qc_n_flagged", "qc_worst_metric", "qc_status"]. qc_worst_metric is the extreme metric value in the bad direction across the group: group[metric_col].max() when _HIGHER_IS_BAD is True, else group[metric_col].min(). qc_status is the worst status across the group: "fail" wins over "warn" which wins over "pass".
Return type:: pandas.DataFrame

table_spec(instance_id: str) → QcTableSpec

Return the catalog descriptor for this analyzed check.

Precondition: analyze() has run. Reads column roles from the class + instance config and derives extra_cols from the augmented frame.

Parameters:: instance_id (str) – The recipe entry id this check was built from.
Returns:: A populated QcTableSpec.
Return type:: QcTableSpec

to_table() → pandas.DataFrame

Return the module’s self-describing frame to persist to DuckDB.

Precondition: analyze() has run (this reads _latest_measurements). The default is member-level: the augmented frame projected to group-key + member-key + on + every QC_<name>_* column (metric/flag/status AND check-specific extras) + context columns (Metadata_Dataset and the column named by self.time_label) when those columns are present.

Diagnostic-only checks override to return a group-level frame.

Returns:: The projected DataFrame; columns vary per check (self-describing).
Return type:: pandas.DataFrame

agg_func: Callable | str | list | dict | None

fail_threshold: float

groupby: ColumnRefList

k: float

member_key_cols: ClassVar[tuple[str, ...]] = ('MetadataImage_ImageName', 'Object_Label'): Per-object curation-key columns. Empty tuple when the check has no per-object key. Subclasses may narrow this.

min_replicates: int

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

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

model_fields = {'agg_func': FieldInfo(annotation=Union[Callable, str, list, dict, NoneType], required=False, default='mean'), 'fail_threshold': FieldInfo(annotation=float, required=False, default=0.25, description='Outlier fraction at which ``Status`` becomes ``"fail"`` and ``Flag=True``. Defaults to ``0.25``.'), 'groupby': FieldInfo(annotation=list[str], required=True, metadata=[_ColumnRefMarker('measurements')]), 'k': FieldInfo(annotation=float, required=False, default=1.5, description='IQR multiplier for the fences. ``1.5`` flags standard outliers; ``3.0`` flags only extreme outliers. Defaults to ``1.5``.'), 'min_replicates': FieldInfo(annotation=int, required=False, default=4, description='Minimum member count required before the outlier fraction is considered meaningful. Bins below this threshold receive ``metric = NaN``. Defaults to ``4``.'), 'n_jobs': FieldInfo(annotation=int, required=False, default=1, alias_priority=2, validation_alias=AliasChoices(choices=['n_jobs', 'num_workers'])), 'on': FieldInfo(annotation=str, required=True, metadata=[_ColumnRefMarker('measurements')]), 'time_label': FieldInfo(annotation=str, required=False, default='MetadataCulture_Time', description='Column name carrying the timepoint within each group. Defaults to ``"MetadataCulture_Time"``.', metadata=[_ColumnRefMarker('measurements')]), 'unmatched_groups': FieldInfo(annotation=list, required=False, default_factory=list, description='Groups that the check could not evaluate (for example, expected counts whose group key never appeared in the data). Populated by subclasses that need to report missing combinations; empty by default.'), 'warn_threshold': FieldInfo(annotation=float, required=False, default=0.1, description='Outlier fraction at which ``Status`` becomes ``"warn"``. Defaults to ``0.10``.')}

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.

n_jobs: int

name: ClassVar[str] = 'Tukey'

on: ColumnRef

supports_object_curation: ClassVar[bool] = True: Whether this check’s rows map to curatable detected objects. False for diagnostic-only checks (e.g. GridOccupancy) — the Review tab hides the curation radial + tile gallery and verified-good skips them.

time_label: ColumnRef

unmatched_groups: list

warn_threshold: float

class phenotypic.analysis.TukeyOutlierRemover(*, on: Annotated[str, _ColumnRefMarker('measurements')], groupby: Annotated[list[str], _ColumnRefMarker('measurements')], agg_func: Callable | str | list | dict | None = None, n_jobs: int = 1, k: float = 1.5)[source]

Bases: SetAnalyzer

Analyzer for removing outliers using Tukey’s fence method.

This class removes outliers from measurement data by applying Tukey’s fence test within groups. The method calculates the interquartile range (IQR) and removes values that fall outside Q1 - k*IQR or Q3 + k*IQR, where k is a tunable multiplier (typically 1.5 for outliers or 3.0 for extreme outliers).

Parameters:

on (Annotated[str, _ColumnRefMarker('measurements')]) – Name of measurement column to test for outliers (e.g., ‘Shape_Area’, ‘Intensity_IntegratedIntensity’).
groupby (Annotated[list[str], _ColumnRefMarker('measurements')]) – List of column names to group by (e.g., [‘StrainID’, ‘Time’]).
k (float) – IQR multiplier for fence calculation. Default is 1.5 (standard outliers). Use 3.0 for extreme outliers only.
n_jobs (int) – Number of parallel workers. Default is 1.
agg_func (Callable | str | list | dict | None)

groupby

List of column names to group by.

Type:: list[str]

on

Column to test for outliers.

Type:: str

k

IQR multiplier used for fence calculation.

Type:: float

n_jobs

Number of parallel workers. Default is 1.

Type:: int

Examples

Remove outliers and visualize results:

>>> import pandas as pd
>>> import numpy as np
>>> from phenotypic.analysis import TukeyOutlierRemover
>>> # Create sample data with some outliers
>>> np.random.seed(42)
>>> data = pd.DataFrame({
...     'ImageName': ['img1'] * 50 + ['img2'] * 50,
...     'Area': np.concatenate([
...         np.random.normal(200, 30, 48),
...         [500, 550],  # outliers in img1
...         np.random.normal(180, 25, 48),
...         [50, 600]  # outliers in img2
...     ])
... })
>>> # Initialize detector
>>> detector = TukeyOutlierRemover(
...     on='Area',
...     groupby=['ImageName'],
...     k=1.5
... )
>>> # Remove outliers
>>> filtered_data = detector.analyze(data)
>>> # Check how many were removed
>>> print(f"Original: {len(data)}, Filtered: {len(filtered_data)}")
>>> # Visualize removed outliers
>>> fig = detector.show()

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, copying parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot.

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:

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:

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:

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

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:

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

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:

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:

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:

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

__init__(**data: Any) → None

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

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

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

Parameters:: data (Any)
Return type:: None

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

So dict(model) works.

Return type:: Generator[tuple[str, Any], None, None]

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

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

Parameters:

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

Return type:

__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

analyze(data: pandas.DataFrame) → pandas.DataFrame[source]

Remove outliers from data using Tukey’s fence method.

This method processes the input DataFrame by grouping according to specified columns and removing outliers within each group independently. Outliers are identified using the IQR method and filtered out. The original data is stored internally for visualization purposes.

Parameters:

data (pandas.DataFrame) – DataFrame containing measurement data. Must include all columns specified in self.groupby and self.on.

Returns:

DataFrame with outliers removed. Contains only the original columns (no additional outlier flag columns).

Raises:

KeyError – If required columns are missing from input DataFrame.
ValueError – If data is empty or malformed.

Return type:

pandas.DataFrame

Examples

Analyze and filter outliers from measurement data:

>>> import pandas as pd
>>> import numpy as np
>>> from phenotypic.analysis import TukeyOutlierRemover
>>> # Create sample data
>>> np.random.seed(42)
>>> data = pd.DataFrame({
...     'ImageName': ['img1'] * 100,
...     'Area': np.concatenate([
...         np.random.normal(200, 30, 98),
...         [500, 50]  # outliers
...     ])
... })
>>> # Remove outliers
>>> detector = TukeyOutlierRemover(
...     on='Area',
...     groupby=['ImageName'],
...     k=1.5
... )
>>> filtered_data = detector.analyze(data)
>>> # Check results
>>> print(f"Original: {len(data)} rows, Filtered: {len(filtered_data)} rows")
>>> print(f"Removed {len(data) - len(filtered_data)} outliers")

Notes

Stores original data in self._original_data for visualization
Stores filtered results in self._latest_measurements for retrieval
Groups are processed independently with their own fences
NaN values in measurement column are preserved in output

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

dash(**kwargs)

Interactive Plotly visualization of analysis results.

Subclasses may override this method to provide an interactive Plotly figure equivalent to show().

Raises:: NotImplementedError – Unless overridden by a subclass.

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:

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:

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:

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

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

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

results() → pandas.DataFrame[source]

Return the filtered results (outliers removed).

Returns the DataFrame with outliers removed from the most recent call to analyze().

Returns:: DataFrame with outliers filtered out. Contains only the original columns without additional outlier flag columns. If analyze() has not been called, returns an empty DataFrame.
Return type:: pandas.DataFrame

Examples

Retrieve filtered results after analysis:

>>> detector = TukeyOutlierRemover(
...     on='Area',
...     groupby=['ImageName']
... )
>>> filtered_data = detector.analyze(data)
>>> results_copy = detector.results()  # Same as filtered_data
>>> assert results_copy.equals(filtered_data)
>>> # Check how many rows were removed
>>> num_removed = len(data) - len(filtered_data)
>>> print(f"Removed {num_removed} outliers")

Notes

Returns the DataFrame stored in self._latest_measurements
Contains only inliers (outliers have been removed)
Use this method to retrieve results after calling analyze()

show(figsize: tuple[int, int] | None = None, max_groups: int = 20, collapsed: bool = True, criteria: dict[str, Any] | None = None, **kwargs) → tuple[TypeAliasForwardRef('matplotlib.figure.Figure'), TypeAliasForwardRef('matplotlib.axes.Axes')][source]

Visualize outlier detection results.

Creates a visualization showing the distribution of values with outliers highlighted and fence boundaries displayed. Can display as individual subplots or as a collapsed stacked view with all groups in a single plot. Outlier flags are computed dynamically for visualization only.

Parameters:

figsize (tuple[int, int] | None) – Figure size as (width, height). If None, automatically determined based on number of groups and mode.
max_groups (int) – Maximum number of groups to display. If there are more groups, only the first max_groups will be shown. Default is 20.
collapsed (bool) – If True, show all groups stacked vertically in a single plot. If False, show each group in its own subplot. Default is False.
criteria (dict[str, Any] | None) – Optional dictionary specifying filtering criteria for data selection. When provided, only groups matching the criteria will be displayed. Format: {‘column_name’: value} or {‘column_name’: [value1, value2]}. Default is None (show all groups).
**kwargs – Additional matplotlib parameters to customize the plot. Common options include: - dpi: Figure resolution (default 100) - facecolor: Figure background color - edgecolor: Figure edge color - grid_alpha: Alpha value for grid lines (default 0.3) - grid_axis: Which axis to apply grid to (‘both’, ‘x’, ‘y’) - legend_loc: Legend location (default ‘best’) - legend_fontsize: Font size for legend (default 8) - marker_alpha: Alpha value for scatter plot markers - line_width: Line width for box plots and fence lines

Returns:

Tuple of (Figure, Axes) containing the visualization.

Raises:

ValueError – If analyze() has not been called yet (no results to display).
KeyError – If criteria references columns not present in the data.

Return type:

tuple[TypeAliasForwardRef(‘matplotlib.figure.Figure’), TypeAliasForwardRef(‘matplotlib.axes.Axes’)]

Examples

Visualize outlier detection with multiple grouping options:

>>> import pandas as pd
>>> import numpy as np
>>> from phenotypic.analysis import TukeyOutlierRemover
>>> # Create sample data with multiple grouping columns
>>> np.random.seed(42)
>>> data = pd.DataFrame({
...     'ImageName': ['img1', 'img2'] * 50,
...     'Plate': ['P1'] * 50 + ['P2'] * 50,
...     'Area': np.concatenate([
...         np.random.normal(200, 30, 48), [500, 550],
...         np.random.normal(180, 25, 48), [50, 600]
...     ])
... })
>>> # Remove outliers and visualize all groups
>>> detector = TukeyOutlierRemover(
...     on='Area',
...     groupby=['Plate', 'ImageName'],
...     k=1.5
... )
>>> results = detector.analyze(data)
>>> fig, axes = detector.show(figsize=(12, 5))
>>> # Visualize only specific plate
>>> fig, axes = detector.show(criteria={'Plate': 'P1'})
>>> # Visualize specific images across plates using collapsed view
>>> fig, ax = detector.show(criteria={'ImageName': 'img1'}, collapsed=True)

Notes

Individual mode (collapsed=False): - Each group gets its own subplot with box plot - Outliers shown in red, normal values in blue - Horizontal lines show fence boundaries

Collapsed mode (collapsed=True): - All groups stacked vertically in single plot - Each group shown as horizontal line with median marker - Vertical bars show fence boundaries - Normal points as circles, outliers as diamonds - More compact for comparing many groups

Filtering with criteria: - Only groups matching all criteria are displayed - Useful for focusing on specific plates, conditions, or subsets - Can be combined with both individual and collapsed modes

agg_func: Callable | str | list | dict | None

groupby: ColumnRefList

k: float

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

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

model_fields = {'agg_func': FieldInfo(annotation=Union[Callable, str, list, dict, NoneType], required=False, default=None), 'groupby': FieldInfo(annotation=list[str], required=True, description='List of column names to group by.', metadata=[_ColumnRefMarker('measurements')]), 'k': FieldInfo(annotation=float, required=False, default=1.5, description='IQR multiplier used for fence calculation.'), 'n_jobs': FieldInfo(annotation=int, required=False, default=1, alias_priority=2, validation_alias=AliasChoices(choices=['n_jobs', 'num_workers']), description='Number of parallel workers. Default is 1.'), 'on': FieldInfo(annotation=str, required=True, description='Column to test for outliers.', metadata=[_ColumnRefMarker('measurements')])}

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.

n_jobs: int

on: ColumnRef

phenotypic.analysis.filter_spec_json(measurement: str, direction: str, cutoff: float) → str[source]

Return the machine-readable filter spec as indented JSON.

Parameters:

measurement (str) – The measurement column the cutoff applies to.
direction (str) – The comparison operator (">" or "<").
cutoff (float) – The decision threshold.

Returns:

{"measurement": "...", "op": ">", "cutoff": 123.4} as a 2-space-indented JSON string.

Return type:

phenotypic.analysis.filter_spec_query(measurement: str, direction: str, cutoff: float) → str[source]

Return the human-readable filter expression.

Parameters:

measurement (str) – The measurement column the cutoff applies to.
direction (str) – The comparison operator (">" or "<").
cutoff (float) – The decision threshold.

Returns:

A Size_Area > 123.40 style expression (cutoff to 2 d.p.).

Return type: