reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/domains/plate_reader/io/synergy_h1/_snapshot.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+
+import pandas as pd
+
+from ._shared import (
+    coerce_measurements,
+    drop_all_empty_rows,
+    is_blank_measurement,
+    require,
+    resolve_channel_from_map,
+)
+
+
+def tidy_snapshot_block(
+    snapshot: pd.DataFrame,
+    *,
+    elapsed_h: float,
+    sheet_index: int,
+    sheet_name: str,
+    channels: Sequence[str] | None,
+    channel_map_ci: Mapping[str, str],
+) -> pd.DataFrame:
+    require(channel_map_ci, "Snapshot parsing requires an explicit 'channel_map'")
+    require(not snapshot.empty, "Empty snapshot block")
+
+    header = snapshot.iloc[0]
+    well_columns = [index for index, value in enumerate(header) if str(value).strip().isdigit()]
+    require(well_columns, "Snapshot header did not contain numbered well columns")
+    well_numbers = [int(str(header[index]).strip()) for index in well_columns]
+    invalid_well_numbers = [number for number in well_numbers if number < 1 or number > 12]
+    require(
+        not invalid_well_numbers,
+        f"Snapshot header contains columns outside the 96-well range 1..12: {invalid_well_numbers}",
+    )
+    duplicate_well_numbers = sorted({number for number in well_numbers if well_numbers.count(number) > 1})
+    require(not duplicate_well_numbers, f"Snapshot header contains duplicate well columns: {duplicate_well_numbers}")
+
+    data_rows = drop_all_empty_rows(snapshot.iloc[1:].copy())
+    require(not data_rows.empty, "Snapshot block contains a header but no data rows")
+
+    row_column_candidates = [
+        column
+        for column in range(data_rows.shape[1])
+        if data_rows.iloc[:, column].map(lambda value: bool(re.fullmatch(r"[A-H]", str(value).strip()))).any()
+    ]
+    require(
+        len(row_column_candidates) == 1,
+        f"Could not identify one row-letter column in snapshot block on sheet {sheet_name!r}",
+    )
+    row_column = row_column_candidates[0]
+    label_columns = [
+        column for column in range(data_rows.shape[1]) if column != row_column and column not in well_columns
+    ]
+    expected_channels = set(channels or channel_map_ci.values())
+
+    def channel_for_data_row(row: pd.Series, *, plate_row: str) -> str:
+        declarations: list[tuple[str, str]] = []
+        for column in label_columns:
+            value = row.iat[column]
+            if is_blank_measurement(value):
+                continue
+            raw_label = str(value).strip()
+            try:
+                resolved = resolve_channel_from_map(raw_label, channel_map_ci=channel_map_ci)
+            except ValueError as error:
+                raise ValueError(f"{error} in snapshot sheet {sheet_name!r}, plate row {plate_row!r}") from error
+            if resolved is not None:
+                declarations.append((raw_label, resolved))
+        if not declarations:
+            raise ValueError(f"Missing snapshot channel label in sheet {sheet_name!r}, plate row {plate_row!r}")
+        if len(declarations) > 1:
+            labels = [raw for raw, _ in declarations]
+            raise ValueError(
+                f"Multiple snapshot channel labels {labels} in sheet {sheet_name!r}, plate row {plate_row!r}"
+            )
+        return declarations[0][1]
+
+    rows: list[dict[str, object]] = []
+    current_plate_row: str | None = None
+    current_channels: set[str] = set()
+
+    def finish_plate_row() -> None:
+        if current_plate_row is None:
+            return
+        missing = expected_channels - current_channels
+        require(
+            not missing,
+            f"Missing snapshot channel labels {sorted(missing)} in sheet {sheet_name!r}, "
+            f"plate row {current_plate_row!r}",
+        )
+
+    for _, data_row in data_rows.iterrows():
+        row_marker = data_row.iat[row_column]
+        if not is_blank_measurement(row_marker):
+            plate_row = str(row_marker).strip()
+            require(
+                bool(re.fullmatch(r"[A-H]", plate_row)),
+                f"Invalid snapshot row label {plate_row!r} in sheet {sheet_name!r}",
+            )
+            finish_plate_row()
+            current_plate_row = plate_row
+            current_channels = set()
+        require(
+            current_plate_row is not None,
+            f"Snapshot measurement row precedes a plate-row label in sheet {sheet_name!r}",
+        )
+
+        channel = channel_for_data_row(data_row, plate_row=current_plate_row)
+        require(
+            channel not in current_channels,
+            f"Duplicate snapshot channel {channel!r} in sheet {sheet_name!r}, plate row {current_plate_row!r}",
+        )
+        current_channels.add(channel)
+        for well_number, value in zip(well_numbers, data_row.iloc[well_columns].tolist(), strict=True):
+            rows.append(
+                {
+                    "position": f"{current_plate_row}{well_number}",
+                    "time": float(elapsed_h),
+                    "channel": channel,
+                    "value": value,
+                    "sheet_index": sheet_index,
+                    "sheet_name": sheet_name,
+                    "source": "snapshot",
+                }
+            )
+    finish_plate_row()
+    return coerce_measurements(pd.DataFrame(rows), source="snapshot")

reader_workbench/domains/plate_reader/ordering.py

@@ -0,0 +1,59 @@
+"""Plate-reader ordering semantics for treatments, doses, and labels."""
+
+from __future__ import annotations
+
+import re
+
+_NUM_RE = re.compile(r"[-+]?\d*\.?\d+(?:[eE][-+]?\d+)?")
+
+
+def _extract_first_number(s: str) -> float | None:
+    match = _NUM_RE.search(str(s))
+    return float(match.group(0)) if match else None
+
+
+def _unit_scale_to_uM(s: str) -> float:
+    text = str(s).lower()
+    if "nm" in text:
+        return 1e-3
+    if "µm" in text or "um" in text or "μm" in text:
+        return 1.0
+    if "mm" in text:
+        return 1e3
+    if re.search(r"\b(?<![a-z])m\b", text):
+        return 1e6
+    return 1.0
+
+
+def smart_string_numeric_key(s: str) -> tuple[int, float, str]:
+    value = str(s)
+    num = _extract_first_number(value)
+    if num is None:
+        return (1, float("inf"), value.lower())
+    return (0, float(num) * _unit_scale_to_uM(value), value.lower())
+
+
+def _prefix_before_number(s: str) -> str:
+    value = str(s)
+    match = _NUM_RE.search(value)
+    prefix = value[: match.start()].strip() if match else value.strip()
+    return re.sub(r"\s+", " ", prefix).strip().lower()
+
+
+def smart_grouped_dose_key(s: str) -> tuple[str, int, float, str]:
+    value = str(s)
+    prefix = _prefix_before_number(value)
+    num = _extract_first_number(value)
+    has_num = 0 if num is not None else 1
+    scaled = float(num) * _unit_scale_to_uM(value) if num is not None else float("inf")
+    return (prefix, has_num, scaled, value.lower())
+
+
+def order_levels(levels: list[str]) -> list[str]:
+    try:
+        return sorted(levels, key=smart_grouped_dose_key)
+    except Exception:
+        return sorted(levels, key=smart_string_numeric_key)
+
+
+__all__ = ["order_levels", "smart_grouped_dose_key", "smart_string_numeric_key"]

reader_workbench/domains/plate_reader/plots/__init__.py

@@ -0,0 +1,15 @@
+"""Plate-reader plotting primitives and figure builders."""
+
+from .distributions import plot_distributions
+from .snapshot_barplot import plot_snapshot_barplot
+from .snapshot_heatmap import plot_snapshot_heatmap
+from .time_series import plot_time_series
+from .ts_and_snap import plot_ts_and_snap
+
+__all__ = [
+    "plot_time_series",
+    "plot_snapshot_heatmap",
+    "plot_snapshot_barplot",
+    "plot_distributions",
+    "plot_ts_and_snap",
+]

reader_workbench/domains/plate_reader/plots/_data.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterable
+
+import pandas as pd
+
+
+def require_columns(df: pd.DataFrame, cols: Iterable[str], *, where: str) -> None:
+    missing = [column for column in cols if column not in df.columns]
+    if missing:
+        raise ValueError(f"{where}: missing required columns: {missing}")
+
+
+def warn_if_empty(df: pd.DataFrame, *, where: str, detail: str | None = None) -> bool:
+    if not df.empty:
+        return False
+    message = f"[warn]{where}[/warn] • no rows to plot"
+    if detail:
+        message += f" ({detail})"
+    logging.getLogger("reader").info(message)
+    return True
+
+
+def alias_column(df: pd.DataFrame, name: str | None, suffix: str = "_alias") -> str | None:
+    if name is None:
+        return None
+    candidate = f"{str(name)}{suffix}"
+    return candidate if candidate in df.columns else name

reader_workbench/domains/plate_reader/plots/common.py

@@ -0,0 +1,346 @@
+"""Shared plotting helpers for plate-reader renderers."""
+
+from __future__ import annotations
+
+import logging
+import math
+from collections.abc import Iterable, Mapping
+from functools import lru_cache
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+import pandas as pd
+
+from reader_workbench.plotting.sinks import PlotFigure
+
+from ._data import alias_column, require_columns, warn_if_empty
+
+if TYPE_CHECKING:
+    from reader_workbench.plotting.style import PaletteBook
+
+
+def pretty_name(name: str, suffix: str = "_alias") -> str:
+    if name.endswith(suffix):
+        return name[: -len(suffix)]
+    return name
+
+
+def best_subplot_grid(n: int) -> tuple[int, int]:
+    n = max(1, int(n))
+    rows = int(math.floor(math.sqrt(n)))
+    cols = int(math.ceil(n / rows))
+    return rows, cols
+
+
+def colors_for(n: int, palette_book: PaletteBook | None) -> list[str]:
+    if palette_book:
+        if n == 1:
+            palette = palette_book.colors(2)
+            return [palette[1]] if (palette and str(palette[0]).lower() in {"#000000", "black"}) else [palette[0]]
+        return palette_book.colors(n)
+    from reader_workbench.plotting.style import PaletteBook as _PaletteBook  # noqa: PLC0415
+
+    cycle = _PaletteBook(name="colorblind").colors(max(2, n))
+    if n == 1 and str(cycle[0]).lower() in {"#000000", "black"} and len(cycle) > 1:
+        return [cycle[1]]
+    return cycle[:n]
+
+
+def plot_figure(
+    *,
+    fig: Any,
+    filename: str,
+    fig_kwargs: Mapping[str, Any] | None,
+    description: str | None = None,
+) -> PlotFigure:
+    ext = str((fig_kwargs or {}).get("ext", "pdf")).lower()
+    dpi = (fig_kwargs or {}).get("dpi", None)
+    return PlotFigure(fig=fig, filename=filename, ext=ext, dpi=dpi, description=description)
+
+
+def exact_observation_counts(frame: pd.DataFrame, *, value_col: str = "value") -> tuple[int, int]:
+    """Return total and bounded-or-non-finite counts without modifying source rows."""
+
+    exact = _exact_observation_mask(frame, value_col=value_col)
+    return len(frame), int((~exact).sum())
+
+
+def select_exact_observations(
+    frame: pd.DataFrame,
+    *,
+    where: str,
+    value_col: str = "value",
+) -> pd.DataFrame:
+    """Withhold observations that cannot support exact descriptive summaries."""
+
+    exact = _exact_observation_mask(frame, value_col=value_col)
+    omitted_count = int((~exact).sum())
+    if omitted_count:
+        logging.getLogger("reader").warning(
+            "%s: withheld %d bounded or non-finite observation(s)",
+            where,
+            omitted_count,
+        )
+    selected = frame.loc[exact].copy()
+    selected[value_col] = pd.to_numeric(selected[value_col], errors="coerce")
+    return selected
+
+
+def _exact_observation_mask(frame: pd.DataFrame, *, value_col: str) -> pd.Series:
+    values = pd.to_numeric(frame[value_col], errors="coerce").to_numpy(dtype=float, copy=False)
+    exact = pd.Series(np.isfinite(values), index=frame.index)
+    bound_column = f"{value_col}_bound_kind"
+    if bound_column in frame.columns:
+        exact &= frame[bound_column].eq("exact")
+    for suffix in ("policy_clipped", "instrument_overflow"):
+        flag_column = f"{value_col}_{suffix}"
+        if flag_column in frame.columns:
+            exact &= frame[flag_column].eq(False)
+    return exact
+
+
+def descriptive_mean_resampling_interval(
+    values: np.ndarray,
+    *,
+    interval_mass: float,
+    resamples: int,
+    rng: np.random.Generator,
+) -> tuple[float, float, float]:
+    """Summarize observed rows without claiming population coverage."""
+
+    mass = _interval_mass(interval_mass)
+    draws = _resample_count(resamples)
+    observed = np.asarray(values, dtype=float)
+    finite_mask = np.isfinite(observed)
+    censored_count = int((~finite_mask).sum())
+    if censored_count:
+        _warn_censored_summary(censored_count=censored_count, observed_count=int(observed.size))
+        return (math.nan, math.nan, math.nan)
+    finite = observed
+    if finite.size == 0:
+        return (math.nan, math.nan, math.nan)
+    mean = float(finite.mean())
+    if finite.size <= 1:
+        return mean, mean, mean
+    alpha = (1.0 - mass) / 2.0
+    if finite.size <= 3:
+        resampled_means = finite[_ordered_resampling_indices(finite.size)].mean(axis=1)
+    else:
+        samples = rng.integers(0, finite.size, size=(draws, finite.size))
+        resampled_means = finite[samples].mean(axis=1)
+    lower, upper = np.quantile(resampled_means, [alpha, 1.0 - alpha])
+    return mean, float(lower), float(upper)
+
+
+def descriptive_linear_resampling_interval(
+    groups: Iterable[np.ndarray | list[float] | tuple[float, ...]],
+    *,
+    coefficients: Iterable[float],
+    interval_mass: float,
+    resamples: int,
+    rng: np.random.Generator,
+) -> tuple[float, float, float]:
+    mass = _interval_mass(interval_mass)
+    draws = _resample_count(resamples)
+    observed_groups = [np.asarray(group, dtype=float) for group in groups]
+    coeffs = [float(value) for value in coefficients]
+    if len(observed_groups) != len(coeffs):
+        raise ValueError("descriptive_linear_resampling_interval: groups and coefficients must have the same length")
+
+    finite_groups: list[np.ndarray] = []
+    for values in observed_groups:
+        finite_mask = np.isfinite(values)
+        censored_count = int((~finite_mask).sum())
+        if censored_count:
+            _warn_censored_summary(censored_count=censored_count, observed_count=int(values.size))
+            return (math.nan, math.nan, math.nan)
+        if values.size == 0:
+            return (math.nan, math.nan, math.nan)
+        finite_groups.append(values)
+
+    mean = float(sum(coeff * values.mean() for coeff, values in zip(coeffs, finite_groups, strict=True)))
+    if all(values.size <= 1 for values in finite_groups):
+        return mean, mean, mean
+    alpha = (1.0 - mass) / 2.0
+
+    boot_values = np.zeros(draws, dtype=float)
+    for coeff, values in zip(coeffs, finite_groups, strict=True):
+        if values.size == 1:
+            boot_values += coeff * float(values[0])
+            continue
+        sample_index = rng.integers(0, values.size, size=(draws, values.size))
+        boot_values += coeff * values[sample_index].mean(axis=1)
+    lower, upper = np.quantile(boot_values, [alpha, 1.0 - alpha])
+    return mean, float(lower), float(upper)
+
+
+def _interval_mass(value: float) -> float:
+    mass = float(value)
+    if not math.isfinite(mass) or not 0.0 < mass < 1.0:
+        raise ValueError("descriptive interval mass must lie strictly between 0 and 1")
+    return mass
+
+
+def _resample_count(value: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        raise ValueError("descriptive resample count must be a positive integer")
+    return value
+
+
+def _warn_censored_summary(*, censored_count: int, observed_count: int) -> None:
+    logging.getLogger("reader").warning(
+        "plot summary: omitted censored summary; %d non-finite value(s) among %d observed value(s)",
+        censored_count,
+        observed_count,
+    )
+
+
+def shared_numeric_limits(
+    values: Iterable[object],
+    *,
+    center: float | None = None,
+    pad_fraction: float = 0.08,
+    min_span: float = 1e-6,
+) -> tuple[float, float]:
+    finite = np.asarray(list(values), dtype=float)
+    finite = finite[np.isfinite(finite)]
+    if finite.size == 0:
+        raise ValueError("shared_numeric_limits: expected at least one finite value")
+
+    lower = float(finite.min())
+    upper = float(finite.max())
+    span_floor = max(float(min_span), 1e-12)
+    pad_fraction = max(0.0, float(pad_fraction))
+
+    if center is not None:
+        midpoint = float(center)
+        half_span = max(abs(lower - midpoint), abs(upper - midpoint), span_floor / 2.0)
+        half_span *= 1.0 + pad_fraction
+        return midpoint - half_span, midpoint + half_span
+
+    span = max(upper - lower, span_floor)
+    pad = span * pad_fraction
+    midpoint = (lower + upper) / 2.0
+    half_span = max(span / 2.0 + pad, span_floor / 2.0)
+    return midpoint - half_span, midpoint + half_span
+
+
+@lru_cache(maxsize=4)
+def _ordered_resampling_indices(size: int) -> np.ndarray:
+    if size <= 0:
+        raise ValueError("resampling size must be positive")
+    grids = np.indices((size,) * size, dtype=np.intp)
+    return grids.reshape(size, -1).T
+
+
+def annotate_points_smart(
+    *,
+    ax: Any,
+    points: Iterable[tuple[float, float]],
+    labels: Iterable[str],
+    text_kwargs: Mapping[str, Any] | None = None,
+) -> list[Any]:
+    fig = ax.figure
+    fig.canvas.draw()
+    renderer = fig.canvas.get_renderer()
+    axes_bbox = ax.get_window_extent(renderer=renderer)
+    point_array = np.asarray(list(points), dtype=float)
+    label_list = [str(label) for label in labels]
+    if point_array.size == 0 or not label_list:
+        return []
+
+    candidate_offsets = [
+        (6, 6),
+        (6, -6),
+        (-6, 6),
+        (-6, -6),
+        (10, 0),
+        (-10, 0),
+        (0, 10),
+        (0, -10),
+        (12, 12),
+        (12, -12),
+        (-12, 12),
+        (-12, -12),
+        (18, 0),
+        (-18, 0),
+        (0, 18),
+        (0, -18),
+    ]
+    display_points = ax.transData.transform(point_array)
+    placed_bboxes: list[Any] = []
+    annotations: list[Any] = []
+    defaults = {
+        "fontsize": 8,
+        "annotation_clip": False,
+        "clip_on": False,
+        "zorder": 6,
+    }
+    defaults.update(dict(text_kwargs or {}))
+
+    for idx, ((x_val, y_val), label) in enumerate(zip(point_array, label_list, strict=False)):
+        other_points = np.delete(display_points, idx, axis=0) if len(display_points) > 1 else np.empty((0, 2))
+        best_offset = candidate_offsets[0]
+        best_score = float("inf")
+        for offset in candidate_offsets:
+            annotation = ax.annotate(
+                label,
+                (float(x_val), float(y_val)),
+                xytext=offset,
+                textcoords="offset points",
+                **defaults,
+            )
+            bbox = annotation.get_window_extent(renderer=renderer).expanded(1.04, 1.10)
+            overlap_penalty = sum(_bbox_overlap_area(bbox, existing) for existing in placed_bboxes)
+            point_penalty = sum(1.0 for px, py in other_points if bbox.contains(px, py))
+            out_penalty = _bbox_outside_axes_penalty(bbox, axes_bbox)
+            distance_penalty = abs(offset[0]) + abs(offset[1])
+            score = overlap_penalty * 1000.0 + point_penalty * 25000.0 + out_penalty * 25.0 + distance_penalty
+            annotation.remove()
+            if score < best_score:
+                best_score = score
+                best_offset = offset
+        final_annotation = ax.annotate(
+            label,
+            (float(x_val), float(y_val)),
+            xytext=best_offset,
+            textcoords="offset points",
+            **defaults,
+        )
+        placed_bboxes.append(final_annotation.get_window_extent(renderer=renderer).expanded(1.04, 1.10))
+        annotations.append(final_annotation)
+    return annotations
+
+
+def _bbox_overlap_area(left: Any, right: Any) -> float:
+    if not left.overlaps(right):
+        return 0.0
+    x_overlap = max(0.0, min(left.x1, right.x1) - max(left.x0, right.x0))
+    y_overlap = max(0.0, min(left.y1, right.y1) - max(left.y0, right.y0))
+    return float(x_overlap * y_overlap)
+
+
+def _bbox_outside_axes_penalty(bbox: Any, axes_bbox: Any) -> float:
+    penalty = 0.0
+    penalty += max(0.0, axes_bbox.x0 - bbox.x0)
+    penalty += max(0.0, bbox.x1 - axes_bbox.x1)
+    penalty += max(0.0, axes_bbox.y0 - bbox.y0)
+    penalty += max(0.0, bbox.y1 - axes_bbox.y1)
+    return float(penalty)
+
+
+__all__ = [
+    "alias_column",
+    "annotate_points_smart",
+    "best_subplot_grid",
+    "descriptive_linear_resampling_interval",
+    "descriptive_mean_resampling_interval",
+    "colors_for",
+    "exact_observation_counts",
+    "plot_figure",
+    "pretty_name",
+    "require_columns",
+    "select_exact_observations",
+    "shared_numeric_limits",
+    "warn_if_empty",
+]