reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/domains/plate_reader/analysis/four_state_event_window/aggregation.py

@@ -0,0 +1,191 @@
+"""Aggregate four-state event-window well summaries into design-level records."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from .contracts import FourStateEventWindowAnalysisSpec, ReductionSpec
+from .event_sensitivity import symmetric_event_sensitivity_half_width
+from .observation_resampling import joint_state_descriptive_resampling_draws
+from .reduction import combine_bound_kinds, invert_bound_kind
+from .seeds import stable_seed
+from .sources import STATE_ORDER, ExperimentSource
+
+
+def build_design_records(
+    midpoint: pd.DataFrame,
+    *,
+    lower: pd.DataFrame,
+    upper: pd.DataFrame,
+    source: ExperimentSource,
+    request: FourStateEventWindowAnalysisSpec,
+    reduction: ReductionSpec,
+) -> pd.DataFrame:
+    """Aggregate one reduction and its event-bound sensitivity records."""
+
+    midpoint_values = _aggregate_state_values(midpoint, request=request)
+    lower_values = _aggregate_state_values(lower, request=request)
+    upper_values = _aggregate_state_values(upper, request=request)
+    records: list[dict[str, object]] = []
+    for design_id, design in midpoint_values.groupby("design_id", sort=True):
+        if set(design["state"].astype(str)) != set(STATE_ORDER):
+            raise ValueError(f"{source.experiment_id}:{design_id}:{reduction.id} lacks complete four-state support.")
+        lower_design = lower_values.loc[lower_values["design_id"].astype(str).eq(str(design_id))].set_index("state")
+        upper_design = upper_values.loc[upper_values["design_id"].astype(str).eq(str(design_id))].set_index("state")
+        design_by_state = design.set_index("state")
+        record: dict[str, object] = {
+            "experiment_id": source.experiment_id,
+            "design_id": str(design_id),
+            "reference_design_id": request.source.reference_design_id,
+            "reduction_id": reduction.id,
+            "reduction_method": reduction.method,
+            "response_basis": reduction.response_basis,
+            "reduction_role": reduction.role,
+            "observation_stat": request.aggregation.observation_stat,
+            "descriptive_resampling_draws": request.aggregation.descriptive_resampling_draws,
+            "descriptive_interval_mass": request.aggregation.descriptive_interval_mass,
+            "event_id": source.event.event_id,
+            "event_time_estimate_assay_h": source.event.estimate_assay_h,
+            "event_time_uncertainty_h": source.event.uncertainty_h,
+            "window_start_event_h": reduction.window_start_event_h,
+            "window_end_event_h": reduction.window_end_event_h,
+            "is_reference": str(design_id) == request.source.reference_design_id,
+            "positive_floor": request.quality.positive_floor,
+            "allowed_max_interior_gap_h": request.quality.max_interior_gap_h,
+            "required_min_observations_per_state": request.quality.min_observations_per_state,
+            "min_observation_count_per_state": int(design["observation_count"].min()),
+            "min_observed_points_per_trace": int(design["min_observed_points"].min()),
+            "max_observed_interior_gap_h": float(design["max_interior_gap_h"].max()),
+            "min_pre_observed_points_per_trace": int(design["min_pre_observed_points"].min()),
+            "max_pre_observed_interior_gap_h": float(design["max_pre_interior_gap_h"].max()),
+        }
+        for state in STATE_ORDER:
+            row = design_by_state.loc[state]
+            lower_row = lower_design.loc[state]
+            upper_row = upper_design.loc[state]
+            record[f"r{state}"] = float(row["response"])
+            record[f"b{state}"] = float(row["anchored_magnitude"])
+            record[f"r{state}_descriptive_resampling_sd"] = float(row["response_descriptive_resampling_sd"])
+            record[f"b{state}_descriptive_resampling_sd"] = float(row["anchored_magnitude_descriptive_resampling_sd"])
+            record[f"r{state}_descriptive_interval_low"] = float(row["response_descriptive_interval_low"])
+            record[f"r{state}_descriptive_interval_high"] = float(row["response_descriptive_interval_high"])
+            record[f"b{state}_descriptive_interval_low"] = float(row["anchored_magnitude_descriptive_interval_low"])
+            record[f"b{state}_descriptive_interval_high"] = float(row["anchored_magnitude_descriptive_interval_high"])
+            record[f"r{state}_event_half_range"] = symmetric_event_sensitivity_half_width(
+                float(row["response"]),
+                float(lower_row["response"]),
+                float(upper_row["response"]),
+            )
+            record[f"b{state}_event_half_range"] = symmetric_event_sensitivity_half_width(
+                float(row["anchored_magnitude"]),
+                float(lower_row["anchored_magnitude"]),
+                float(upper_row["anchored_magnitude"]),
+            )
+            for prefix, field in (("r", "response"), ("b", "anchored_magnitude")):
+                record[f"{prefix}{state}_event_sensitivity_has_policy_clipping"] = any(
+                    bool(candidate[f"{field}_has_policy_clipping"]) for candidate in (row, lower_row, upper_row)
+                )
+                record[f"{prefix}{state}_event_sensitivity_has_instrument_overflow"] = any(
+                    bool(candidate[f"{field}_has_instrument_overflow"]) for candidate in (row, lower_row, upper_row)
+                )
+            record[f"r{state}_has_policy_clipping"] = bool(row["response_has_policy_clipping"])
+            record[f"r{state}_has_instrument_overflow"] = bool(row["response_has_instrument_overflow"])
+            record[f"r{state}_bound_kind"] = str(row["response_bound_kind"])
+            record[f"b{state}_has_policy_clipping"] = bool(row["anchored_magnitude_has_policy_clipping"])
+            record[f"b{state}_has_instrument_overflow"] = bool(row["anchored_magnitude_has_instrument_overflow"])
+            record[f"b{state}_bound_kind"] = str(row["anchored_magnitude_bound_kind"])
+            record[f"n{state}"] = int(row["observation_count"])
+        records.append(record)
+    return pd.DataFrame.from_records(records)
+
+
+def _aggregate_state_values(wells: pd.DataFrame, *, request: FourStateEventWindowAnalysisSpec) -> pd.DataFrame:
+    stat = request.aggregation.observation_stat
+    aggregate = np.median if stat == "median" else np.mean
+    anchor_id = request.source.reference_design_id
+    anchor = wells.loc[wells["design_id"].astype(str).eq(anchor_id)]
+    if set(anchor["state"].astype(str)) != set(STATE_ORDER):
+        raise ValueError(f"reference design {anchor_id!r} lacks complete four-state support.")
+    rows: list[dict[str, object]] = []
+    alpha = (1.0 - request.aggregation.descriptive_interval_mass) / 2.0
+    for (design_id, state), frame in wells.groupby(["design_id", "state"], sort=True):
+        response_values = frame["response_well"].to_numpy(dtype=float)
+        magnitude_values = frame["magnitude_well"].to_numpy(dtype=float)
+        state_anchor = anchor.loc[anchor["state"].astype(str).eq(str(state))]
+        anchor_values = state_anchor["magnitude_well"].to_numpy(dtype=float)
+        minimum = request.quality.min_observations_per_state
+        if min(len(response_values), len(magnitude_values), len(anchor_values)) < minimum:
+            raise ValueError(
+                f"{design_id}:{state} requires at least {minimum} within-experiment design and reference observations."
+            )
+        rng = np.random.default_rng(
+            stable_seed(
+                request.aggregation.random_seed,
+                str(frame["experiment_id"].iloc[0]),
+                str(design_id),
+                str(state),
+                str(frame["reduction_id"].iloc[0]),
+            )
+        )
+        response_draws, anchored_magnitude_draws = joint_state_descriptive_resampling_draws(
+            response_values,
+            magnitude_values,
+            anchor_values,
+            samples=request.aggregation.descriptive_resampling_draws,
+            stat=stat,
+            rng=rng,
+            paired_anchor=str(design_id) == anchor_id,
+        )
+        response_bound = combine_bound_kinds(*frame["response_bound_kind"])
+        design_magnitude_bound = combine_bound_kinds(*frame["magnitude_bound_kind"])
+        anchor_magnitude_bound = combine_bound_kinds(*state_anchor["magnitude_bound_kind"])
+        anchored_bound = (
+            "exact"
+            if str(design_id) == anchor_id
+            else combine_bound_kinds(
+                design_magnitude_bound,
+                invert_bound_kind(anchor_magnitude_bound),
+            )
+        )
+        rows.append(
+            {
+                "design_id": str(design_id),
+                "state": str(state),
+                "response": float(aggregate(response_values)),
+                "anchored_magnitude": float(aggregate(magnitude_values) - aggregate(anchor_values)),
+                "response_descriptive_resampling_sd": float(np.std(response_draws, ddof=1)),
+                "anchored_magnitude_descriptive_resampling_sd": float(np.std(anchored_magnitude_draws, ddof=1)),
+                "response_descriptive_interval_low": float(np.quantile(response_draws, alpha)),
+                "response_descriptive_interval_high": float(np.quantile(response_draws, 1.0 - alpha)),
+                "anchored_magnitude_descriptive_interval_low": float(np.quantile(anchored_magnitude_draws, alpha)),
+                "anchored_magnitude_descriptive_interval_high": float(
+                    np.quantile(anchored_magnitude_draws, 1.0 - alpha)
+                ),
+                "observation_count": int(min(len(response_values), len(magnitude_values))),
+                "min_observed_points": int(
+                    frame[["response_observed_point_count", "magnitude_observed_point_count"]].min().min()
+                ),
+                "max_interior_gap_h": float(
+                    frame[["response_max_interior_gap_h", "magnitude_max_interior_gap_h"]].max().max()
+                ),
+                "min_pre_observed_points": int(frame["response_pre_observed_point_count"].min()),
+                "max_pre_interior_gap_h": float(frame["response_pre_max_interior_gap_h"].max()),
+                "response_has_policy_clipping": bool(frame["response_policy_clipped_point_count"].gt(0).any()),
+                "response_has_instrument_overflow": bool(frame["response_instrument_overflow_point_count"].gt(0).any()),
+                "response_bound_kind": response_bound,
+                "anchored_magnitude_has_policy_clipping": bool(
+                    frame["magnitude_policy_clipped_point_count"].gt(0).any()
+                    or state_anchor["magnitude_policy_clipped_point_count"].gt(0).any()
+                ),
+                "anchored_magnitude_has_instrument_overflow": bool(
+                    frame["magnitude_instrument_overflow_point_count"].gt(0).any()
+                    or state_anchor["magnitude_instrument_overflow_point_count"].gt(0).any()
+                ),
+                "anchored_magnitude_bound_kind": anchored_bound,
+            }
+        )
+    return pd.DataFrame.from_records(rows)
+
+
+__all__ = ["build_design_records"]

reader_workbench/domains/plate_reader/analysis/four_state_event_window/contract_fields.py

@@ -0,0 +1,50 @@
+"""Validate scalar and mapping fields used by four-state event-window contracts."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import numpy as np
+
+
+def mapping(value: object, *, context: str) -> dict[str, Any]:
+    if not isinstance(value, Mapping):
+        raise ValueError(f"{context} must be a mapping.")
+    return {str(key): item for key, item in value.items()}
+
+
+def exact_fields(
+    value: object,
+    *,
+    context: str,
+    required: set[str],
+    optional: set[str] | None = None,
+) -> dict[str, Any]:
+    payload = mapping(value, context=context)
+    allowed = required | (optional or set())
+    unknown = sorted(set(payload) - allowed)
+    if unknown:
+        raise ValueError(f"{context} has unknown fields: {unknown}.")
+    missing = sorted(required - set(payload))
+    if missing:
+        raise ValueError(f"{context} is missing required fields: {missing}.")
+    return payload
+
+
+def nonempty(value: object, *, context: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{context} must be a non-empty string.")
+    return value.strip()
+
+
+def finite(value: object, *, context: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f"{context} must be a finite number.")
+    result = float(value)
+    if not np.isfinite(result):
+        raise ValueError(f"{context} must be a finite number.")
+    return result
+
+
+__all__ = ["exact_fields", "finite", "mapping", "nonempty"]

reader_workbench/domains/plate_reader/analysis/four_state_event_window/contracts.py

@@ -0,0 +1,320 @@
+"""Strict contracts for event-relative plate-reader response summaries."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Literal
+
+from .contract_fields import exact_fields as _exact_fields
+from .contract_fields import finite as _finite
+from .contract_fields import mapping as _mapping
+from .contract_fields import nonempty as _nonempty
+from .design_dispositions import DesignDisposition, parse_design_dispositions
+from .well_exclusions import WellExclusion, parse_well_exclusions
+
+ReductionMethod = Literal["geometric_time_mean", "integrated_linear_mean"]
+ResponseBasis = Literal["post_window", "post_minus_pre"]
+ReductionRole = Literal["primary", "sensitivity"]
+ObservationStat = Literal["mean", "median"]
+EventEstimateMethod = Literal["segment_gap_midpoint"]
+
+
+@dataclass(frozen=True)
+class FourStateEventWindowSourceSpec:
+    response_channel: str
+    magnitude_channel: str
+    growth_channel: str
+    reference_design_id: str
+    state_column: str
+    state_values: Mapping[str, str]
+    state_labels: Mapping[str, str]
+    state_values_case_sensitive: bool = True
+    well_exclusions: tuple[WellExclusion, ...] = ()
+    design_dispositions: tuple[DesignDisposition, ...] = ()
+
+    @classmethod
+    def from_mapping(cls, value: object) -> FourStateEventWindowSourceSpec:
+        fields = {
+            "response_channel",
+            "magnitude_channel",
+            "growth_channel",
+            "reference_design_id",
+            "state_column",
+            "state_values",
+        }
+        payload = _exact_fields(
+            value,
+            context="source",
+            required=fields,
+            optional={
+                "design_dispositions",
+                "state_labels",
+                "state_values_case_sensitive",
+                "well_exclusions",
+            },
+        )
+        state_values = _mapping(payload["state_values"], context="source.state_values")
+        expected_states = {"00", "10", "01", "11"}
+        if set(state_values) != expected_states:
+            raise ValueError("source.state_values must define exactly 00, 10, 01, and 11.")
+        normalized_values = {
+            state: _nonempty(state_values[state], context=f"source.state_values.{state}")
+            for state in sorted(expected_states)
+        }
+        if len(set(normalized_values.values())) != 4:
+            raise ValueError("source.state_values must map to four distinct source values.")
+        state_labels = _mapping(payload.get("state_labels", normalized_values), context="source.state_labels")
+        if set(state_labels) != expected_states:
+            raise ValueError("source.state_labels must define exactly 00, 10, 01, and 11.")
+        normalized_labels = {
+            state: _nonempty(state_labels[state], context=f"source.state_labels.{state}")
+            for state in sorted(expected_states)
+        }
+        case_sensitive = payload.get("state_values_case_sensitive", True)
+        if not isinstance(case_sensitive, bool):
+            raise ValueError("source.state_values_case_sensitive must be true or false.")
+        reference_design_id = _nonempty(payload["reference_design_id"], context="source.reference_design_id")
+        return cls(
+            response_channel=_nonempty(payload["response_channel"], context="source.response_channel"),
+            magnitude_channel=_nonempty(payload["magnitude_channel"], context="source.magnitude_channel"),
+            growth_channel=_nonempty(payload["growth_channel"], context="source.growth_channel"),
+            reference_design_id=reference_design_id,
+            state_column=_nonempty(payload["state_column"], context="source.state_column"),
+            state_values=normalized_values,
+            state_labels=normalized_labels,
+            state_values_case_sensitive=case_sensitive,
+            well_exclusions=parse_well_exclusions(payload.get("well_exclusions", [])),
+            design_dispositions=parse_design_dispositions(payload.get("design_dispositions", [])),
+        )
+
+    def require_known_experiment_ids(self, experiment_ids: Sequence[str]) -> None:
+        """Reject design selections that do not name a resolved source experiment."""
+
+        known = {str(value) for value in experiment_ids}
+        referenced = {item.experiment_id for item in (*self.well_exclusions, *self.design_dispositions)}
+        unknown = sorted(referenced - known)
+        if unknown:
+            raise ValueError(f"source experiment selections name unknown experiments: {unknown}.")
+
+    def require_known_reduction_ids(self, reduction_ids: Sequence[str]) -> None:
+        """Reject design dispositions that do not name a declared reduction."""
+
+        known = {str(value) for value in reduction_ids}
+        for disposition in self.design_dispositions:
+            if disposition.reduction_id not in known:
+                raise ValueError(f"design disposition names unknown reduction {disposition.reduction_id!r}.")
+
+
+@dataclass(frozen=True)
+class EventSpec:
+    event_id: str
+    event_kind: str
+    segment_column: str
+    pre_segment_index: int
+    post_segment_index: int
+    estimate_method: EventEstimateMethod
+    declaration: str
+
+    @classmethod
+    def from_mapping(cls, value: object) -> EventSpec:
+        fields = {
+            "event_id",
+            "event_kind",
+            "segment_column",
+            "pre_segment_index",
+            "post_segment_index",
+            "estimate_method",
+            "declaration",
+        }
+        payload = _exact_fields(value, context="event", required=fields)
+        pre = payload["pre_segment_index"]
+        post = payload["post_segment_index"]
+        if isinstance(pre, bool) or not isinstance(pre, int):
+            raise ValueError("event.pre_segment_index must be an integer.")
+        if isinstance(post, bool) or not isinstance(post, int):
+            raise ValueError("event.post_segment_index must be an integer.")
+        if pre == post:
+            raise ValueError("event segment indexes must differ.")
+        estimate = _nonempty(payload["estimate_method"], context="event.estimate_method")
+        if estimate != "segment_gap_midpoint":
+            raise ValueError("event.estimate_method must be 'segment_gap_midpoint' for symmetric event uncertainty.")
+        return cls(
+            event_id=_nonempty(payload["event_id"], context="event.event_id"),
+            event_kind=_nonempty(payload["event_kind"], context="event.event_kind"),
+            segment_column=_nonempty(payload["segment_column"], context="event.segment_column"),
+            pre_segment_index=pre,
+            post_segment_index=post,
+            estimate_method=estimate,
+            declaration=_nonempty(payload["declaration"], context="event.declaration"),
+        )
+
+
+@dataclass(frozen=True)
+class ReductionSpec:
+    id: str
+    window_start_event_h: float
+    window_end_event_h: float
+    method: ReductionMethod
+    response_basis: ResponseBasis
+    role: ReductionRole
+    pre_window_duration_h: float | None = None
+
+    @classmethod
+    def from_mapping(cls, value: object, *, index: int) -> ReductionSpec:
+        required = {
+            "id",
+            "window_start_event_h",
+            "window_end_event_h",
+            "method",
+            "response_basis",
+            "role",
+        }
+        payload = _exact_fields(
+            value,
+            context=f"reductions[{index}]",
+            required=required,
+            optional={"pre_window_duration_h"},
+        )
+        start = _finite(payload["window_start_event_h"], context=f"reductions[{index}].window_start_event_h")
+        end = _finite(payload["window_end_event_h"], context=f"reductions[{index}].window_end_event_h")
+        if start < 0.0 or end <= start:
+            raise ValueError(f"reductions[{index}] requires 0 <= window start < window end.")
+        method = _nonempty(payload["method"], context=f"reductions[{index}].method")
+        if method not in {"geometric_time_mean", "integrated_linear_mean"}:
+            raise ValueError(f"reductions[{index}].method is unsupported: {method!r}.")
+        basis = _nonempty(payload["response_basis"], context=f"reductions[{index}].response_basis")
+        if basis not in {"post_window", "post_minus_pre"}:
+            raise ValueError(f"reductions[{index}].response_basis is unsupported: {basis!r}.")
+        role = _nonempty(payload["role"], context=f"reductions[{index}].role")
+        if role not in {"primary", "sensitivity"}:
+            raise ValueError(f"reductions[{index}].role is unsupported: {role!r}.")
+        raw_pre = payload.get("pre_window_duration_h")
+        pre = None if raw_pre is None else _finite(raw_pre, context=f"reductions[{index}].pre_window_duration_h")
+        if basis == "post_minus_pre" and (pre is None or pre <= 0.0):
+            raise ValueError(f"reductions[{index}] post_minus_pre requires a positive pre_window_duration_h.")
+        if basis == "post_window" and pre is not None:
+            raise ValueError(f"reductions[{index}] pre_window_duration_h is only valid for post_minus_pre.")
+        return cls(
+            id=_nonempty(payload["id"], context=f"reductions[{index}].id"),
+            window_start_event_h=start,
+            window_end_event_h=end,
+            method=method,
+            response_basis=basis,
+            role=role,
+            pre_window_duration_h=pre,
+        )
+
+
+@dataclass(frozen=True)
+class AggregationSpec:
+    observation_stat: ObservationStat
+    descriptive_resampling_draws: int
+    descriptive_interval_mass: float
+    random_seed: int
+
+    @classmethod
+    def from_mapping(cls, value: object) -> AggregationSpec:
+        fields = {
+            "observation_stat",
+            "descriptive_resampling_draws",
+            "descriptive_interval_mass",
+            "random_seed",
+        }
+        payload = _exact_fields(value, context="aggregation", required=fields)
+        stat = _nonempty(payload["observation_stat"], context="aggregation.observation_stat")
+        if stat not in {"mean", "median"}:
+            raise ValueError(f"aggregation.observation_stat is unsupported: {stat!r}.")
+        samples = payload["descriptive_resampling_draws"]
+        seed = payload["random_seed"]
+        if isinstance(samples, bool) or not isinstance(samples, int) or samples < 100:
+            raise ValueError("aggregation.descriptive_resampling_draws must be an integer of at least 100.")
+        if isinstance(seed, bool) or not isinstance(seed, int) or seed < 0:
+            raise ValueError("aggregation.random_seed must be a non-negative integer.")
+        level = _finite(payload["descriptive_interval_mass"], context="aggregation.descriptive_interval_mass")
+        if not 0.5 < level < 1.0:
+            raise ValueError("aggregation.descriptive_interval_mass must be between 0.5 and 1.0.")
+        return cls(
+            observation_stat=stat,
+            descriptive_resampling_draws=samples,
+            descriptive_interval_mass=level,
+            random_seed=seed,
+        )
+
+
+@dataclass(frozen=True)
+class QualitySpec:
+    positive_floor: float
+    max_interior_gap_h: float
+    min_observations_per_state: int
+
+    @classmethod
+    def from_mapping(cls, value: object) -> QualitySpec:
+        fields = {"positive_floor", "max_interior_gap_h", "min_observations_per_state"}
+        payload = _exact_fields(value, context="quality", required=fields)
+        floor = _finite(payload["positive_floor"], context="quality.positive_floor")
+        gap = _finite(payload["max_interior_gap_h"], context="quality.max_interior_gap_h")
+        observations = payload["min_observations_per_state"]
+        if floor <= 0.0:
+            raise ValueError("quality.positive_floor must be positive.")
+        if gap <= 0.0:
+            raise ValueError("quality.max_interior_gap_h must be positive.")
+        if isinstance(observations, bool) or not isinstance(observations, int) or observations < 2:
+            raise ValueError("quality.min_observations_per_state must be an integer of at least 2.")
+        return cls(
+            positive_floor=floor,
+            max_interior_gap_h=gap,
+            min_observations_per_state=observations,
+        )
+
+
+@dataclass(frozen=True)
+class FourStateEventWindowAnalysisSpec:
+    source: FourStateEventWindowSourceSpec
+    event: EventSpec
+    reductions: tuple[ReductionSpec, ...]
+    aggregation: AggregationSpec
+    quality: QualitySpec
+
+    @property
+    def primary_reduction(self) -> ReductionSpec:
+        return next(spec for spec in self.reductions if spec.role == "primary")
+
+    @classmethod
+    def from_mapping(cls, value: object) -> FourStateEventWindowAnalysisSpec:
+        fields = {
+            "source",
+            "event",
+            "reductions",
+            "aggregation",
+            "quality",
+        }
+        payload = _exact_fields(value, context="analysis", required=fields)
+        raw_reductions = payload["reductions"]
+        if isinstance(raw_reductions, (str, bytes)) or not isinstance(raw_reductions, Sequence):
+            raise ValueError("reductions must be a non-empty sequence.")
+        reductions = tuple(ReductionSpec.from_mapping(item, index=index) for index, item in enumerate(raw_reductions))
+        ids = [spec.id for spec in reductions]
+        if not reductions or len(ids) != len(set(ids)):
+            raise ValueError("reduction ids must be non-empty and unique.")
+        if sum(spec.role == "primary" for spec in reductions) != 1:
+            raise ValueError("analysis must declare exactly one primary reduction.")
+        source = FourStateEventWindowSourceSpec.from_mapping(payload["source"])
+        source.require_known_reduction_ids(ids)
+        return cls(
+            source=source,
+            event=EventSpec.from_mapping(payload["event"]),
+            reductions=reductions,
+            aggregation=AggregationSpec.from_mapping(payload["aggregation"]),
+            quality=QualitySpec.from_mapping(payload["quality"]),
+        )
+
+
+__all__ = [
+    "AggregationSpec",
+    "EventSpec",
+    "QualitySpec",
+    "ReductionSpec",
+    "FourStateEventWindowAnalysisSpec",
+    "FourStateEventWindowSourceSpec",
+]

reader_workbench/domains/plate_reader/analysis/four_state_event_window/design_dispositions.py

@@ -0,0 +1,54 @@
+"""Define plate- and reduction-scoped design eligibility dispositions."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from .contract_fields import exact_fields, nonempty
+
+_OBSERVATION_REASON = "insufficient_state_observations"
+
+
+@dataclass(frozen=True)
+class DesignDisposition:
+    experiment_id: str
+    design_id: str
+    state: str
+    reduction_id: str
+    reason: str
+
+
+def parse_design_dispositions(value: object) -> tuple[DesignDisposition, ...]:
+    if isinstance(value, (str, bytes)) or not isinstance(value, Sequence):
+        raise ValueError("source.design_dispositions must be a sequence.")
+    dispositions: list[DesignDisposition] = []
+    for index, item in enumerate(value):
+        context = f"source.design_dispositions[{index}]"
+        payload = exact_fields(
+            item,
+            context=context,
+            required={"experiment_id", "design_id", "state", "reduction_id", "reason"},
+        )
+        state = nonempty(payload["state"], context=f"{context}.state")
+        if state not in {"00", "10", "01", "11"}:
+            raise ValueError(f"{context}.state must be 00, 10, 01, or 11.")
+        reason = nonempty(payload["reason"], context=f"{context}.reason")
+        if reason != _OBSERVATION_REASON:
+            raise ValueError(f"{context}.reason must be {_OBSERVATION_REASON!r}.")
+        dispositions.append(
+            DesignDisposition(
+                experiment_id=nonempty(payload["experiment_id"], context=f"{context}.experiment_id"),
+                design_id=nonempty(payload["design_id"], context=f"{context}.design_id"),
+                state=state,
+                reduction_id=nonempty(payload["reduction_id"], context=f"{context}.reduction_id"),
+                reason=reason,
+            )
+        )
+    keys = [(item.experiment_id, item.design_id, item.reduction_id) for item in dispositions]
+    if len(keys) != len(set(keys)):
+        raise ValueError("source.design_dispositions must not repeat an experiment, design, and reduction.")
+    return tuple(dispositions)
+
+
+__all__ = ["DesignDisposition", "parse_design_dispositions"]