reader-workbench 1.0.0__py3-none-any.whl

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

@@ -0,0 +1,161 @@
+"""Shared snapshot selection and drawing primitives."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from reader_workbench.domains.plate_reader.ordering import order_levels
+from reader_workbench.domains.plate_reader.plots.common import colors_for
+from reader_workbench.plotting.style import PaletteBook
+
+
+def draw_snapshot_panel(
+    ax,
+    *,
+    snapped: pd.DataFrame,
+    stats: pd.DataFrame,
+    x_col: str,
+    hue_col: str | None,
+    agg: str,
+    dispersion: str,
+    palette_book: PaletteBook | None,
+    show_legend: bool,
+    legend_loc: str,
+    title: str | None,
+    ylabel: str,
+    color_map: dict[str, str] | None = None,
+    x_color_map: dict[str, str] | None = None,
+    x_order: list[str] | None = None,
+    hue_order: list[str] | None = None,
+    tick_rotation: float = 45.0,
+    axis_label_size: float | None = None,
+    tick_label_size: float | None = None,
+    legend_fontsize: float | None = None,
+    observation_seed: int = 0,
+) -> None:
+    x_levels = stats[x_col].astype(str).unique().tolist()
+    resolved_x_order = [str(value) for value in x_order] if x_order is not None else order_levels(x_levels)
+    observed_x = set(map(str, x_levels))
+    missing_x = [value for value in resolved_x_order if value not in observed_x]
+    omitted_x = [value for value in observed_x if value not in resolved_x_order]
+    if missing_x:
+        raise ValueError(f"snapshot: x order includes missing label(s): {missing_x}")
+    if omitted_x:
+        raise ValueError(f"snapshot: x order omits observed label(s): {sorted(omitted_x)}")
+    if len(set(resolved_x_order)) != len(resolved_x_order):
+        raise ValueError("snapshot: x order contains duplicate labels")
+    observed_hue_levels = order_levels(stats[hue_col].astype(str).unique().tolist()) if hue_col else ["_single"]
+    hue_levels = [str(value) for value in hue_order] if hue_col and hue_order is not None else observed_hue_levels
+    observed_hue = set(observed_hue_levels)
+    missing_hue = [value for value in hue_levels if value not in observed_hue]
+    omitted_hue = [value for value in observed_hue if value not in hue_levels]
+    if missing_hue:
+        raise ValueError(f"snapshot: hue order includes missing label(s): {missing_hue}")
+    if omitted_hue:
+        raise ValueError(f"snapshot: hue order omits observed label(s): {sorted(omitted_hue)}")
+    if len(set(hue_levels)) != len(hue_levels):
+        raise ValueError("snapshot: hue order contains duplicate labels")
+    if color_map is None:
+        if hue_col:
+            colors = colors_for(len(hue_levels), palette_book)
+            color_map = {hue: colors[idx % len(colors)] for idx, hue in enumerate(hue_levels)}
+        else:
+            color_map = {"_single": "#D9D9D9"}
+
+    n_x = len(resolved_x_order)
+    base_pos = np.arange(n_x, dtype=float)
+    num_hues = len(hue_levels) if hue_col else 1
+    has_hue = hue_col is not None and num_hues > 1
+    width = 0.8 if not has_hue else min(0.85 / max(num_hues, 1), 0.8)
+    offsets = (np.arange(num_hues) - (num_hues - 1) / 2.0) * width if has_hue else np.array([0.0])
+    hue_index = {hue: idx for idx, hue in enumerate(hue_levels)}
+
+    ax.grid(False)
+    ax.yaxis.grid(True, which="major")
+    ax.xaxis.grid(False)
+
+    legend_handles: dict[str, object] = {}
+    rng = np.random.default_rng(int(observation_seed))
+    for j, x_value in enumerate(resolved_x_order):
+        x_center = base_pos[j]
+        for hue in hue_levels:
+            sub = stats[stats[x_col].astype(str) == str(x_value)]
+            if hue_col:
+                sub = sub[sub[hue_col].astype(str) == str(hue)]
+            if sub.empty:
+                continue
+            row = sub.iloc[0]
+            height = float(row[agg])
+
+            yerr = None
+            if dispersion == "sd":
+                dispersion_value = float(row.get("std", np.nan))
+                yerr = None if not np.isfinite(dispersion_value) else dispersion_value
+            elif dispersion == "iqr":
+                q1 = row.get("q1", np.nan)
+                q3 = row.get("q3", np.nan)
+                if np.isfinite(q1) and np.isfinite(q3):
+                    if agg == "median":
+                        lower = max(height - float(q1), 0.0)
+                        upper = max(float(q3) - height, 0.0)
+                        yerr = [[lower], [upper]]
+                    else:
+                        yerr = max(0.5 * (float(q3) - float(q1)), 0.0)
+
+            error_kw = {"capsize": 3, "elinewidth": 1.0, "alpha": 0.9} if yerr is not None else None
+            xpos = x_center + offsets[hue_index[hue]]
+            bar_color = color_map[hue] if hue_col else ((x_color_map or {}).get(str(x_value), "#D9D9D9"))
+            bars = ax.bar(
+                [xpos],
+                [height],
+                width=width,
+                color=bar_color,
+                edgecolor="#C0C0C0",
+                zorder=1,
+                yerr=yerr,
+                **({"error_kw": error_kw} if error_kw else {}),
+                label=(str(hue) if (show_legend and hue not in legend_handles) else None),
+            )
+            if show_legend and hue not in legend_handles and len(bars.patches) > 0:
+                legend_handles[hue] = bars.patches[0]
+
+            rr = snapped[snapped[x_col].astype(str) == str(x_value)]
+            if hue_col:
+                rr = rr[rr[hue_col].astype(str) == str(hue)]
+            if not rr.empty:
+                jitter = float(width) * (0.08 if has_hue else 0.12)
+                xj = xpos + (rng.random(len(rr)) - 0.5) * (2.0 * jitter)
+                ax.scatter(
+                    xj,
+                    rr["value"],
+                    s=34,
+                    zorder=3,
+                    facecolors="#FFFFFF",
+                    edgecolors="#C0C0C0",
+                    linewidths=0.7,
+                    color=None,
+                )
+
+    ax.set_xticks(base_pos)
+    horizontal_alignment = "center" if float(tick_rotation) == 0.0 else "right"
+    tick_kwargs = {"fontsize": tick_label_size} if tick_label_size is not None else {}
+    ax.set_xticklabels(resolved_x_order, rotation=float(tick_rotation), ha=horizontal_alignment, **tick_kwargs)
+    ax.set_xlabel("")
+    ylabel_kwargs = {"fontsize": axis_label_size} if axis_label_size is not None else {}
+    ax.set_ylabel(ylabel, **ylabel_kwargs)
+    if tick_label_size is not None:
+        ax.tick_params(axis="y", labelsize=tick_label_size)
+    if title:
+        ax.set_title(title, fontweight="normal")
+
+    if show_legend and hue_col and len(hue_levels) > 1 and legend_handles:
+        legend_kwargs = {"fontsize": legend_fontsize} if legend_fontsize is not None else {}
+        ax.legend(
+            handles=list(legend_handles.values()),
+            labels=list(legend_handles.keys()),
+            loc=str(legend_loc),
+            title=None,
+            frameon=False,
+            **legend_kwargs,
+        )

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

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+import pandas as pd
+import polars as pl
+
+from reader_workbench.domains.plate_reader.analysis.timepoints import nearest_time_per_key
+
+from ..common import select_exact_observations
+
+
+@dataclass(frozen=True)
+class SnapshotSelection:
+    rows: pd.DataFrame
+    time_used: float
+    fell_back: bool
+    fallback_delta: float | None = None
+    fallback_times_preview: str | None = None
+
+
+def select_snapshot_rows(
+    *,
+    df: pd.DataFrame,
+    target_time: float,
+    keys: Sequence[str],
+    channel: str,
+    tolerance: float,
+) -> SnapshotSelection:
+    snapped = nearest_time_per_key(df, target_time=float(target_time), keys=list(keys), tol=float(tolerance))
+    snapped = snapped[snapped["channel"].astype(str) == str(channel)].copy()
+    if snapped.empty:
+        fallback = nearest_time_per_key(df, target_time=float(target_time), keys=list(keys), tol=float("inf"))
+        fallback = fallback[fallback["channel"].astype(str) == str(channel)].copy()
+        fallback = select_exact_observations(fallback, where="snapshot summary")
+        if fallback.empty:
+            return SnapshotSelection(rows=fallback, time_used=float(target_time), fell_back=True)
+        times_used = pd.to_numeric(fallback["time"], errors="coerce").dropna()
+        unique_times = sorted(times_used.unique().tolist())
+        representative_time = unique_times[0] if len(unique_times) == 1 else float(pd.Series(unique_times).median())
+        preview = ", ".join(f"{time:.2f}" for time in unique_times[:6]) + (" …" if len(unique_times) > 6 else "")
+        return SnapshotSelection(
+            rows=fallback,
+            time_used=float(times_used.median()) if not times_used.empty else float(target_time),
+            fell_back=True,
+            fallback_delta=abs(float(representative_time) - float(target_time)),
+            fallback_times_preview=preview,
+        )
+
+    snapped = select_exact_observations(snapped, where="snapshot summary")
+    times_used = pd.to_numeric(snapped["time"], errors="coerce").dropna()
+    time_used = float(times_used.median()) if not times_used.empty else float(target_time)
+    return SnapshotSelection(rows=snapped, time_used=time_used, fell_back=False)
+
+
+def summarize_snapshot_values(
+    *,
+    df: pd.DataFrame,
+    group_cols: Sequence[str],
+    dispersion: str,
+) -> pd.DataFrame:
+    stats_pl = (
+        pl.from_pandas(df)
+        .with_columns(
+            pl.when(pl.col("value").cast(pl.Float64, strict=False).is_nan())
+            .then(None)
+            .otherwise(pl.col("value").cast(pl.Float64, strict=False))
+            .alias("value")
+        )
+        .group_by(list(group_cols))
+        .agg(
+            pl.col("value").count().alias("n"),
+            pl.col("value").mean().alias("mean"),
+            pl.col("value").median().alias("median"),
+            pl.col("value").std(ddof=1).alias("std"),
+        )
+    )
+
+    if dispersion == "iqr":
+        quantiles = (
+            pl.from_pandas(df)
+            .group_by(list(group_cols))
+            .agg(
+                pl.col("value").quantile(0.25, interpolation="linear").alias("q1"),
+                pl.col("value").quantile(0.75, interpolation="linear").alias("q3"),
+            )
+        )
+        stats_pl = stats_pl.join(quantiles, on=list(group_cols), how="left")
+
+    return stats_pl.sort(list(group_cols)).to_pandas(use_pyarrow_extension_array=False)

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

@@ -0,0 +1,296 @@
+"""Shared time-series drawing primitives."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+import numpy as np
+import pandas as pd
+from matplotlib.lines import Line2D
+
+from ..common import descriptive_mean_resampling_interval, select_exact_observations
+
+_MARKERS = ["o", "s", "^", "D", "P", "X", "v", "<", ">", "h", "H"]
+
+
+def marker_map_for_levels(levels: Sequence[str]) -> dict[str, str]:
+    return {str(level): _MARKERS[idx % len(_MARKERS)] for idx, level in enumerate(levels)}
+
+
+def _maybe_log(ax, enable: bool) -> None:
+    if enable:
+        ax.set_yscale("log")
+        ymin, ymax = ax.get_ylim()
+        if ymin <= 0:
+            ax.set_ylim(bottom=max(1e-12, ymin))
+
+
+def _summarize_time_series_lines(
+    *,
+    data: pd.DataFrame,
+    x_col: str,
+    hue_col: str,
+    hue_levels: Sequence[str],
+    segment_col: str | None,
+    observation_interval_mass: float,
+    observation_resamples: int,
+    observation_seed: int,
+    style_col: str | None = None,
+    style_levels: Sequence[str] | None = None,
+) -> dict[str | tuple[str, str], pd.DataFrame]:
+    if data.empty:
+        return {}
+
+    columns = [x_col, hue_col, "value"]
+    if style_col is not None and style_col in data.columns:
+        columns.append(style_col)
+    if segment_col is not None and segment_col in data.columns:
+        columns.append(segment_col)
+    plot_data = data.loc[:, columns].copy()
+    plot_data[hue_col] = plot_data[hue_col].astype(str)
+    active_style_col = style_col if style_col is not None and style_col in plot_data.columns else None
+    if active_style_col is not None:
+        plot_data[active_style_col] = plot_data[active_style_col].astype(str)
+    active_segment_col = segment_col if segment_col is not None and segment_col in plot_data.columns else None
+    if active_segment_col is not None:
+        plot_data[active_segment_col] = plot_data[active_segment_col].astype(str)
+    else:
+        active_segment_col = "__segment_id"
+        plot_data[active_segment_col] = "segment"
+    plot_data["value"] = pd.to_numeric(plot_data["value"], errors="coerce")
+    group_columns = [hue_col]
+    if active_style_col is not None:
+        group_columns.append(active_style_col)
+    group_columns.extend([active_segment_col, x_col])
+    grouped = plot_data.groupby(group_columns, dropna=False, sort=True)["value"]
+    rng = np.random.default_rng(int(observation_seed))
+
+    if active_style_col is None:
+        summary_keys: list[str | tuple[str, str]] = [str(hue) for hue in hue_levels]
+    else:
+        resolved_style_levels = [str(value) for value in (style_levels or [])]
+        if not resolved_style_levels:
+            resolved_style_levels = sorted(plot_data[active_style_col].dropna().astype(str).unique().tolist())
+        summary_keys = [(str(hue), style) for hue in hue_levels for style in resolved_style_levels]
+    summaries: dict[str | tuple[str, str], dict[str, list[object]]] = {
+        key: {x_col: [], "segment": [], "mean": [], "lower": [], "upper": []} for key in summary_keys
+    }
+    for group_key, series in grouped:
+        if active_style_col is None:
+            hue, segment_id, x_value = group_key
+            summary_key: str | tuple[str, str] = str(hue)
+        else:
+            hue, style, segment_id, x_value = group_key
+            summary_key = (str(hue), str(style))
+        payload = summaries.get(summary_key)
+        if payload is None:
+            continue
+        values = series.to_numpy(dtype=float, copy=False)
+        values = values[~np.isnan(values)]
+        if values.size == 0:
+            continue
+        mean, lower, upper = descriptive_mean_resampling_interval(
+            values,
+            interval_mass=observation_interval_mass,
+            resamples=observation_resamples,
+            rng=rng,
+        )
+        payload[x_col].append(x_value)
+        payload["segment"].append(str(segment_id))
+        payload["mean"].append(mean)
+        payload["lower"].append(lower)
+        payload["upper"].append(upper)
+
+    out: dict[str | tuple[str, str], pd.DataFrame] = {}
+    for key in summary_keys:
+        payload = summaries[key]
+        if not payload[x_col]:
+            continue
+        out[key] = pd.DataFrame(payload).sort_values(["segment", x_col], kind="stable")
+    return out
+
+
+def draw_time_series_panel(
+    ax,
+    *,
+    data: pd.DataFrame,
+    x_col: str,
+    hue_col: str,
+    hue_levels: list[str],
+    color_map: dict[str, str],
+    marker_map: dict[str, str],
+    segment_col: str | None,
+    show_observations: bool,
+    observation_interval_mass: float,
+    observation_interval_alpha: float,
+    observation_resamples: int,
+    observation_seed: int,
+    line_alpha: float,
+    mean_marker_alpha: float,
+    observation_alpha: float,
+    add_sheet_lines: bool,
+    sheet_lines: list[float] | None,
+    sheet_line_kwargs: dict | None,
+    log_y: bool,
+    xlabel: str,
+    ylabel: str,
+    legend_loc: str,
+    show_legend: bool,
+    legend_label_map: Mapping[str, str] | None = None,
+    marked_time: float | None = None,
+    marked_time_kwargs: dict | None = None,
+    line_width: float = 1.8,
+    mean_marker_size: float = 36.0,
+    mean_marker_every: int = 1,
+    observation_marker_size: float = 18.0,
+    axis_label_size: float = 10.0,
+    tick_label_size: float = 8.0,
+    legend_fontsize: float = 8.0,
+    legend_marker_size: float = 7.0,
+    style_col: str | None = None,
+    style_levels: list[str] | None = None,
+    linestyle_map: dict[str, str] | None = None,
+    style_legend_loc: str = "lower right",
+    style_legend_title: str | None = None,
+) -> None:
+    ax.grid(False)
+    ax.yaxis.grid(True, which="major")
+    ax.xaxis.grid(True, which="major")
+    data = select_exact_observations(data, where="time-series summary")
+
+    if show_observations:
+        for hue in hue_levels:
+            rr = data[data[hue_col].astype(str) == str(hue)]
+            ax.scatter(
+                rr[x_col],
+                rr["value"],
+                s=observation_marker_size,
+                alpha=observation_alpha,
+                zorder=3,
+                linewidths=0.0,
+                edgecolors="none",
+                marker=marker_map[hue],
+                c=color_map[hue],
+            )
+
+    summary_by_hue = _summarize_time_series_lines(
+        data=data,
+        x_col=x_col,
+        hue_col=hue_col,
+        hue_levels=hue_levels,
+        segment_col=segment_col,
+        observation_interval_mass=observation_interval_mass,
+        observation_resamples=observation_resamples,
+        observation_seed=observation_seed,
+        style_col=style_col,
+        style_levels=style_levels,
+    )
+    resolved_style_levels = [str(value) for value in (style_levels or [])]
+    if style_col is not None and not resolved_style_levels:
+        resolved_style_levels = sorted(data[style_col].dropna().astype(str).unique().tolist())
+    if style_col is None:
+        resolved_style_levels = []
+    style_cycle = ["-", "--", ":", "-."]
+    resolved_linestyle_map = linestyle_map or {
+        style: style_cycle[idx % len(style_cycle)] for idx, style in enumerate(resolved_style_levels)
+    }
+    for hue in hue_levels:
+        styles_for_hue: list[str | None] = resolved_style_levels if style_col is not None else [None]
+        for style in styles_for_hue:
+            summary_key: str | tuple[str, str] = str(hue) if style is None else (str(hue), str(style))
+            mm = summary_by_hue.get(summary_key)
+            if mm is None or mm.empty:
+                continue
+            for _, segment_df in mm.groupby("segment", sort=False):
+                if float(observation_interval_mass) > 0:
+                    ax.fill_between(
+                        segment_df[x_col],
+                        segment_df["lower"],
+                        segment_df["upper"],
+                        alpha=float(observation_interval_alpha),
+                        color=color_map[hue],
+                        linewidth=0.0,
+                        zorder=1,
+                    )
+                ax.plot(
+                    segment_df[x_col],
+                    segment_df["mean"],
+                    color=color_map[hue],
+                    linestyle=(resolved_linestyle_map[str(style)] if style is not None else "-"),
+                    linewidth=line_width,
+                    alpha=line_alpha,
+                    zorder=1.5,
+                )
+                marker_rows = segment_df.iloc[:: max(1, int(mean_marker_every))]
+                ax.scatter(
+                    marker_rows[x_col],
+                    marker_rows["mean"],
+                    s=mean_marker_size,
+                    zorder=2.5,
+                    marker=marker_map[hue],
+                    alpha=mean_marker_alpha,
+                    edgecolors="none",
+                    linewidths=0.0,
+                    c=color_map[hue],
+                )
+
+    if add_sheet_lines and sheet_lines:
+        style = {"color": "#9E9E9E", "linestyle": "--", "linewidth": 0.8, "alpha": 0.9, "zorder": 0.5}
+        style.update(sheet_line_kwargs or {})
+        for sheet_x in sheet_lines:
+            ax.axvline(float(sheet_x), **style)
+
+    if marked_time is not None:
+        style = {"color": "#9E9E9E", "linestyle": "--", "linewidth": 0.9, "alpha": 1.0, "zorder": 0.8}
+        style.update(marked_time_kwargs or {})
+        ax.axvline(float(marked_time), **style)
+
+    _maybe_log(ax, log_y)
+    ax.set_xlabel(xlabel, fontsize=axis_label_size)
+    ax.set_ylabel(ylabel, fontsize=axis_label_size)
+    ax.tick_params(axis="x", labelsize=tick_label_size)
+    ax.tick_params(axis="y", labelsize=tick_label_size)
+
+    if show_legend:
+        handles = [
+            Line2D(
+                [0],
+                [0],
+                color=color_map[hue],
+                marker=marker_map[hue],
+                markersize=legend_marker_size,
+                linestyle="-",
+                linewidth=line_width,
+                alpha=mean_marker_alpha,
+                label=(str(legend_label_map.get(str(hue), hue)) if legend_label_map is not None else str(hue)),
+            )
+            for hue in hue_levels
+        ]
+        hue_legend = ax.legend(
+            handles=handles,
+            loc=legend_loc,
+            title=None,
+            frameon=False,
+            fontsize=legend_fontsize,
+        )
+        if resolved_style_levels:
+            ax.add_artist(hue_legend)
+            style_handles = [
+                Line2D(
+                    [0],
+                    [0],
+                    color="#333333",
+                    linestyle=resolved_linestyle_map[style],
+                    linewidth=line_width,
+                    label=style,
+                )
+                for style in resolved_style_levels
+            ]
+            ax.legend(
+                handles=style_handles,
+                loc=style_legend_loc,
+                title=style_legend_title,
+                frameon=False,
+                fontsize=legend_fontsize,
+                title_fontsize=legend_fontsize,
+            )