phenotypic.analysis.GridOccupancy#

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

Bases: ExpectedVsDetectedCount

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

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

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

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

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

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

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

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

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

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

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

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

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

Raises:

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

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

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

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

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

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

Methods

`__init__`	Create a new model by parsing and validating input data from keyword arguments.
`analyze`	Guard the cell-id column, then run the inherited `analyze`.
`construct`
`copy`	Returns a copy of the model.
`dash`	Render a horizontal bar of per-group occupancy, colored by status.
`dict`
`flag_col`	Return the flag column name for this check.
`flagged_keys`	Return (`Metadata_ImageName`, `Object_Label`) pairs to curate.
`from_orm`
`group_members`	Map each group key to its member rows for worklists/galleries.
`json`
`metric_col`	Return the metric column name for this check.
`model_construct`	Creates a new instance of the Model class with validated data.
`model_copy`	!!! abstract "Usage Documentation"
`model_dump`	!!! abstract "Usage Documentation"
`model_dump_json`	!!! abstract "Usage Documentation"
`model_json_schema`	Generates a JSON schema for a model class.
`model_parametrized_name`	Compute the class name for parametrizations of generic classes.
`model_post_init`	Resolve the layout frame, validate columns, pre-compute counts.
`model_rebuild`	Try to rebuild the pydantic-core schema for the model.
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	!!! abstract "Usage Documentation"
`model_validate_strings`	Validate the given object with string data against the Pydantic model.
`parse_file`
`parse_obj`
`parse_raw`
`results`	Return the augmented frame stored by the most recent analyze().
`schema`
`schema_json`
`show`	QualityCheck plots are Plotly-only — see `dash()`.
`status_col`	Return the status column name for this check.
`summary`	Return a one-row-per-group summary of the most recent analyze.
`table_spec`	Return the catalog descriptor for this analyzed check.
`to_table`	Return one group-level row per group (occupancy is per-plate).
`update_forward_refs`
`validate`

Attributes

`member_key_cols`	Per-object curation-key columns.
`model_computed_fields`
`model_config`	Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
`model_extra`	Get extra fields set during validation.
`model_fields`
`model_fields_set`	Returns the set of fields that have been explicitly set on this model instance.
`name`
`supports_object_curation`	Whether this check's rows map to curatable detected objects.
`warn_threshold`
`fail_threshold`
`cell_label`
`on`
`agg_func`
`metadata`
`unmatched_groups`
`groupby`
`n_jobs`

Parameters:

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

name: ClassVar[str] = 'Occupancy'#

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

warn_threshold: float#

fail_threshold: float#

cell_label: ColumnRef#

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

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

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

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

to_table() → pandas.DataFrame[source]#

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

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

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

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

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

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

__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

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

Hook into generating the model’s JSON schema.

Parameters:

core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.
handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

__init__(**data: Any) → None#

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

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

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

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

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

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

So dict(model) works.

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

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

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

Parameters:

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

Return type:

Generator[Any]

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

__repr_name__() → str#

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

Return type:: str

__repr_recursion__(object: Any) → str#

Returns the string representation of a recursive object.

Parameters:: object (Any)
Return type:: str

__rich_repr__() → RichReprResult#

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

Return type:: RichReprResult

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

Parameters:

_fields_set (set[str] | None)
values (Any)

Return type:

Self

Returns a copy of the model.

!!! warning “Deprecated”: This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

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

Parameters:

include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.
exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.
update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.
deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

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

Return type:

Self

Parameters:

include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)
exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)
by_alias (bool)
exclude_unset (bool)
exclude_defaults (bool)
exclude_none (bool)

Return type:

Dict[str, Any]

classmethod flag_col() → str#

Return the flag column name for this check.

Return type:: str

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

Return (Metadata_ImageName, Object_Label) pairs to curate.

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

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

classmethod from_orm(obj: Any) → Self#

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

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

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

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

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

Returns:: Ordered mapping of group key (always a tuple, even for a single groupby column) to a list of (image_file, object_label, member_value) tuples. Empty when the curation key columns are absent.
Return type:: dict[tuple, list[tuple[str, int, Any]]]

Parameters:

include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)
exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)
by_alias (bool)
exclude_unset (bool)
exclude_defaults (bool)
exclude_none (bool)
encoder (Callable[[Any], Any] | None)
models_as_dict (bool)
dumps_kwargs (Any)

Return type:

str

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

classmethod metric_col() → str#

Return the metric column name for this check.

Return type:: str

model_computed_fields = {}#

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

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

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

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

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

Parameters:

_fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.
values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

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

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

Returns a copy of the model.

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

Parameters:

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

Returns:

New model instance.

Return type:

Self

!!! abstract “Usage Documentation”: [model_dump](../concepts/serialization.md#python-mode)

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

Parameters:

mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.
include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.
exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.
context (Any | None) – Additional context to pass to the serializer.
by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.
exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.
exclude_defaults (bool) – Whether to exclude fields that are set to their default value.
exclude_none (bool) – Whether to exclude fields that have a value of None.
exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.
round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].
warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].
fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.
serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

!!! abstract “Usage Documentation”: [model_dump_json](../concepts/serialization.md#json-mode)

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

Parameters:

indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.
ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.
include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.
exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.
context (Any | None) – Additional context to pass to the serializer.
by_alias (bool | None) – Whether to serialize using field aliases.
exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.
exclude_defaults (bool) – Whether to exclude fields that are set to their default value.
exclude_none (bool) – Whether to exclude fields that have a value of None.
exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.
round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].
warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].
fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.
serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

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

Get extra fields set during validation.

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

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

property model_fields_set: set[str]#

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

Returns:

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

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

Generates a JSON schema for a model class.

Parameters:

by_alias (bool) – Whether to use attribute aliases or not.
ref_template (str) – The reference template.
union_format (Literal['any_of', 'primitive_type_array']) –
The format to use when combining schemas from unions together. Can be one of:
- ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)
keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.
schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications
mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

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

Compute the class name for parametrizations of generic classes.

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

Parameters:: params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.
Returns:: String representing the new class where params are passed to cls as type variables.
Raises:: TypeError – Raised when trying to generate concrete names for non-generic models.
Return type:: str

model_post_init(_ExpectedVsDetectedCount__context: Any) → None#

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

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

Parameters:

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

Raises:

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

Return type:

None

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:

Self

!!! abstract “Usage Documentation”: [JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

json_data (str | bytes | bytearray) – The JSON data to validate.
strict (bool | None) – Whether to enforce types strictly.
extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.
context (Any | None) – Extra variables to pass to the validator.
by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.
by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

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

Return type:

Self

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

Parameters:

obj (Any) – The object containing string data to validate.
strict (bool | None) – Whether to enforce types strictly.
extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.
context (Any | None) – Extra variables to pass to the validator.
by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.
by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

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

Parameters:

path (str | Path)
content_type (str | None)
encoding (str)
proto (DeprecatedParseProtocol | None)
allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self#

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

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

Parameters:

b (str | bytes)
content_type (str | None)
encoding (str)
proto (DeprecatedParseProtocol | None)
allow_pickle (bool)

Return type:

Self

results() → pandas.DataFrame#

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

Return type:: pandas.DataFrame

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

Parameters:

by_alias (bool)
ref_template (str)

Return type:

Dict[str, Any]

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

Parameters:

by_alias (bool)
ref_template (str)
dumps_kwargs (Any)

Return type:

str

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:

Any

classmethod status_col() → str#

Return the status column name for this check.

Return type:: str

summary() → pandas.DataFrame#

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

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

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

table_spec(instance_id: str) → QcTableSpec#

Return the catalog descriptor for this analyzed check.

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

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

classmethod update_forward_refs(**localns: Any) → None#

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

classmethod validate(value: Any) → Self#

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

on: ColumnRef#

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

metadata: _MetadataField#

unmatched_groups: list#

groupby: ColumnRefList#

n_jobs: int#

phenotypic.analysis.GridOccupancy#

This Page