reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/domains/plate_reader/plots/single_reporter_diagnostic_render.py

@@ -0,0 +1,300 @@
+"""Static rendering for the single-reporter diagnostic 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 matplotlib.lines import Line2D
+
+from reader_workbench.plotting.style import use_style
+
+from .single_reporter_diagnostic import SingleReporterDiagnosticData
+
+_DEFAULT_COLORS = ("#334155", "#0f766e", "#2563eb", "#be123c")
+_MARKERS = ("o", "s", "^", "D", "P", "X", "v", "<", ">")
+
+
+def render_single_reporter_diagnostic(
+    data: SingleReporterDiagnosticData,
+    *,
+    colors: Sequence[str] | None = None,
+    figsize: tuple[float, float] = (14.0, 3.7),
+    axis_label_size: float = 9.5,
+    tick_label_size: float = 8.5,
+    legend_fontsize: float = 8.5,
+    line_width: float = 1.7,
+    point_size: float = 28.0,
+    condition_tick_rotation: float = 20.0,
+) -> Figure:
+    """Render normalizer, reporter, ratio, and reduced-condition panels."""
+
+    order = list(data.condition_order)
+    palette = list(colors or _DEFAULT_COLORS)
+    if not palette:
+        raise ValueError("single_reporter_diagnostic: colors must contain at least one color")
+    color_map = {condition: palette[index % len(palette)] for index, condition in enumerate(order)}
+    marker_map = {condition: _MARKERS[index % len(_MARKERS)] for index, condition in enumerate(order)}
+
+    with use_style(
+        rc={
+            "axes_titleweight": "regular",
+            "axes_titlesize": 10.5,
+            "axes_labelsize": axis_label_size,
+            "font_size": 9.5,
+            "legend_fontsize": legend_fontsize,
+            "legend_title_fontsize": legend_fontsize,
+            "xtick_labelsize": tick_label_size,
+            "ytick_labelsize": tick_label_size,
+        },
+        color_cycle=palette,
+    ):
+        figure, axes = plt.subplots(1, 4, figsize=figsize, constrained_layout=True)
+        figure.set_gid("single-reporter-diagnostic")
+        for axis, channel in zip(
+            axes[:3],
+            (data.normalizer_channel, data.reporter_channel, data.ratio_channel),
+            strict=True,
+        ):
+            _draw_kinetics_panel(
+                axis,
+                data=data,
+                channel=channel,
+                color_map=color_map,
+                marker_map=marker_map,
+                line_width=line_width,
+                point_size=point_size,
+            )
+            axis.set_title(f"{channel} kinetics")
+            axis.set_xlabel("Time (h)")
+            axis.set_ylabel(channel)
+            axis.set_box_aspect(1.0)
+
+        qc_axis = _draw_reduction_panel(
+            axes[3],
+            data=data,
+            color_map=color_map,
+            marker_map=marker_map,
+            point_size=point_size,
+            condition_tick_rotation=condition_tick_rotation,
+        )
+        axes[3].set_box_aspect(1.0)
+        qc_axis.set_box_aspect(1.0)
+
+        condition_handles = [
+            Line2D(
+                [0],
+                [0],
+                color=color_map[condition],
+                marker=marker_map[condition],
+                linestyle="-",
+                linewidth=line_width,
+                markersize=max(4.0, point_size**0.5),
+                label=condition,
+            )
+            for condition in order
+        ]
+        qc_handle = Line2D(
+            [0],
+            [0],
+            color="#64748b",
+            marker="x",
+            linestyle="--",
+            linewidth=1.1,
+            markersize=max(4.0, point_size**0.5),
+            label=f"{data.normalizer_channel} QC (right axis)",
+        )
+        condition_label = _column_label(data.condition_column)
+        figure.legend(
+            handles=[*condition_handles, qc_handle],
+            loc="outside lower center",
+            ncols=max(1, min(len(condition_handles) + 1, 5)),
+            title=condition_label,
+        )
+        figure.suptitle(f"{data.group_label}\n{data.selection.label}", fontweight="normal")
+        return figure
+
+
+def _draw_kinetics_panel(
+    axis,
+    *,
+    data: SingleReporterDiagnosticData,
+    channel: str,
+    color_map: dict[str, str],
+    marker_map: dict[str, str],
+    line_width: float,
+    point_size: float,
+) -> None:
+    channel_rows = data.kinetics[data.kinetics["channel"].astype(str) == str(channel)]
+    if channel_rows.empty:
+        raise ValueError(f"single_reporter_diagnostic: no kinetics rows for {channel!r}")
+
+    for condition in data.condition_order:
+        selected = channel_rows[channel_rows["__condition"].astype(str) == condition]
+        if selected.empty:
+            continue
+        grouped = selected.groupby(["__segment", data.time_column], sort=True, dropna=False)["value"]
+        summary = grouped.agg(
+            center=lambda values: _center(
+                values,
+                statistic=data.observation_aggregation.across_unit_statistic,
+            ),
+            lower=lambda values: float(np.quantile(np.asarray(values, dtype=float), 0.25)),
+            upper=lambda values: float(np.quantile(np.asarray(values, dtype=float), 0.75)),
+        ).reset_index()
+        for _, segment in summary.groupby("__segment", sort=False):
+            segment = segment.sort_values(data.time_column)
+            x = segment[data.time_column].to_numpy(dtype=float)
+            center = segment["center"].to_numpy(dtype=float)
+            color = color_map[condition]
+            axis.fill_between(
+                x,
+                segment["lower"].to_numpy(dtype=float),
+                segment["upper"].to_numpy(dtype=float),
+                color=color,
+                alpha=0.14,
+                linewidth=0.0,
+            )
+            axis.plot(x, center, color=color, linewidth=line_width)
+            marker_stride = max(1, len(x) // 12)
+            axis.scatter(
+                x[::marker_stride],
+                center[::marker_stride],
+                color=color,
+                marker=marker_map[condition],
+                s=point_size * 0.55,
+                linewidths=0.0,
+                zorder=3,
+            )
+    _mark_selection(axis, data=data)
+
+
+def _mark_selection(axis, *, data: SingleReporterDiagnosticData) -> None:
+    if data.selection.endpoint_time_h is not None:
+        line = axis.axvline(
+            data.selection.endpoint_time_h,
+            color="#111827",
+            linewidth=1.0,
+            linestyle=(0, (5, 3)),
+            zorder=0.8,
+        )
+        line.set_gid("single-reporter-endpoint")
+        return
+    assert data.selection.window_h is not None
+    lower, upper = data.selection.window_h
+    patch = axis.axvspan(lower, upper, color="#d8b365", alpha=0.18, linewidth=0.0, zorder=0.5)
+    patch.set_gid("single-reporter-window")
+
+
+def _draw_reduction_panel(
+    axis,
+    *,
+    data: SingleReporterDiagnosticData,
+    color_map: dict[str, str],
+    marker_map: dict[str, str],
+    point_size: float,
+    condition_tick_rotation: float,
+):
+    qc_axis = axis.twinx()
+    qc_axis.set_gid("single-reporter-normalizer-qc")
+    qc_axis.grid(False)
+    qc_axis.spines["right"].set_visible(True)
+    qc_axis.spines["right"].set_color("#64748b")
+    qc_axis.tick_params(axis="y", colors="#64748b")
+
+    for index, condition in enumerate(data.condition_order):
+        ratio = data.reduced_ratio[data.reduced_ratio["__condition"].astype(str) == condition]
+        normalizer = data.reduced_normalizer[data.reduced_normalizer["__condition"].astype(str) == condition]
+        ratio_values = ratio["value"].to_numpy(dtype=float)
+        normalizer_values = normalizer["value"].to_numpy(dtype=float)
+        ratio_offsets = _offsets(len(ratio_values), center=-0.07)
+        normalizer_offsets = _offsets(len(normalizer_values), center=0.07)
+        color = color_map[condition]
+        axis.scatter(
+            index + ratio_offsets,
+            ratio_values,
+            s=point_size,
+            facecolors="white",
+            edgecolors=color,
+            marker=marker_map[condition],
+            linewidths=1.1,
+            zorder=3,
+        )
+        ratio_center = _center(
+            ratio_values,
+            statistic=data.observation_aggregation.across_unit_statistic,
+        )
+        ratio_line = axis.hlines(ratio_center, index - 0.22, index + 0.02, color=color, linewidth=2.4, zorder=4)
+        ratio_line.set_gid("single-reporter-ratio-center")
+
+        qc_axis.scatter(
+            index + normalizer_offsets,
+            normalizer_values,
+            s=point_size * 0.9,
+            color="#64748b",
+            marker="x",
+            linewidths=1.1,
+            zorder=3,
+        )
+        normalizer_center = _center(
+            normalizer_values,
+            statistic=data.observation_aggregation.across_unit_statistic,
+        )
+        qc_line = qc_axis.hlines(
+            normalizer_center,
+            index + 0.02,
+            index + 0.22,
+            color="#64748b",
+            linewidth=1.5,
+            linestyle="--",
+            zorder=4,
+        )
+        qc_line.set_gid("single-reporter-normalizer-center")
+
+    unit_label = (
+        "Declared replicate units" if data.unit_role == "declared_replicate" else "Observation units (not replicates)"
+    )
+    axis.set_title(f"{data.ratio_channel} by condition\n{unit_label}")
+    axis.set_xlabel(_column_label(data.condition_column))
+    value_space = data.selection.temporal_reduction.output_space
+    value_suffix = "" if value_space == "linear" else " (log2)"
+    axis.set_ylabel(f"Reduced {data.ratio_channel}{value_suffix}")
+    qc_axis.set_ylabel(f"Reduced {data.normalizer_channel}{value_suffix} (QC only)", color="#64748b")
+    axis.set_xticks(
+        range(len(data.condition_order)),
+        data.condition_order,
+        rotation=condition_tick_rotation,
+        ha="right" if condition_tick_rotation else "center",
+    )
+    axis.set_xlim(-0.45, max(0.55, len(data.condition_order) - 0.55))
+    return qc_axis
+
+
+def _offsets(size: int, *, center: float) -> np.ndarray:
+    if size <= 1:
+        return np.asarray([center] if size else [], dtype=float)
+    return np.linspace(center - 0.06, center + 0.06, size)
+
+
+def _column_label(column: str) -> str:
+    """Render configured semantic columns without storage-only alias suffixes."""
+
+    normalized = str(column).strip()
+    if normalized.endswith("_alias"):
+        normalized = normalized.removesuffix("_alias")
+    return normalized.replace("_", " ").capitalize()
+
+
+def _center(values, *, statistic: str) -> float:
+    finite = np.asarray(values, dtype=float)
+    finite = finite[np.isfinite(finite)]
+    if finite.size == 0:
+        raise ValueError("single_reporter_diagnostic: reduction contains no finite values")
+    if statistic == "mean":
+        return float(finite.mean())
+    return float(np.median(finite))
+
+
+__all__ = ["render_single_reporter_diagnostic"]

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

@@ -0,0 +1,315 @@
+from __future__ import annotations
+
+import logging
+from contextlib import suppress
+from typing import Literal
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+
+from reader_workbench.plotting.sinks import PlotFigure
+from reader_workbench.plotting.style import PaletteBook, use_style
+
+from ...ordering import order_levels
+from ..common import alias_column, best_subplot_grid, colors_for, plot_figure, require_columns, warn_if_empty
+from ..grouping import GroupMatch
+from ..panels import draw_snapshot_panel, select_snapshot_rows, summarize_snapshot_values
+from .planning import build_figure_groups, compute_shared_ylim, resolve_panel_configuration
+
+_PanelBy = Literal["channel", "x", "group"]
+_FileBy = Literal["auto", "group", "channel", "x"]
+
+
+def _figure_stub(
+    *,
+    filename: str | None,
+    panel_by: _PanelBy,
+    group_col: str | None,
+    fig_label: str,
+    members: list[str | None],
+    selected_channel: str | None,
+    multiple_files: bool,
+) -> str:
+    if filename:
+        if not multiple_files:
+            return filename
+        suffix_parts: list[str] = []
+        if panel_by == "group" and selected_channel is not None:
+            suffix_parts.append(f"channel={selected_channel}")
+        elif panel_by == "channel":
+            key = members[0] if group_col and members and members[0] is not None else fig_label
+            suffix_parts.append(f"group={key}")
+        else:
+            suffix_parts.append(f"panel={fig_label}")
+        return f"{filename}__{'__'.join(suffix_parts)}"
+    if panel_by == "group":
+        return f"snap__grp__{selected_channel}"
+    if panel_by == "channel":
+        key = members[0] if group_col and members and members[0] is not None else fig_label
+        return f"snap__ch__{key}"
+    return f"snap__x__{selected_channel}__{fig_label}"
+
+
+def plot_snapshot_barplot(
+    *,
+    df: pd.DataFrame,
+    x: str,
+    y: list[str] | str,
+    hue: str | None,
+    group_on: str | None,
+    pool_sets: list[dict[str, list[str]]] | None,
+    time: float,
+    pool_match: GroupMatch = "exact",
+    fig_kwargs: dict | None = None,
+    filename: str | None = None,
+    palette_book: PaletteBook | None = None,
+    agg: str = "mean",
+    dispersion: str = "sd",
+    time_tolerance: float = 0.51,
+    panel_by: _PanelBy = "channel",
+    channel_select: str | None = None,
+    file_by: _FileBy = "auto",
+    show_legend: bool = False,
+    legend_loc: str = "upper right",
+) -> list[PlotFigure]:
+    fig_kwargs = fig_kwargs or {}
+
+    if agg not in {"mean", "median"}:
+        raise ValueError("agg must be 'mean' or 'median'")
+    if dispersion not in {"sd", "iqr", "none"}:
+        raise ValueError("dispersion must be 'sd', 'iqr', or 'none'")
+    if file_by not in {"auto", "channel"}:
+        raise ValueError("snapshot_barplot: file_by supports only 'auto' or 'channel'")
+
+    x_col = alias_column(df, x)
+    hue_col = alias_column(df, hue) if hue else None
+    group_col = alias_column(df, group_on) if group_on else None
+    y_list = [y] if isinstance(y, str) else list(y)
+    if panel_by == "channel" and channel_select:
+        y_list = [channel_select]
+
+    required = ["time", "channel", "value", "position", x_col]
+    if hue_col:
+        required.append(hue_col)
+    if group_col:
+        required.append(group_col)
+    require_columns(df, required, where="snapshot_barplot")
+
+    work = df.copy()
+    work["value"] = pd.to_numeric(work["value"], errors="coerce")
+
+    if panel_by == "channel":
+        available = sorted(work["channel"].astype(str).unique().tolist())
+        missing = [str(channel) for channel in y_list if str(channel) not in available]
+        if missing:
+            raise ValueError(f"snapshot_barplot: requested channels not found: {missing}. Available: {available}")
+        work = work[work["channel"].astype(str).isin([str(channel) for channel in y_list])].copy()
+    if warn_if_empty(work, where="snapshot_barplot", detail="after channel filter"):
+        return []
+
+    if panel_by in {"x", "group"} and not channel_select:
+        raise ValueError("snapshot_barplot: channel_select is required when panel_by != 'channel'")
+    if channel_select and panel_by in {"x", "group"}:
+        available = sorted(work["channel"].astype(str).unique().tolist())
+        if str(channel_select) not in available:
+            raise ValueError(f"snapshot_barplot: channel_select {channel_select!r} not in data. Available: {available}")
+
+    selected_channel_default = None
+    if panel_by in {"x", "group"}:
+        selected_channel_default = str(
+            channel_select if channel_select else (y if isinstance(y, str) else (y_list[0] if y_list else None))
+        )
+        if not selected_channel_default:
+            raise ValueError(
+                f"snapshot_barplot: panel_by={panel_by!r} requires an explicit channel via channel_select or y."
+            )
+
+    key_cols = [column for column in [group_col, x_col, hue_col, "channel", "position"] if column]
+    target_channels = list(y_list) if panel_by == "channel" else [selected_channel_default]
+    selections = [
+        select_snapshot_rows(
+            df=work,
+            target_time=float(time),
+            keys=key_cols,
+            channel=str(channel),
+            tolerance=float(time_tolerance),
+        )
+        for channel in target_channels
+    ]
+    snapped_parts = [selection.rows for selection in selections if not selection.rows.empty]
+    if not snapped_parts:
+        logging.getLogger("reader").info(
+            "[warn]snapshot_barplot[/warn] • no rows available at any time — skipping figure"
+        )
+        return []
+    fallback_notes = [selection for selection in selections if selection.fell_back and not selection.rows.empty]
+    if fallback_notes:
+        preview = "; ".join(
+            f"{target_channels[idx]}: times={selection.fallback_times_preview} Δ≈{float(selection.fallback_delta or 0.0):.2f} h"
+            for idx, selection in enumerate(selections)
+            if selection.fell_back and not selection.rows.empty
+        )
+        logging.getLogger("reader").info(
+            "[warn]snapshot_barplot[/warn] • requested t=%.2f h; no rows within ±%.2f h — "
+            "using nearest available per key (%s)",
+            float(time),
+            float(time_tolerance),
+            preview,
+        )
+    snapped = pd.concat(snapped_parts, ignore_index=True)
+    snapped["value"] = pd.to_numeric(snapped["value"], errors="coerce")
+    times_used = pd.to_numeric(snapped["time"], errors="coerce").dropna()
+    t_used = float(times_used.median()) if not times_used.empty else float(time)
+
+    if group_col:
+        mask = snapped[group_col].notna() & (
+            ~snapped[group_col].astype(str).str.strip().str.lower().isin({"none", "nan", ""})
+        )
+        snapped = snapped.loc[mask].copy()
+        if snapped.empty:
+            return []
+
+    base_group_cols = [column for column in [group_col, x_col, hue_col, "channel"] if column]
+    seen_cols: set[str] = set()
+    base_group_cols = [column for column in base_group_cols if not (column in seen_cols or seen_cols.add(column))]
+    stats = summarize_snapshot_values(df=snapped, group_cols=base_group_cols, dispersion=dispersion)
+
+    fig_groups = build_figure_groups(
+        stats=stats,
+        group_col=group_col,
+        panel_by=panel_by,
+        pool_sets=pool_sets,
+        pool_match=pool_match,
+    )
+
+    iterate_channels = panel_by == "group" and file_by == "channel"
+    channels_for_files: list[str | None] = (
+        (y_list if iterate_channels else [None]) if y_list else ([None] if not iterate_channels else [])
+    )
+    if iterate_channels and not channels_for_files:
+        return []
+
+    figures: list[PlotFigure] = []
+    for fig_label, members in fig_groups:
+        for ch_for_file in channels_for_files:
+            panels, selected_channel = resolve_panel_configuration(
+                panel_by=panel_by,
+                members=members,
+                y_list=y_list,
+                group_col=group_col,
+                channel_select=channel_select,
+                selected_channel_default=selected_channel_default,
+                ch_for_file=ch_for_file,
+                stats=stats,
+                x_col=x_col,
+            )
+            rows, cols = best_subplot_grid(len(panels))
+            hue_levels_union = order_levels(stats[hue_col].astype(str).unique().tolist()) if hue_col else ["_single"]
+            colors = colors_for(max(1, len(hue_levels_union)), palette_book)
+            color_map = {level: colors[index % len(colors)] for index, level in enumerate(hue_levels_union)}
+
+            with use_style(rc=fig_kwargs.get("rc"), color_cycle=colors):
+                fig, axes = plt.subplots(rows, cols, figsize=(cols * 5, rows * 5), constrained_layout=True)
+                axes = np.atleast_1d(axes).ravel()
+                rasterize_zorder = fig_kwargs.get("rasterize_zorder", None)
+                if rasterize_zorder is not None:
+                    for ax in axes:
+                        ax.set_rasterization_zorder(float(rasterize_zorder))
+
+                if panel_by == "channel" and group_col and members and members[0] is not None:
+                    fig.suptitle(f"{members[0]} • t={t_used:.2f} h", y=float(fig_kwargs.get("suptitle_y", 1.04)))
+                elif panel_by == "group":
+                    fig.suptitle(f"{selected_channel} • t={t_used:.2f} h", y=float(fig_kwargs.get("suptitle_y", 1.04)))
+                else:
+                    fig.suptitle(f"{fig_label} • t={t_used:.2f} h", y=float(fig_kwargs.get("suptitle_y", 1.04)))
+
+                y_lo_glob, y_hi_glob = (
+                    compute_shared_ylim(
+                        stats=stats,
+                        snapped=snapped,
+                        panels=panels,
+                        panel_by=panel_by,
+                        selected_channel=str(selected_channel),
+                        group_col=group_col,
+                        x_col=x_col,
+                        agg=agg,
+                        dispersion=dispersion,
+                    )
+                    if selected_channel is not None
+                    else (None, None)
+                )
+
+                for ax_idx, panel in enumerate(panels):
+                    ax = axes[ax_idx]
+                    if panel_by == "channel":
+                        gval = members[0] if (group_col and members and members[0] is not None) else None
+                        sbar = stats[stats["channel"].astype(str) == str(panel)].copy()
+                        srep = snapped[snapped["channel"].astype(str) == str(panel)].copy()
+                        if gval is not None:
+                            sbar = sbar[sbar[group_col].astype(str) == str(gval)]
+                            srep = srep[srep[group_col].astype(str) == str(gval)]
+                        channel_key = str(panel)
+                    elif panel_by == "group":
+                        sbar = stats[
+                            (stats["channel"].astype(str) == str(selected_channel))
+                            & (stats[group_col].astype(str) == str(panel))
+                        ].copy()
+                        srep = snapped[
+                            (snapped["channel"].astype(str) == str(selected_channel))
+                            & (snapped[group_col].astype(str) == str(panel))
+                        ].copy()
+                        channel_key = str(selected_channel)
+                    else:
+                        sbar = stats[
+                            (stats["channel"].astype(str) == str(selected_channel))
+                            & (stats[x_col].astype(str) == str(panel))
+                        ].copy()
+                        srep = snapped[
+                            (snapped["channel"].astype(str) == str(selected_channel))
+                            & (snapped[x_col].astype(str) == str(panel))
+                        ].copy()
+                        channel_key = str(selected_channel)
+
+                    if sbar.empty:
+                        ax.set_visible(False)
+                        continue
+
+                    title = str(panel) if panel_by == "group" else None
+                    draw_snapshot_panel(
+                        ax,
+                        snapped=srep,
+                        stats=sbar,
+                        x_col=x_col,
+                        hue_col=hue_col,
+                        agg=agg,
+                        dispersion=dispersion,
+                        palette_book=palette_book,
+                        show_legend=show_legend,
+                        legend_loc=legend_loc,
+                        title=title,
+                        ylabel=str(channel_key if panel_by != "channel" else panel),
+                        color_map=(color_map if hue_col else None),
+                    )
+                    with suppress(Exception):
+                        ax.set_box_aspect(1.0)
+
+                for index in range(len(panels), len(axes)):
+                    axes[index].set_visible(False)
+
+                if y_hi_glob is not None:
+                    for axis in axes[: len(panels)]:
+                        if axis.get_visible():
+                            axis.set_ylim(y_lo_glob if y_lo_glob is not None else axis.get_ylim()[0], y_hi_glob)
+
+                stub = _figure_stub(
+                    filename=filename,
+                    panel_by=panel_by,
+                    group_col=group_col,
+                    fig_label=str(fig_label),
+                    members=members,
+                    selected_channel=str(selected_channel) if selected_channel is not None else None,
+                    multiple_files=len(fig_groups) * len(channels_for_files) > 1,
+                )
+                figures.append(plot_figure(fig=fig, filename=stub, fig_kwargs=fig_kwargs))
+    return figures