phenotypic.analysis.qc package<a class="headerlink" href="#module-phenotypic.analysis.qc" title="Link to this heading">#

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_ImageFile, Object_Label) pairs to curate.

Used by the GUI “Mark all flagged for removal” button. Requires the analyzed frame to carry both Metadata_ImageFile 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_ImageFile, 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_ImageFile 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]#

Validate metadata columns and pre-compute expected counts.

Runs after pydantic has validated every field. Mirrors the resolved metadata frame onto 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:

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

agg_func: Callable | str | list | dict | None#

fail_threshold: float#

groupby: ColumnRefList#

metadata: _MetadataFrame#

metadata_source: str | None#

model_computed_fields = {}#

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

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

Get extra fields set during validation.

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

model_fields = {'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=DataFrame, required=True, description='Layout frame whose row count per ``groupby`` key is the expected colony count. Either a DataFrame or a path to a CSV or Parquet file. Excluded from serialization — supply ``metadata_source`` instead when rebuilding from JSON.', exclude=True, metadata=[WithJsonSchema(json_schema={'type': 'object'}, mode=None)]), 'metadata_source': FieldInfo(annotation=Union[str, NoneType], required=False, default=None, description='Path to the layout CSV/Parquet, captured automatically when ``metadata`` is given as a path. This is the JSON-serializable handle to the layout: on reconstruction from ``pipeline.json`` the frame is re-read from here. Usually set implicitly; pass it explicitly only when reconstructing without a ``metadata`` frame.'), '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#

unmatched_groups: list#

warn_threshold: float#

class phenotypic.analysis.qc.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')] = 'Metadata_Time', rater_label: ~typing.Annotated[str, _ColumnRefMarker('measurements')] = 'Metadata_Replicate')[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 "Metadata_Time") and one column per rater_label value (the replicates that should agree, by default "Metadata_Replicate") — and computes the ICC(2,1) two-way random, absolute-agreement coefficient over it. With Metadata_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 "Metadata_Time" so each timepoint is a subject and the ICC flags replicates that disagree relative to the growth trend. Override (e.g. "Metadata_StrainID") 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 "Metadata_Replicate".

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,
...     "Metadata_Time": [0, 0, 0, 1, 1, 1, 2, 2, 2],
...     "Metadata_Replicate": [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,
...     "Metadata_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
`QC_ICC_Flag`	True when the metric crosses fail_threshold in the bad direction; eligible for curation.
`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.
`QC_ICC_Status`	Categorical: pass \| warn \| fail.

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_ImageFile, Object_Label) pairs to curate.

Used by the GUI “Mark all flagged for removal” button. Requires the analyzed frame to carry both Metadata_ImageFile 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_ImageFile, 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_ImageFile 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

agg_func: Callable | str | list | dict | None#

fail_threshold: float#

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'), '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='Metadata_Replicate', description='Column whose distinct values index the *rater* (column) axis of the two-way model — the replicates that should agree. Defaults to ``"Metadata_Replicate"``.', metadata=[_ColumnRefMarker('measurements')]), 'subject_label': FieldInfo(annotation=str, required=False, default='Metadata_Time', description='Column whose distinct values index the *subject* (row) axis of the two-way model — the repeated-measure axis. Defaults to ``"Metadata_Time"`` so each timepoint is a subject and the ICC flags replicates that disagree relative to the growth trend. Override (e.g. ``"Metadata_StrainID"``) 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#

unmatched_groups: list#

warn_threshold: float#

class phenotypic.analysis.qc.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')] = 'Metadata_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 "Metadata_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,
...     "Metadata_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="Metadata_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"],
...     "Metadata_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
`QC_ZMax_Flag`	True when the metric crosses fail_threshold in the bad direction; eligible for curation.
`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.
`QC_ZMax_Status`	Categorical: pass \| warn \| fail.

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_ImageFile, Object_Label) pairs to curate.

Used by the GUI “Mark all flagged for removal” button. Requires the analyzed frame to carry both Metadata_ImageFile 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_ImageFile, 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_ImageFile 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

agg_func: Callable | str | list | dict | None#

fail_threshold: float#

groupby: ColumnRefList#

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='Metadata_Time', description='Column name carrying the timepoint within each group. Defaults to ``"Metadata_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#

time_label: ColumnRef#

unmatched_groups: list#

warn_threshold: float#

class phenotypic.analysis.qc.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')] = 'Metadata_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 "Metadata_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,
...     "Metadata_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="Metadata_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"],
...     "Metadata_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
`QC_MAD_Flag`	True when the metric crosses fail_threshold in the bad direction; eligible for curation.
`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.
`QC_MAD_Status`	Categorical: pass \| warn \| fail.

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_ImageFile, Object_Label) pairs to curate.

Used by the GUI “Mark all flagged for removal” button. Requires the analyzed frame to carry both Metadata_ImageFile 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_ImageFile, 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_ImageFile 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

agg_func: Callable | str | list | dict | None#

eps: float#

fail_threshold: float#

groupby: ColumnRefList#

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='Metadata_Time', description='Column name carrying the timepoint within each group. Defaults to ``"Metadata_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#

time_label: ColumnRef#

unmatched_groups: list#

warn_threshold: float#

class phenotypic.analysis.qc.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')] = 'Metadata_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 "Metadata_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,
...     "Metadata_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="Metadata_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"],
...     "Metadata_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
`QC_SE_Flag`	True when the metric crosses fail_threshold in the bad direction; eligible for curation.
`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.
`QC_SE_Status`	Categorical: pass \| warn \| fail.

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_ImageFile, Object_Label) pairs to curate.

Used by the GUI “Mark all flagged for removal” button. Requires the analyzed frame to carry both Metadata_ImageFile 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_ImageFile, 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_ImageFile 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

agg_func: Callable | str | list | dict | None#

eps: float#

fail_threshold: float#

groupby: ColumnRefList#

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='Metadata_Time', description='Column name carrying the timepoint within each group. Defaults to ``"Metadata_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#

time_label: ColumnRef#

unmatched_groups: list#

warn_threshold: float#

class phenotypic.analysis.qc.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')] = 'Metadata_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 "Metadata_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,
...     "Metadata_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="Metadata_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"],
...     "Metadata_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
`QC_Tukey_Flag`	True when the metric crosses fail_threshold in the bad direction; eligible for curation.
`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.
`QC_Tukey_Status`	Categorical: pass \| warn \| fail.

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_ImageFile, Object_Label) pairs to curate.

Used by the GUI “Mark all flagged for removal” button. Requires the analyzed frame to carry both Metadata_ImageFile 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_ImageFile, 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_ImageFile 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: