reader-workbench 1.0.0__py3-none-any.whl

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

@@ -0,0 +1,308 @@
+"""Render a provenance-aware four-state event-window diagnostic."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from reader_workbench.plotting.style import use_style
+
+from .diagnostic import FourStateEventWindowDiagnostic, prepare_four_state_event_window_diagnostic
+from .diagnostic_components import draw_component_panel, has_quality_flags
+from .diagnostic_style import BOUND_MARKERS, STATE_COLORS, STATE_MARKERS, validated_axis_labels, validated_state_labels
+from .schema import STATE_ORDER
+
+_REFERENCE_COLOR = "#7C8793"
+
+
+def render_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,
+    axis_labels: Mapping[str, str] | None = None,
+    state_labels: Mapping[str, str] | None = None,
+    reference_label: str = "reference",
+    title: str | None = None,
+) -> Any:
+    """Render observed traces, descriptive dispersion, and event sensitivity in one row."""
+
+    diagnostic = prepare_four_state_event_window_diagnostic(
+        traces,
+        designs,
+        source_experiment_id=source_experiment_id,
+        design_id=design_id,
+        reduction_id=reduction_id,
+        pre_window_duration_h=pre_window_duration_h,
+    )
+    with use_style(
+        {
+            "axes_titleweight": "regular",
+            "figure_figsize": (18.5, 6.0),
+            "font_size": 13.0,
+            "axes_labelsize": 13.0,
+            "axes_titlesize": 15.0,
+            "xtick_labelsize": 11.5,
+            "ytick_labelsize": 11.5,
+            "legend_fontsize": 11.5,
+        }
+    ):
+        from matplotlib.figure import Figure  # noqa: PLC0415
+        from matplotlib.lines import Line2D  # noqa: PLC0415
+
+        figure = Figure(
+            figsize=(18.5, 6.0),
+            constrained_layout=True,
+        )
+        axes = figure.subplots(
+            1,
+            4,
+            gridspec_kw={"width_ratios": (1.0, 1.0, 1.0, 0.95)},
+        )
+        figure.set_gid("four-state-event-window-diagnostic")
+        labels = validated_axis_labels(axis_labels)
+        states = validated_state_labels(state_labels)
+        for axis, signal_kind, panel_title in (
+            (axes[0], "growth", "Growth"),
+            (axes[1], "response", "Response"),
+            (axes[2], "magnitude", "Signal vs reference"),
+        ):
+            _draw_trace_panel(axis, diagnostic=diagnostic, signal_kind=signal_kind)
+            axis.set_title(panel_title, pad=12)
+            axis.set_xlabel("Time from event estimate (h)", labelpad=8)
+            axis.set_ylabel(labels[signal_kind], labelpad=8)
+        draw_component_panel(
+            axes[3],
+            diagnostic=diagnostic,
+            axis_labels=labels,
+            reference_label=reference_label,
+        )
+        window_start, window_end = diagnostic.window
+        axes[3].set_title(f"{window_start:g}–{window_end:g} h mean", pad=12)
+        for axis in axes:
+            axis.set_box_aspect(1.0)
+
+        figure.suptitle(
+            title or f"{diagnostic.source_experiment_id} :: {diagnostic.design_id}",
+            fontsize=19.0,
+            fontweight="bold",
+        )
+
+        legend = [
+            Line2D(
+                [0],
+                [0],
+                color=STATE_COLORS[state],
+                marker=STATE_MARKERS[state],
+                linewidth=1.8,
+                label=states[state],
+            )
+            for state in STATE_ORDER
+        ]
+        if diagnostic.reference_design_id != diagnostic.design_id:
+            legend.append(
+                Line2D([0], [0], color=_REFERENCE_COLOR, linestyle="--", linewidth=1.7, label=reference_label)
+            )
+        legend.extend(
+            (
+                Line2D(
+                    [0],
+                    [0],
+                    color="#64748b",
+                    linewidth=5.0,
+                    alpha=0.28,
+                    label="event timing sensitivity",
+                ),
+                Line2D(
+                    [0],
+                    [0],
+                    color="#334155",
+                    linewidth=1.4,
+                    marker="|",
+                    markersize=8.0,
+                    markeredgewidth=1.1,
+                    label=f"{100.0 * diagnostic.descriptive_interval_mass:g}% resampling interval",
+                ),
+            )
+        )
+        if has_quality_flags(diagnostic):
+            legend.append(Line2D([0], [0], color="#7c2d12", marker="x", linestyle="none", label="quality/bound flag"))
+        figure.legend(
+            handles=legend,
+            loc="outside lower center",
+            ncol=min(len(legend), 8),
+            frameon=False,
+            columnspacing=1.5,
+            handletextpad=0.55,
+        )
+    return figure
+
+
+def _draw_trace_panel(axis: Any, *, diagnostic: FourStateEventWindowDiagnostic, signal_kind: str) -> None:
+    rows = diagnostic.traces.loc[diagnostic.traces["signal_kind"].astype(str).eq(signal_kind)].copy()
+    rows["plot_value"] = rows["value"].astype(float)
+    if signal_kind in {"response", "magnitude"}:
+        rows["plot_value"] = np.log2(rows["plot_value"])
+    _draw_time_context(axis, diagnostic=diagnostic, signal_kind=signal_kind)
+    for state in STATE_ORDER:
+        selected = rows.loc[
+            rows["design_id"].astype(str).eq(diagnostic.design_id) & rows["state"].astype(str).eq(state)
+        ]
+        _draw_observed_traces(
+            axis,
+            selected,
+            color=STATE_COLORS[state],
+            marker=STATE_MARKERS[state],
+            linestyle="-",
+            reference=False,
+            observation_stat=diagnostic.observation_stat,
+            interval_mass=diagnostic.descriptive_interval_mass,
+            gid="four-state-event-window-trace",
+        )
+        if signal_kind == "magnitude" and diagnostic.reference_design_id != diagnostic.design_id:
+            reference = rows.loc[
+                rows["design_id"].astype(str).eq(diagnostic.reference_design_id) & rows["state"].astype(str).eq(state)
+            ]
+            _draw_observed_traces(
+                axis,
+                reference,
+                color=_REFERENCE_COLOR,
+                marker=STATE_MARKERS[state],
+                linestyle="--",
+                reference=True,
+                observation_stat=diagnostic.observation_stat,
+                interval_mass=diagnostic.descriptive_interval_mass,
+                gid="four-state-event-window-reference-trace",
+            )
+
+
+def _draw_time_context(axis: Any, *, diagnostic: FourStateEventWindowDiagnostic, signal_kind: str) -> None:
+    uncertainty = diagnostic.event_time_uncertainty_h
+    if uncertainty > 0.0:
+        interval = axis.axvspan(-uncertainty, uncertainty, color="#64748b", alpha=0.10, linewidth=0.0)
+        interval.set_gid("four-state-event-window-event-interval")
+    event = axis.axvline(0.0, color="#64748b", linewidth=0.9)
+    event.set_gid("four-state-event-window-event-estimate")
+    post = axis.axvspan(*diagnostic.window, color="#f0c36e", alpha=0.18, linewidth=0.0)
+    post.set_gid("four-state-event-window-reduction-window")
+    if signal_kind == "response" and diagnostic.pre_window is not None:
+        pre = axis.axvspan(*diagnostic.pre_window, color="#94a3b8", alpha=0.14, linewidth=0.0)
+        pre.set_gid("four-state-event-window-pre-window")
+
+
+def _draw_observed_traces(
+    axis: Any,
+    rows: pd.DataFrame,
+    *,
+    color: str,
+    marker: str,
+    linestyle: str,
+    reference: bool,
+    observation_stat: str,
+    interval_mass: float,
+    gid: str,
+) -> None:
+    traces: list[pd.DataFrame] = []
+    for _, trace in rows.groupby("position", sort=True):
+        trace = trace.sort_values("time_from_event_h", kind="stable")
+        traces.append(trace)
+        flagged = trace.loc[
+            trace["value_policy_clipped"].astype(bool)
+            | trace["value_instrument_overflow"].astype(bool)
+            | trace["value_bound_kind"].astype(str).ne("exact")
+        ]
+        if not flagged.empty:
+            axis.scatter(
+                flagged["time_from_event_h"],
+                flagged["plot_value"],
+                marker="x",
+                s=18.0,
+                color="#7c2d12",
+                zorder=4,
+            )
+    summary = summarize_observed_traces(
+        traces,
+        observation_stat=observation_stat,
+        interval_mass=interval_mass,
+    )
+    if summary is None:
+        raise ValueError("four-state event-window diagnostic requires observed trace points")
+    times, values, interval_low, interval_high = summary
+    band = axis.fill_between(
+        times,
+        interval_low,
+        interval_high,
+        color=color,
+        alpha=0.07 if reference else 0.14,
+        linewidth=0.0,
+        zorder=1,
+    )
+    band.set_gid("four-state-event-window-observation-interval")
+    (line,) = axis.plot(
+        times,
+        values,
+        color=color,
+        linestyle=linestyle,
+        linewidth=1.9 if not reference else 1.15,
+        marker=marker,
+        markersize=4.0 if not reference else 2.7,
+        markeredgecolor="white",
+        markeredgewidth=0.55 if not reference else 0.45,
+        alpha=0.78 if reference else 1.0,
+        markevery=4 if reference else None,
+        zorder=3,
+    )
+    line.set_gid(gid)
+
+
+def summarize_observed_traces(
+    traces: list[pd.DataFrame],
+    *,
+    observation_stat: str,
+    interval_mass: float,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray] | None:
+    if not traces:
+        return None
+    observed = pd.concat(
+        (
+            trace.loc[:, ["time_from_event_h", "plot_value"]].assign(trace_index=index)
+            for index, trace in enumerate(traces)
+        ),
+        ignore_index=True,
+    )
+    observed_by_time = observed.groupby("time_from_event_h", sort=True, observed=True)
+    grouped = observed_by_time["plot_value"]
+    times = grouped.size().index.to_numpy(dtype=float)
+    center = (
+        grouped.mean().to_numpy(dtype=float) if observation_stat == "mean" else grouped.median().to_numpy(dtype=float)
+    )
+    tail = (1.0 - interval_mass) / 2.0
+    interval_low = grouped.quantile(tail).to_numpy(dtype=float)
+    interval_high = grouped.quantile(1.0 - tail).to_numpy(dtype=float)
+    trace_cohorts = observed_by_time["trace_index"].apply(lambda values: frozenset(values.tolist())).tolist()
+    break_indices = [
+        index
+        for index, (previous, current) in enumerate(zip(trace_cohorts, trace_cohorts[1:], strict=False), start=1)
+        if current != previous
+    ]
+    if break_indices:
+        times = np.insert(times, break_indices, np.nan)
+        center = np.insert(center, break_indices, np.nan)
+        interval_low = np.insert(interval_low, break_indices, np.nan)
+        interval_high = np.insert(interval_high, break_indices, np.nan)
+    return times, center, interval_low, interval_high
+
+
+__all__ = [
+    "BOUND_MARKERS",
+    "STATE_COLORS",
+    "STATE_MARKERS",
+    "render_four_state_event_window_diagnostic",
+    "summarize_observed_traces",
+]

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

@@ -0,0 +1,51 @@
+"""Shared visual vocabulary for four-state event-window diagnostics."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+STATE_COLORS = {
+    "00": "#596675",
+    "10": "#4F8C83",
+    "01": "#607CC8",
+    "11": "#C15D6E",
+}
+STATE_MARKERS = {"00": "o", "10": "s", "01": "^", "11": "D"}
+BOUND_MARKERS = {"exact": "o", "lower": ">", "upper": "<", "indeterminate": "X"}
+
+_DEFAULT_AXIS_LABELS = {
+    "growth": "Signal",
+    "response": "log$_2$(response signal)",
+    "magnitude": "log$_2$(magnitude signal)",
+}
+
+
+def validated_axis_labels(axis_labels: Mapping[str, str] | None) -> dict[str, str]:
+    """Validate the three compiler-owned signal labels."""
+
+    labels = dict(_DEFAULT_AXIS_LABELS if axis_labels is None else axis_labels)
+    if set(labels) != set(_DEFAULT_AXIS_LABELS):
+        raise ValueError("four-state event-window diagnostic axis labels must define growth, response, and magnitude")
+    if any(not isinstance(value, str) or not value.strip() for value in labels.values()):
+        raise ValueError("four-state event-window diagnostic axis labels must be non-empty strings")
+    return {key: value.strip() for key, value in labels.items()}
+
+
+def validated_state_labels(state_labels: Mapping[str, str] | None) -> dict[str, str]:
+    """Validate one display label for every canonical state."""
+
+    labels = {state: state for state in STATE_MARKERS} if state_labels is None else dict(state_labels)
+    if set(labels) != set(STATE_MARKERS):
+        raise ValueError("four-state event-window diagnostic state labels must define 00, 10, 01, and 11")
+    if any(not isinstance(value, str) or not value.strip() for value in labels.values()):
+        raise ValueError("four-state event-window diagnostic state labels must be non-empty strings")
+    return {key: value.strip() for key, value in labels.items()}
+
+
+__all__ = [
+    "BOUND_MARKERS",
+    "STATE_COLORS",
+    "STATE_MARKERS",
+    "validated_axis_labels",
+    "validated_state_labels",
+]

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

@@ -0,0 +1,8 @@
+"""Shared four-state event-window plot coordinates."""
+
+STATE_ORDER = ("00", "10", "01", "11")
+RESPONSE_COLUMNS = tuple(f"r{state}" for state in STATE_ORDER)
+MAGNITUDE_COLUMNS = tuple(f"b{state}" for state in STATE_ORDER)
+COMPONENT_COLUMNS = (*RESPONSE_COLUMNS, *MAGNITUDE_COLUMNS)
+
+__all__ = ["COMPONENT_COLUMNS", "MAGNITUDE_COLUMNS", "RESPONSE_COLUMNS", "STATE_ORDER"]

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

@@ -0,0 +1,140 @@
+"""Selection and rendering for the canonical four-state event-window summary."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from reader_workbench.plotting.style import use_style
+
+from .schema import COMPONENT_COLUMNS, MAGNITUDE_COLUMNS, RESPONSE_COLUMNS, STATE_ORDER
+
+
+@dataclass(frozen=True)
+class FourStateEventWindowSummaryMatrix:
+    """Ordered labels and values consumed by the summary heatmap."""
+
+    row_labels: tuple[str, ...]
+    component_labels: tuple[str, ...]
+    values: np.ndarray
+
+
+def four_state_event_window_summary_matrix(
+    designs: pd.DataFrame,
+    *,
+    primary_reduction_id: str,
+    experiment_ids: list[str] | tuple[str, ...] | None = None,
+    design_ids: list[str] | tuple[str, ...] | None = None,
+    maximum_rows: int = 64,
+) -> FourStateEventWindowSummaryMatrix:
+    """Select one reduction's non-reference designs and validate plot values."""
+
+    experiment_selection = _identity_filter(experiment_ids, label="experiment_ids")
+    design_selection = _identity_filter(design_ids, label="design_ids")
+    if isinstance(maximum_rows, bool) or not isinstance(maximum_rows, int) or maximum_rows < 1:
+        raise ValueError("four-state event-window summary maximum_rows must be a positive integer")
+    selected = designs.loc[
+        designs["reduction_id"].astype(str).eq(primary_reduction_id) & ~designs["is_reference"].astype(bool)
+    ].copy()
+    if experiment_selection is not None:
+        selected = selected.loc[selected["experiment_id"].astype(str).isin(experiment_selection)]
+    if design_selection is not None:
+        selected = selected.loc[selected["design_id"].astype(str).isin(design_selection)]
+    if selected.empty:
+        raise ValueError(
+            f"four-state event-window plot has no non-reference rows for reduction {primary_reduction_id!r} "
+            "under the configured experiment_ids/design_ids filters"
+        )
+    if len(selected) > maximum_rows:
+        raise ValueError(
+            f"four-state event-window summary selected {len(selected)} rows, exceeding maximum_rows={maximum_rows}; "
+            "configure experiment_ids/design_ids or raise maximum_rows explicitly"
+        )
+
+    selected = selected.sort_values(["experiment_id", "design_id"], kind="stable")
+    row_labels = tuple(selected["experiment_id"].astype(str) + " :: " + selected["design_id"].astype(str))
+    values = selected.loc[:, COMPONENT_COLUMNS].to_numpy(dtype=float)
+    if not np.isfinite(values).all():
+        raise ValueError("four-state event-window summary requires finite component values")
+
+    return FourStateEventWindowSummaryMatrix(
+        row_labels=row_labels,
+        component_labels=COMPONENT_COLUMNS,
+        values=values,
+    )
+
+
+def render_four_state_event_window_summary(
+    designs: pd.DataFrame,
+    *,
+    primary_reduction_id: str,
+    title: str,
+    experiment_ids: list[str] | tuple[str, ...] | None = None,
+    design_ids: list[str] | tuple[str, ...] | None = None,
+    maximum_rows: int = 64,
+):
+    """Render the selected response and anchored-magnitude components."""
+
+    summary = four_state_event_window_summary_matrix(
+        designs,
+        primary_reduction_id=primary_reduction_id,
+        experiment_ids=experiment_ids,
+        design_ids=design_ids,
+        maximum_rows=maximum_rows,
+    )
+    with use_style(
+        {
+            "axes_grid": False,
+            "figure_figsize": (11.0, max(4.5, 0.32 * len(summary.row_labels) + 2.0)),
+        }
+    ):
+        import matplotlib.pyplot as plt  # noqa: PLC0415
+        from matplotlib.colors import TwoSlopeNorm  # noqa: PLC0415
+
+        figure, axes = plt.subplots(1, 2, sharey=True, constrained_layout=True)
+        response_values = summary.values[:, : len(RESPONSE_COLUMNS)]
+        magnitude_values = summary.values[:, len(RESPONSE_COLUMNS) :]
+        families = (
+            (axes[0], "Response", "response", response_values),
+            (axes[1], "Anchored magnitude", "anchored magnitude", magnitude_values),
+        )
+        for axis, panel_title, colorbar_label, values in families:
+            limit = max(float(np.max(np.abs(values))), np.finfo(float).eps)
+            image = axis.imshow(
+                values,
+                aspect="auto",
+                cmap="coolwarm",
+                norm=TwoSlopeNorm(vmin=-limit, vcenter=0.0, vmax=limit),
+            )
+            axis.set_xticks(range(len(STATE_ORDER)), labels=STATE_ORDER)
+            axis.set_title(panel_title)
+            axis.set_xlabel("state")
+            figure.colorbar(image, ax=axis, label=colorbar_label, shrink=0.8)
+        axes[0].set_yticks(range(len(summary.row_labels)), labels=summary.row_labels)
+        axes[0].set_ylabel("source :: design")
+        figure.suptitle(title)
+    return figure
+
+
+def _identity_filter(values: list[str] | tuple[str, ...] | None, *, label: str) -> tuple[str, ...] | None:
+    if values is None:
+        return None
+    normalized = tuple(str(value).strip() for value in values)
+    if not normalized or any(not value for value in normalized):
+        raise ValueError(f"four-state event-window summary {label} must contain non-empty identities")
+    if len(normalized) != len(set(normalized)):
+        raise ValueError(f"four-state event-window summary {label} must not contain duplicates")
+    return normalized
+
+
+__all__ = [
+    "COMPONENT_COLUMNS",
+    "MAGNITUDE_COLUMNS",
+    "RESPONSE_COLUMNS",
+    "FourStateEventWindowSummaryMatrix",
+    "STATE_ORDER",
+    "render_four_state_event_window_summary",
+    "four_state_event_window_summary_matrix",
+]

reader_workbench/domains/plate_reader/plots/grouping.py

@@ -0,0 +1,53 @@
+"""Plate-reader plot grouping helpers."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from typing import Literal
+
+from reader_workbench.domains.plate_reader.ordering import order_levels
+
+GroupMatch = Literal["exact", "contains", "startswith", "endswith", "regex"]
+
+
+def _match_value(val: str, needle: str, mode: GroupMatch) -> bool:
+    v = str(val)
+    n = str(needle)
+    if mode == "exact":
+        return v == n
+    if mode == "contains":
+        return n in v
+    if mode == "startswith":
+        return v.startswith(n)
+    if mode == "endswith":
+        return v.endswith(n)
+    if mode == "regex":
+        return re.search(n, v) is not None
+    raise ValueError(f"Unknown group_match: {mode}")
+
+
+def resolve_groups(
+    universe: Iterable[str],
+    groups: list[dict[str, list[str]]] | None,
+    *,
+    match: GroupMatch,
+) -> list[tuple[str, list[str]]]:
+    values = list(map(str, universe))
+    if not groups:
+        return [("all", values)]
+    resolved: list[tuple[str, list[str]]] = []
+    for item in groups:
+        if not isinstance(item, dict) or len(item) != 1:
+            raise ValueError("groups must be list of single-key dicts")
+        label, needles = next(iter(item.items()))
+        members = [v for v in values if any(_match_value(v, n, match) for n in needles)]
+        resolved.append((str(label), members))
+    return resolved
+
+
+def ordered_groups(universe: Iterable[str]) -> list[str]:
+    return order_levels(list(map(str, universe)))
+
+
+__all__ = ["GroupMatch", "ordered_groups", "resolve_groups"]

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

@@ -0,0 +1,12 @@
+from .snapshot import draw_snapshot_panel
+from .snapshot_data import SnapshotSelection, select_snapshot_rows, summarize_snapshot_values
+from .time_series import draw_time_series_panel, marker_map_for_levels
+
+__all__ = [
+    "SnapshotSelection",
+    "draw_snapshot_panel",
+    "draw_time_series_panel",
+    "marker_map_for_levels",
+    "select_snapshot_rows",
+    "summarize_snapshot_values",
+]