reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/domains/plate_reader/plots/dual_reporter_triptych_render.py

@@ -0,0 +1,195 @@
+"""Static Matplotlib rendering for the dual-reporter triptych contract."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.figure import Figure
+
+from reader_workbench.plotting.style import use_style
+
+from .dual_reporter_triptych import DualReporterTriptychData
+
+_DEFAULT_COLORS = ("#334155", "#0f766e", "#2563eb", "#be123c")
+_LINESTYLES = ("-", "--", "-.", ":")
+
+
+def render_dual_reporter_triptych(
+    data: DualReporterTriptychData,
+    *,
+    time_col: str,
+    treatment_col: str,
+    acquisition_transition_time_h: float | None = None,
+    title: str | None = None,
+    colors: Sequence[str] | None = None,
+    figsize: tuple[float, float] = (10.5, 3.5),
+) -> Figure:
+    """Render two kinetic panels and one observed-value snapshot panel."""
+
+    if data.od600_time.empty:
+        raise ValueError("dual_reporter_triptych: no growth time-series data available")
+    if data.ratio_time.empty:
+        raise ValueError("dual_reporter_triptych: no ratio time-series data available")
+    if data.snapshot_stats.empty:
+        raise ValueError("dual_reporter_triptych: no snapshot data available")
+
+    order = list(data.treatment_order)
+    palette = list(colors or _DEFAULT_COLORS)
+    if not palette:
+        raise ValueError("dual_reporter_triptych: colors must contain at least one color")
+    color_map = {value: palette[index % len(palette)] for index, value in enumerate(order)}
+
+    with use_style(
+        rc={
+            "axes_titleweight": "regular",
+            "axes_titlesize": 11.0,
+            "axes_labelsize": 10.0,
+            "font_size": 10.0,
+            "legend_fontsize": 9.0,
+            "legend_title_fontsize": 9.0,
+            "xtick_labelsize": 9.0,
+            "ytick_labelsize": 9.0,
+        },
+        color_cycle=palette,
+    ):
+        figure, axes = plt.subplots(1, 3, figsize=figsize, constrained_layout=True)
+        _draw_time_panel(
+            axes[0],
+            data.od600_time,
+            time_col=time_col,
+            treatment_col=treatment_col,
+            order=order,
+            color_map=color_map,
+            snapshot_time=data.snapshot_time,
+            acquisition_transition_time_h=acquisition_transition_time_h,
+            title=f"{data.growth_channel} kinetics",
+            ylabel=data.growth_channel,
+        )
+        _draw_time_panel(
+            axes[1],
+            data.ratio_time,
+            time_col=time_col,
+            treatment_col=treatment_col,
+            order=order,
+            color_map=color_map,
+            snapshot_time=data.snapshot_time,
+            acquisition_transition_time_h=acquisition_transition_time_h,
+            title=f"{data.ratio_channel} kinetics",
+            ylabel=data.ratio_channel,
+        )
+        _draw_snapshot_panel(
+            axes[2],
+            data,
+            treatment_col=treatment_col,
+            color_map=color_map,
+            title=f"{data.snapshot_channel} snapshot at {data.snapshot_time:g} h",
+        )
+
+        handles, labels = axes[0].get_legend_handles_labels()
+        if handles:
+            figure.legend(
+                handles,
+                labels,
+                loc="outside lower center",
+                ncols=max(1, min(len(handles), 4)),
+                title=str(treatment_col).replace("_", " ").capitalize(),
+            )
+        if title:
+            figure.suptitle(str(title), fontweight="normal")
+        return figure
+
+
+def _draw_time_panel(
+    axis,
+    frame,
+    *,
+    time_col: str,
+    treatment_col: str,
+    order: list[str],
+    color_map: dict[str, str],
+    snapshot_time: float,
+    acquisition_transition_time_h: float | None,
+    title: str,
+    ylabel: str,
+) -> None:
+    for index, treatment in enumerate(order):
+        subset = frame[frame[treatment_col].astype(str) == str(treatment)].sort_values(time_col)
+        if subset.empty:
+            continue
+        x = subset[time_col].to_numpy(dtype=float)
+        mean = subset["y_mean"].to_numpy(dtype=float)
+        lower = subset["y_lo"].to_numpy(dtype=float)
+        upper = subset["y_hi"].to_numpy(dtype=float)
+        color = color_map[treatment]
+        axis.fill_between(x, lower, upper, color=color, alpha=0.16, linewidth=0)
+        axis.plot(
+            x,
+            mean,
+            color=color,
+            linestyle=_LINESTYLES[index % len(_LINESTYLES)],
+            linewidth=1.7,
+            label=treatment,
+        )
+
+    axis.axvline(float(snapshot_time), color="#111827", linewidth=1.0)
+    if acquisition_transition_time_h is not None:
+        transition = float(acquisition_transition_time_h)
+        if np.isfinite(transition):
+            axis.axvline(transition, color="#64748b", linewidth=1.0, linestyle=(0, (5, 3)))
+    axis.set_title(title)
+    axis.set_xlabel("Time (h)")
+    axis.set_ylabel(ylabel)
+
+
+def _draw_snapshot_panel(
+    axis,
+    data: DualReporterTriptychData,
+    *,
+    treatment_col: str,
+    color_map: dict[str, str],
+    title: str,
+) -> None:
+    order = list(data.treatment_order)
+    x_positions = {value: float(index) for index, value in enumerate(order)}
+
+    for treatment in order:
+        subset = data.snapshot_points[data.snapshot_points[treatment_col].astype(str) == str(treatment)].sort_values(
+            "observation_index"
+        )
+        offsets = np.linspace(-0.12, 0.12, len(subset)) if len(subset) > 1 else np.zeros(len(subset))
+        if not subset.empty:
+            axis.scatter(
+                x_positions[treatment] + offsets,
+                subset["value"].to_numpy(dtype=float),
+                s=28,
+                facecolors="white",
+                edgecolors=color_map[treatment],
+                linewidths=1.0,
+                zorder=3,
+            )
+
+    for _, row in data.snapshot_stats.iterrows():
+        treatment = str(row[treatment_col])
+        if treatment not in x_positions:
+            continue
+        center = x_positions[treatment]
+        mean = float(row["y_mean"])
+        lower = float(row["y_lo"])
+        upper = float(row["y_hi"])
+        if not all(np.isfinite(value) for value in (mean, lower, upper)):
+            continue
+        color = color_map[treatment]
+        axis.plot([center, center], [lower, upper], color=color, linewidth=1.0, zorder=4)
+        axis.plot([center - 0.05, center + 0.05], [lower, lower], color=color, linewidth=1.0, zorder=4)
+        axis.plot([center - 0.05, center + 0.05], [upper, upper], color=color, linewidth=1.0, zorder=4)
+        axis.plot([center - 0.16, center + 0.16], [mean, mean], color=color, linewidth=2.2, zorder=5)
+
+    axis.set_title(title)
+    axis.set_xlabel(str(treatment_col).replace("_", " ").capitalize())
+    axis.set_ylabel(data.snapshot_channel)
+    axis.set_xticks(range(len(order)), order, rotation=0)
+
+
+__all__ = ["render_dual_reporter_triptych"]

reader_workbench/domains/plate_reader/plots/four_state_event_window/__init__.py

@@ -0,0 +1,26 @@
+"""Canonical four-state event-window plot selection and rendering."""
+
+from .diagnostic import (
+    FourStateEventWindowDiagnostic,
+    prepare_four_state_event_window_diagnostic,
+)
+from .diagnostic_render import render_four_state_event_window_diagnostic
+from .schema import COMPONENT_COLUMNS, MAGNITUDE_COLUMNS, RESPONSE_COLUMNS, STATE_ORDER
+from .summary import (
+    FourStateEventWindowSummaryMatrix,
+    four_state_event_window_summary_matrix,
+    render_four_state_event_window_summary,
+)
+
+__all__ = [
+    "COMPONENT_COLUMNS",
+    "MAGNITUDE_COLUMNS",
+    "RESPONSE_COLUMNS",
+    "FourStateEventWindowDiagnostic",
+    "FourStateEventWindowSummaryMatrix",
+    "STATE_ORDER",
+    "prepare_four_state_event_window_diagnostic",
+    "render_four_state_event_window_diagnostic",
+    "render_four_state_event_window_summary",
+    "four_state_event_window_summary_matrix",
+]

reader_workbench/domains/plate_reader/plots/four_state_event_window/diagnostic.py

@@ -0,0 +1,295 @@
+"""Select one diagnostic from canonical four-state event-window records."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from .schema import COMPONENT_COLUMNS, STATE_ORDER
+
+BOUND_KINDS = frozenset({"exact", "lower", "upper", "indeterminate"})
+
+
+@dataclass(frozen=True)
+class FourStateEventWindowDiagnostic:
+    """One source design and primary reduction ready for rendering."""
+
+    source_experiment_id: str
+    design_id: str
+    reference_design_id: str
+    reduction_id: str
+    reduction_method: str
+    response_basis: str
+    observation_stat: str
+    descriptive_resampling_draws: int
+    descriptive_interval_mass: float
+    event_id: str
+    event_time_uncertainty_h: float
+    window: tuple[float, float]
+    pre_window: tuple[float, float] | None
+    component_values: tuple[float, ...]
+    component_descriptive_interval_low: tuple[float, ...]
+    component_descriptive_interval_high: tuple[float, ...]
+    component_event_half_range: tuple[float, ...]
+    component_bound_kinds: tuple[str, ...]
+    component_has_policy_clipping: tuple[bool, ...]
+    component_has_instrument_overflow: tuple[bool, ...]
+    component_event_has_policy_clipping: tuple[bool, ...]
+    component_event_has_instrument_overflow: tuple[bool, ...]
+    traces: pd.DataFrame
+
+
+def prepare_four_state_event_window_diagnostic(
+    traces: pd.DataFrame,
+    designs: pd.DataFrame,
+    *,
+    source_experiment_id: str,
+    design_id: str,
+    reduction_id: str,
+    pre_window_duration_h: float | None,
+) -> FourStateEventWindowDiagnostic:
+    """Select and validate one diagnostic subject from canonical records."""
+
+    source_experiment_id = _identifier(source_experiment_id, field="source_experiment_id")
+    design_id = _identifier(design_id, field="design_id")
+    reduction_id = _identifier(reduction_id, field="reduction_id")
+    _require_columns(designs, _design_columns(), record="designs")
+    selected = designs.loc[
+        designs["experiment_id"].astype(str).eq(source_experiment_id)
+        & designs["design_id"].astype(str).eq(design_id)
+        & designs["reduction_id"].astype(str).eq(reduction_id)
+    ]
+    if len(selected) != 1:
+        raise ValueError(
+            "four-state event-window diagnostic requires exactly one designs row for "
+            f"source experiment {source_experiment_id!r}, design {design_id!r}, and reduction {reduction_id!r}; "
+            f"found {len(selected)}"
+        )
+    row = selected.iloc[0]
+    response_basis = _choice(row["response_basis"], field="response_basis", choices={"post_window", "post_minus_pre"})
+    pre_window = _pre_window(
+        response_basis=response_basis,
+        pre_window_duration_h=pre_window_duration_h,
+        event_time_uncertainty_h=float(row["event_time_uncertainty_h"]),
+    )
+    window = (float(row["window_start_event_h"]), float(row["window_end_event_h"]))
+    if not np.isfinite(window).all() or window[1] <= window[0]:
+        raise ValueError("four-state event-window diagnostic requires a finite window start before its end")
+
+    values = tuple(float(row[column]) for column in COMPONENT_COLUMNS)
+    interval_low = tuple(float(row[f"{column}_descriptive_interval_low"]) for column in COMPONENT_COLUMNS)
+    interval_high = tuple(float(row[f"{column}_descriptive_interval_high"]) for column in COMPONENT_COLUMNS)
+    event_half_range = tuple(float(row[f"{column}_event_half_range"]) for column in COMPONENT_COLUMNS)
+    if not np.isfinite((*values, *interval_low, *interval_high, *event_half_range)).all():
+        raise ValueError("four-state event-window diagnostic requires finite component dispersion values")
+    if any(low > high for low, high in zip(interval_low, interval_high, strict=True)):
+        raise ValueError(
+            "four-state event-window diagnostic descriptive-interval lower bounds must not exceed upper bounds"
+        )
+    if any(value < 0.0 for value in event_half_range):
+        raise ValueError("four-state event-window diagnostic event-sensitivity half-ranges must be non-negative")
+
+    trace_set = _select_traces(
+        traces,
+        source_experiment_id=source_experiment_id,
+        design_id=design_id,
+        reference_design_id=_identifier(row["reference_design_id"], field="reference_design_id"),
+    )
+    return FourStateEventWindowDiagnostic(
+        source_experiment_id=source_experiment_id,
+        design_id=design_id,
+        reference_design_id=_identifier(row["reference_design_id"], field="reference_design_id"),
+        reduction_id=reduction_id,
+        reduction_method=_identifier(row["reduction_method"], field="reduction_method"),
+        response_basis=response_basis,
+        observation_stat=_choice(row["observation_stat"], field="observation_stat", choices={"mean", "median"}),
+        descriptive_resampling_draws=_positive_int(
+            row["descriptive_resampling_draws"], field="descriptive_resampling_draws"
+        ),
+        descriptive_interval_mass=_descriptive_interval_mass(row["descriptive_interval_mass"]),
+        event_id=_identifier(row["event_id"], field="event_id"),
+        event_time_uncertainty_h=_nonnegative_float(row["event_time_uncertainty_h"], field="event_time_uncertainty_h"),
+        window=window,
+        pre_window=pre_window,
+        component_values=values,
+        component_descriptive_interval_low=interval_low,
+        component_descriptive_interval_high=interval_high,
+        component_event_half_range=event_half_range,
+        component_bound_kinds=tuple(
+            _choice(row[f"{column}_bound_kind"], field=f"{column}_bound_kind", choices=BOUND_KINDS)
+            for column in COMPONENT_COLUMNS
+        ),
+        component_has_policy_clipping=_component_bools(row, suffix="has_policy_clipping"),
+        component_has_instrument_overflow=_component_bools(row, suffix="has_instrument_overflow"),
+        component_event_has_policy_clipping=_component_bools(row, suffix="event_sensitivity_has_policy_clipping"),
+        component_event_has_instrument_overflow=_component_bools(
+            row, suffix="event_sensitivity_has_instrument_overflow"
+        ),
+        traces=trace_set,
+    )
+
+
+def _design_columns() -> set[str]:
+    component_columns = {
+        f"{component}_{suffix}"
+        for component in COMPONENT_COLUMNS
+        for suffix in (
+            "descriptive_interval_low",
+            "descriptive_interval_high",
+            "event_half_range",
+            "bound_kind",
+            "has_policy_clipping",
+            "has_instrument_overflow",
+            "event_sensitivity_has_policy_clipping",
+            "event_sensitivity_has_instrument_overflow",
+        )
+    }
+    return {
+        "experiment_id",
+        "design_id",
+        "reference_design_id",
+        "reduction_id",
+        "reduction_method",
+        "response_basis",
+        "observation_stat",
+        "descriptive_resampling_draws",
+        "descriptive_interval_mass",
+        "event_id",
+        "event_time_uncertainty_h",
+        "window_start_event_h",
+        "window_end_event_h",
+        *COMPONENT_COLUMNS,
+        *component_columns,
+    }
+
+
+def _select_traces(
+    traces: pd.DataFrame,
+    *,
+    source_experiment_id: str,
+    design_id: str,
+    reference_design_id: str,
+) -> pd.DataFrame:
+    _require_columns(
+        traces,
+        {
+            "experiment_id",
+            "design_id",
+            "position",
+            "state",
+            "time_from_event_h",
+            "value",
+            "value_policy_clipped",
+            "value_instrument_overflow",
+            "value_bound_kind",
+            "signal_kind",
+        },
+        record="traces",
+    )
+    source = traces.loc[traces["experiment_id"].astype(str).eq(source_experiment_id)]
+    selected = source.loc[source["design_id"].astype(str).eq(design_id)]
+    _validate_trace_support(selected, design_id=design_id, signal_kinds=("growth", "response", "magnitude"))
+    frames = [selected]
+    if reference_design_id != design_id:
+        reference = source.loc[
+            source["design_id"].astype(str).eq(reference_design_id) & source["signal_kind"].astype(str).eq("magnitude")
+        ]
+        _validate_trace_support(reference, design_id=reference_design_id, signal_kinds=("magnitude",))
+        frames.append(reference)
+    result = pd.concat(frames, ignore_index=True).sort_values(
+        ["signal_kind", "design_id", "state", "position", "time_from_event_h"], kind="stable"
+    )
+    numeric = result.loc[:, ["time_from_event_h", "value"]].to_numpy(dtype=float)
+    if not np.isfinite(numeric).all():
+        raise ValueError("four-state event-window diagnostic traces require finite event-relative times and values")
+    log_rows = result["signal_kind"].astype(str).isin({"response", "magnitude"})
+    if result.loc[log_rows, "value"].astype(float).le(0.0).any():
+        raise ValueError("four-state event-window diagnostic response and magnitude traces must be positive")
+    unknown_bounds = sorted(set(result["value_bound_kind"].astype(str)) - BOUND_KINDS)
+    if unknown_bounds:
+        raise ValueError(f"four-state event-window diagnostic traces contain unsupported bounds: {unknown_bounds}")
+    return result.reset_index(drop=True)
+
+
+def _pre_window(
+    *,
+    response_basis: str,
+    pre_window_duration_h: float | None,
+    event_time_uncertainty_h: float,
+) -> tuple[float, float] | None:
+    uncertainty = _nonnegative_float(event_time_uncertainty_h, field="event_time_uncertainty_h")
+    if response_basis == "post_window":
+        if pre_window_duration_h is not None:
+            raise ValueError("post_window diagnostics must not declare pre_window_duration_h")
+        return None
+    duration = _nonnegative_float(pre_window_duration_h, field="pre_window_duration_h")
+    if duration <= 0.0:
+        raise ValueError("post_minus_pre diagnostics require positive pre_window_duration_h")
+    end = -uncertainty
+    return (end - duration, end)
+
+
+def _component_bools(row: pd.Series, *, suffix: str) -> tuple[bool, ...]:
+    values: list[bool] = []
+    for component in COMPONENT_COLUMNS:
+        value = row[f"{component}_{suffix}"]
+        if not isinstance(value, (bool, np.bool_)):
+            raise ValueError(f"four-state event-window diagnostic {component}_{suffix} must be boolean")
+        values.append(bool(value))
+    return tuple(values)
+
+
+def _validate_trace_support(rows: pd.DataFrame, *, design_id: str, signal_kinds: tuple[str, ...]) -> None:
+    for signal_kind in signal_kinds:
+        states = set(rows.loc[rows["signal_kind"].astype(str).eq(signal_kind), "state"].astype(str))
+        if states != set(STATE_ORDER):
+            raise ValueError(
+                f"four-state event-window diagnostic requires {signal_kind!r} traces for design {design_id!r} "
+                f"in states {list(STATE_ORDER)}; found {sorted(states)}"
+            )
+
+
+def _require_columns(frame: pd.DataFrame, required: set[str], *, record: str) -> None:
+    missing = sorted(required - set(frame.columns))
+    if missing:
+        raise ValueError(f"four-state event-window diagnostic {record} record is missing columns: {missing}")
+
+
+def _identifier(value: object, *, field: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"four-state event-window diagnostic {field} must be a non-empty string")
+    return value.strip()
+
+
+def _choice(value: object, *, field: str, choices: set[str] | frozenset[str]) -> str:
+    result = _identifier(value, field=field)
+    if result not in choices:
+        raise ValueError(f"four-state event-window diagnostic {field} must be one of {sorted(choices)}")
+    return result
+
+
+def _positive_int(value: object, *, field: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, (int, np.integer)) or int(value) <= 0:
+        raise ValueError(f"four-state event-window diagnostic {field} must be a positive integer")
+    return int(value)
+
+
+def _nonnegative_float(value: object, *, field: str) -> float:
+    if value is None or isinstance(value, bool):
+        raise ValueError(f"four-state event-window diagnostic {field} must be a non-negative finite number")
+    result = float(value)
+    if not np.isfinite(result) or result < 0.0:
+        raise ValueError(f"four-state event-window diagnostic {field} must be a non-negative finite number")
+    return result
+
+
+def _descriptive_interval_mass(value: object) -> float:
+    result = _nonnegative_float(value, field="descriptive_interval_mass")
+    if not 0.5 < result < 1.0:
+        raise ValueError("four-state event-window diagnostic descriptive_interval_mass must be between 0.5 and 1.0")
+    return result
+
+
+__all__ = ["FourStateEventWindowDiagnostic", "prepare_four_state_event_window_diagnostic"]

reader_workbench/domains/plate_reader/plots/four_state_event_window/diagnostic_components.py

@@ -0,0 +1,149 @@
+"""Render the reduced components of a four-state event-window diagnostic."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import numpy as np
+
+from .diagnostic import FourStateEventWindowDiagnostic
+from .diagnostic_style import BOUND_MARKERS, STATE_COLORS
+from .schema import COMPONENT_COLUMNS
+
+
+def draw_component_panel(
+    axis: Any,
+    *,
+    diagnostic: FourStateEventWindowDiagnostic,
+    axis_labels: Mapping[str, str],
+    reference_label: str,
+) -> None:
+    y = np.arange(len(COMPONENT_COLUMNS))
+    values = np.asarray(diagnostic.component_values)
+    interval_low = np.asarray(diagnostic.component_descriptive_interval_low)
+    interval_high = np.asarray(diagnostic.component_descriptive_interval_high)
+    event_range = np.asarray(diagnostic.component_event_half_range)
+    for index, (component, value) in enumerate(zip(COMPONENT_COLUMNS, values, strict=True)):
+        state = component[1:]
+        color = STATE_COLORS[state]
+        sensitivity = axis.hlines(
+            y[index],
+            value - event_range[index],
+            value + event_range[index],
+            color=color,
+            linewidth=5.0,
+            alpha=0.18,
+            zorder=1,
+        )
+        sensitivity.set_gid("four-state-event-window-component-event-range")
+        interval = axis.hlines(
+            y[index],
+            interval_low[index],
+            interval_high[index],
+            color=color,
+            linewidth=1.4,
+            zorder=2,
+        )
+        interval.set_gid("four-state-event-window-component-descriptive-interval")
+        caps = axis.vlines(
+            [interval_low[index], interval_high[index]],
+            y[index] - 0.09,
+            y[index] + 0.09,
+            color=color,
+            linewidth=1.1,
+            zorder=2,
+        )
+        caps.set_gid("four-state-event-window-component-descriptive-caps")
+        axis.scatter(
+            value,
+            y[index],
+            color=color,
+            marker=BOUND_MARKERS[diagnostic.component_bound_kinds[index]],
+            s=30.0,
+            edgecolor="white",
+            linewidth=0.5,
+            zorder=3,
+        )
+    axis.axvline(0.0, color="#64748b", linewidth=0.9)
+    axis.axhline(3.5, color="#cbd5e1", linewidth=0.8)
+    axis.set_yticks(y, labels=COMPONENT_COLUMNS)
+    axis.invert_yaxis()
+    axis.set_xlabel("Reduced value (log$_2$ units)", labelpad=8)
+    _draw_group_label(axis, start=-0.35, end=3.35, label=f"Response $r_i$\n{axis_labels['response']}")
+    _draw_group_label(
+        axis,
+        start=3.65,
+        end=7.35,
+        label=f"Signal $b_i$\n{axis_labels['magnitude']}\nrelative to {reference_label}",
+    )
+    notes = quality_notes(diagnostic)
+    if notes:
+        axis.text(
+            0.0,
+            -0.16,
+            "Quality flags — " + "; ".join(notes),
+            transform=axis.transAxes,
+            ha="left",
+            va="top",
+            fontsize=10.5,
+            color="#7c2d12",
+            wrap=True,
+        )
+
+
+def _draw_group_label(axis: Any, *, start: float, end: float, label: str) -> None:
+    transform = axis.get_yaxis_transform()
+    (bracket,) = axis.plot(
+        [1.025, 1.055, 1.055, 1.025],
+        [start, start, end, end],
+        color="#8793A1",
+        linewidth=0.9,
+        transform=transform,
+        clip_on=False,
+    )
+    bracket.set_gid("four-state-event-window-component-group")
+    axis.text(
+        1.075,
+        (start + end) / 2.0,
+        label,
+        transform=transform,
+        ha="left",
+        va="center",
+        fontsize=11.5,
+        color="#536273",
+        linespacing=1.15,
+        clip_on=False,
+    )
+
+
+def quality_notes(diagnostic: FourStateEventWindowDiagnostic) -> list[str]:
+    notes: list[str] = []
+    for index, component in enumerate(COMPONENT_COLUMNS):
+        flags: list[str] = []
+        bound = diagnostic.component_bound_kinds[index]
+        if bound != "exact":
+            flags.append(f"{bound} bound")
+        if diagnostic.component_has_policy_clipping[index]:
+            flags.append("policy clipping")
+        if diagnostic.component_has_instrument_overflow[index]:
+            flags.append("instrument overflow")
+        if diagnostic.component_event_has_policy_clipping[index]:
+            flags.append("event-range clipping")
+        if diagnostic.component_event_has_instrument_overflow[index]:
+            flags.append("event-range overflow")
+        if flags:
+            notes.append(f"{component}: {', '.join(flags)}")
+    return notes
+
+
+def has_quality_flags(diagnostic: FourStateEventWindowDiagnostic) -> bool:
+    trace_flags = (
+        diagnostic.traces["value_policy_clipped"].astype(bool)
+        | diagnostic.traces["value_instrument_overflow"].astype(bool)
+        | diagnostic.traces["value_bound_kind"].astype(str).ne("exact")
+    ).any()
+    return bool(trace_flags or quality_notes(diagnostic))
+
+
+__all__ = ["draw_component_panel", "has_quality_flags", "quality_notes"]