reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/plugins/plot/time_series.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+from pydantic import Field, model_validator
+
+from reader_workbench.plotting.sinks import PlotFigure
+from reader_workbench.plugins.plot._shared import FigurePlotPlugin, PlotPartitionCfg, resolve_plot_partition_cfg
+from reader_workbench.workbench.ports import dataframe_input
+from reader_workbench.workbench.registry import PluginConfig
+
+
+class TimeSeriesFigureCfg(PluginConfig):
+    """Presentation options consumed by the time-series renderer."""
+
+    figsize: tuple[float, float] | None = None
+    dpi: int | None = Field(default=None, gt=0)
+    ext: str | None = Field(default=None, min_length=1)
+    rc: dict[str, Any] | None = None
+    rasterize_zorder: float | None = None
+    line_alpha: float | None = Field(default=None, ge=0.0, le=1.0)
+    mean_marker_alpha: float | None = Field(default=None, ge=0.0, le=1.0)
+    observation_alpha: float | None = Field(default=None, ge=0.0, le=1.0)
+    axis_label_size: float | None = Field(default=None, gt=0.0)
+    title_fontsize: float | None = Field(default=None, gt=0.0)
+    tick_label_size: float | None = Field(default=None, gt=0.0)
+    legend_fontsize: float | None = Field(default=None, gt=0.0)
+    legend_marker_size: float | None = Field(default=None, gt=0.0)
+    mean_marker_size: float | None = Field(default=None, gt=0.0)
+    observation_marker_size: float | None = Field(default=None, gt=0.0)
+    line_width: float | None = Field(default=None, gt=0.0)
+    top: float | None = Field(default=None, ge=0.0, le=1.0)
+    bottom: float | None = Field(default=None, ge=0.0, le=1.0)
+    left: float | None = Field(default=None, ge=0.0, le=1.0)
+    right: float | None = Field(default=None, ge=0.0, le=1.0)
+    wspace: float | None = Field(default=None, ge=0.0)
+    hspace: float | None = Field(default=None, ge=0.0)
+
+    @model_validator(mode="after")
+    def validate_geometry(self) -> TimeSeriesFigureCfg:
+        if self.figsize is not None and any(value <= 0.0 for value in self.figsize):
+            raise ValueError("time_series.fig.figsize values must be positive")
+        if self.left is not None and self.right is not None and self.left >= self.right:
+            raise ValueError("time_series.fig.left must be less than fig.right")
+        if self.bottom is not None and self.top is not None and self.bottom >= self.top:
+            raise ValueError("time_series.fig.bottom must be less than fig.top")
+        return self
+
+
+class TimeSeriesCfg(PluginConfig):
+    x: str = "time"
+    xlabel: str | None = None
+    y: list[str] | None = None
+    ylabel_map: dict[str, str] = Field(default_factory=dict)
+    hue_label_map: dict[str, str] = Field(default_factory=dict)
+    hue: str = "treatment"
+    partition: PlotPartitionCfg = Field(default_factory=PlotPartitionCfg)
+    fig: TimeSeriesFigureCfg = Field(default_factory=TimeSeriesFigureCfg)
+    channels: list[str] | None = None
+    add_sheet_line: bool = False
+    sheet_line_kwargs: dict[str, Any] = Field(default_factory=dict)
+    log_transform: bool | list[str] = False
+    time_window: list[float] | None = None
+    observation_interval_mass: float = Field(default=0.95, gt=0.0, lt=1.0)
+    observation_interval_alpha: float = Field(default=0.15, ge=0.0, le=1.0)
+    observation_resamples: int = Field(default=100, ge=1)
+    observation_seed: int = 0
+    legend_loc: str = "upper left"
+    show_observations: bool = False
+    shared_legend: bool = False
+    filename: str | None = None
+
+
+class TimeSeriesPlot(FigurePlotPlugin):
+    ConfigModel = TimeSeriesCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"df": dataframe_input("df", "tidy.v1")}
+
+    def render(self, ctx, inputs, cfg: TimeSeriesCfg) -> list[PlotFigure]:
+        df: pd.DataFrame = inputs["df"]
+        from reader_workbench.domains.plate_reader.plots.time_series import plot_time_series  # noqa: PLC0415
+
+        partition = resolve_plot_partition_cfg(ctx=ctx, partition=cfg.partition)
+
+        return plot_time_series(
+            df=df,
+            x=cfg.x,
+            xlabel=cfg.xlabel,
+            y=cfg.y,
+            ylabel_map=cfg.ylabel_map,
+            hue_label_map=cfg.hue_label_map,
+            hue=cfg.hue,
+            channels=cfg.channels,
+            group_on=partition.group_by,
+            pool_sets=partition.collection_items,
+            pool_match=partition.match,
+            fig_kwargs=cfg.fig.model_dump(exclude_none=True),
+            add_sheet_line=cfg.add_sheet_line,
+            sheet_line_kwargs=cfg.sheet_line_kwargs,
+            log_transform=cfg.log_transform,
+            time_window=cfg.time_window,
+            palette_book=ctx.palette_book,
+            observation_interval_mass=cfg.observation_interval_mass,
+            observation_interval_alpha=cfg.observation_interval_alpha,
+            observation_resamples=cfg.observation_resamples,
+            observation_seed=cfg.observation_seed,
+            legend_loc=cfg.legend_loc,
+            show_observations=cfg.show_observations,
+            shared_legend=cfg.shared_legend,
+            filename=cfg.filename,
+        )

reader_workbench/plugins/plot/ts_and_snap.py

@@ -0,0 +1,210 @@
+"""Two-panel plot (time series + snapshot barplot)."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+import pandas as pd
+from pydantic import Field, model_validator
+
+from reader_workbench.plotting.sinks import PlotFigure
+from reader_workbench.plugins.plot._shared import FigurePlotPlugin, PlotPartitionCfg, resolve_plot_partition_cfg
+from reader_workbench.workbench.ports import dataframe_input
+from reader_workbench.workbench.registry import PluginConfig
+
+
+class TSAndSnapFigureCfg(PluginConfig):
+    """Figure and presentation options accepted by the composite renderer."""
+
+    figsize: tuple[float, float] | None = None
+    dpi: float | None = Field(default=None, gt=0)
+    facecolor: str | None = None
+    edgecolor: str | None = None
+    frameon: bool | None = None
+    clear: bool | None = None
+    constrained_layout: bool | None = None
+    layout: str | None = None
+    rc: dict[str, Any] | None = None
+    ext: str | None = None
+    axis_label_size: float | None = Field(default=None, gt=0)
+    tick_label_size: float | None = Field(default=None, gt=0)
+    legend_fontsize: float | None = Field(default=None, gt=0)
+    legend_marker_size: float | None = Field(default=None, gt=0)
+    line_width: float | None = Field(default=None, gt=0)
+    mean_marker_size: float | None = Field(default=None, gt=0)
+    mean_marker_every: int | None = Field(default=None, ge=1)
+    observation_marker_size: float | None = Field(default=None, gt=0)
+    style_legend_loc: str | None = None
+    style_legend_title: str | None = None
+    snap_tick_rotation: float | None = None
+    ts_title: str | None = None
+    snap_title: str | None = None
+    line_alpha: float | None = Field(default=None, ge=0, le=1)
+    mean_marker_alpha: float | None = Field(default=None, ge=0, le=1)
+    observation_alpha: float | None = Field(default=None, ge=0, le=1)
+    suptitle_y: float | None = None
+
+
+class TSAndSnapCfg(PluginConfig):
+    # grouping
+    partition: PlotPartitionCfg = Field(default_factory=PlotPartitionCfg)
+    group_layout: Literal["separate", "paired_row"] = "separate"
+
+    # time series (left)
+    ts_x: str = "time"
+    ts_channel: str
+    ts_hue: str
+    ts_style: str | None = None
+    order_hue: list[str] | None = None
+    order_hue_ref: str | None = None
+    order_style: list[str] | None = None
+    order_style_ref: str | None = None
+    ts_time_window: list[float] | None = None
+    ts_add_sheet_line: bool = False
+    ts_sheet_line_kwargs: dict[str, Any] = Field(default_factory=dict)
+    ts_mark_snap_time: bool = False
+    ts_snap_line_kwargs: dict[str, Any] = Field(default_factory=dict)
+    ts_log_transform: bool | list[str] = False
+    ts_observation_interval_mass: float = Field(default=0.95, gt=0.0, lt=1.0)
+    ts_observation_interval_alpha: float = Field(default=0.15, ge=0.0, le=1.0)
+    ts_observation_resamples: int = Field(default=100, ge=1)
+    ts_observation_seed: int = 0
+    ts_show_observations: bool = False
+    ts_legend_loc: str = "upper right"
+
+    # snapshot (right)
+    snap_x: str = "treatment"
+    snap_channel: str | None = None
+    snap_hue: str | None = None
+    order_x: list[str] | None = None
+    order_x_ref: str | None = None
+    order_snap_hue: list[str] | None = None
+    order_snap_hue_ref: str | None = None
+    snap_time: float = Field(..., description="Snapshot time (hours); required for deterministic plotting.")
+    snap_agg: Literal["mean", "median"] = "mean"
+    snap_dispersion: Literal["sd", "iqr", "none"] = "sd"
+    snap_time_tolerance: float = 0.51
+    snap_show_legend: bool = False
+    snap_legend_loc: str = "upper right"
+    snap_color_by_x: bool = False
+    square_panels: bool = False
+
+    # figure
+    fig: TSAndSnapFigureCfg = Field(default_factory=TSAndSnapFigureCfg)
+    filename: str | None = None
+    title: str | None = None
+
+    @model_validator(mode="after")
+    def validate_order_sources(self) -> TSAndSnapCfg:
+        for arg_name in ("order_hue", "order_style", "order_x", "order_snap_hue"):
+            if getattr(self, arg_name) is not None and getattr(self, f"{arg_name}_ref") is not None:
+                raise ValueError(f"ts_and_snap: {arg_name} and {arg_name}_ref are mutually exclusive")
+        if self.order_style is not None and self.ts_style is None:
+            raise ValueError("ts_and_snap: order_style requires ts_style")
+        if self.order_style_ref is not None and self.ts_style is None:
+            raise ValueError("ts_and_snap: order_style_ref requires ts_style")
+        if self.order_snap_hue is not None and self.snap_hue is None:
+            raise ValueError("ts_and_snap: order_snap_hue requires snap_hue")
+        if self.order_snap_hue_ref is not None and self.snap_hue is None:
+            raise ValueError("ts_and_snap: order_snap_hue_ref requires snap_hue")
+        if self.snap_color_by_x and self.snap_hue is not None:
+            raise ValueError("ts_and_snap: snap_color_by_x requires snap_hue to be omitted")
+        return self
+
+
+class TSAndSnapPlot(FigurePlotPlugin):
+    ConfigModel = TSAndSnapCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"df": dataframe_input("df", "tidy.v1")}
+
+    @classmethod
+    def _resolve_semantic_orders(cls, *, experiment, cfg: TSAndSnapCfg):
+        return (
+            experiment.annotations.resolve_order_arg(
+                order=cfg.order_hue,
+                order_ref=cfg.order_hue_ref,
+                column=cfg.ts_hue,
+                arg_name="order_hue",
+            ),
+            experiment.annotations.resolve_order_arg(
+                order=cfg.order_style,
+                order_ref=cfg.order_style_ref,
+                column=cfg.ts_style,
+                arg_name="order_style",
+            ),
+            experiment.annotations.resolve_order_arg(
+                order=cfg.order_x,
+                order_ref=cfg.order_x_ref,
+                column=cfg.snap_x,
+                arg_name="order_x",
+            ),
+            experiment.annotations.resolve_order_arg(
+                order=cfg.order_snap_hue,
+                order_ref=cfg.order_snap_hue_ref,
+                column=cfg.snap_hue,
+                arg_name="order_snap_hue",
+            ),
+        )
+
+    @classmethod
+    def validate_semantic_references(cls, *, experiment, cfg: TSAndSnapCfg) -> None:
+        cls._resolve_semantic_orders(experiment=experiment, cfg=cfg)
+
+    def render(self, ctx, inputs, cfg: TSAndSnapCfg) -> list[PlotFigure]:
+        df: pd.DataFrame = inputs["df"]
+        from reader_workbench.domains.plate_reader.plots.ts_and_snap import plot_ts_and_snap  # noqa: PLC0415
+
+        partition = resolve_plot_partition_cfg(ctx=ctx, partition=cfg.partition)
+        if ctx.experiment is None:
+            raise ValueError("ts_and_snap requires experiment semantics in the run context")
+        resolved_order_hue, resolved_order_style, resolved_order_x, resolved_order_snap_hue = type(
+            self
+        )._resolve_semantic_orders(experiment=ctx.experiment, cfg=cfg)
+
+        return plot_ts_and_snap(
+            df=df,
+            group_on=partition.group_by,
+            pool_sets=partition.collection_items,
+            pool_match=partition.match,
+            group_layout=cfg.group_layout,
+            # ts (left)
+            ts_x=cfg.ts_x,
+            ts_channel=cfg.ts_channel,
+            ts_hue=cfg.ts_hue,
+            ts_style=cfg.ts_style,
+            order_hue=resolved_order_hue,
+            order_style=resolved_order_style,
+            ts_time_window=cfg.ts_time_window,
+            ts_add_sheet_line=cfg.ts_add_sheet_line,
+            ts_sheet_line_kwargs=cfg.ts_sheet_line_kwargs,
+            ts_mark_snap_time=cfg.ts_mark_snap_time,
+            ts_snap_line_kwargs=cfg.ts_snap_line_kwargs,
+            ts_log_transform=cfg.ts_log_transform,
+            ts_observation_interval_mass=cfg.ts_observation_interval_mass,
+            ts_observation_interval_alpha=cfg.ts_observation_interval_alpha,
+            ts_observation_resamples=cfg.ts_observation_resamples,
+            ts_observation_seed=cfg.ts_observation_seed,
+            ts_show_observations=cfg.ts_show_observations,
+            ts_legend_loc=cfg.ts_legend_loc,
+            # snap (right)
+            snap_x=cfg.snap_x,
+            snap_channel=cfg.snap_channel,
+            snap_hue=cfg.snap_hue,
+            order_x=resolved_order_x,
+            order_snap_hue=resolved_order_snap_hue,
+            snap_time=cfg.snap_time,
+            snap_agg=cfg.snap_agg,
+            snap_dispersion=cfg.snap_dispersion,
+            snap_time_tolerance=cfg.snap_time_tolerance,
+            snap_show_legend=cfg.snap_show_legend,
+            snap_legend_loc=cfg.snap_legend_loc,
+            snap_color_by_x=cfg.snap_color_by_x,
+            square_panels=cfg.square_panels,
+            # fig
+            fig_kwargs=cfg.fig.model_dump(exclude_none=True),
+            filename=cfg.filename,
+            title=cfg.title,
+            palette_book=ctx.palette_book,
+        )

reader_workbench/plugins/transform/_four_state_vector.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from reader_workbench.domains.logic.four_state_vector.builder import (
+    FourStateVectorBuildResult,
+    build_four_state_vector_from_tidy,
+)
+from reader_workbench.domains.logic.four_state_vector.treatment_semantics import (
+    bind_four_state_vector_treatment_semantics,
+)
+
+
+def build_four_state_vector_plugin_result(*, ctx, df: pd.DataFrame, cfg) -> FourStateVectorBuildResult:
+    if ctx.experiment is None:
+        raise ValueError("four_state_vector requires experiment semantics in the run context")
+    state_space = ctx.experiment.annotations.resolve_ordered_state_space(ref=cfg.state_map_ref)
+    semantics = bind_four_state_vector_treatment_semantics(
+        state_ids=state_space.state_ids,
+        source_column=state_space.column,
+        source_values=state_space.source_values,
+        case_sensitive=state_space.case_sensitive,
+        treatment_column=cfg.treatment_column,
+    )
+    run_cfg = semantics.inject(cfg.model_dump(exclude={"state_map_ref"}))
+    return build_four_state_vector_from_tidy(df.copy(), run_cfg)
+
+
+def log_four_state_vector_plugin_result(*, ctx, result: FourStateVectorBuildResult) -> None:
+    vector = result.vector
+    four_state_vector_cfg = result.cfg
+    sel_logic = result.sel_logic
+    sel_int = result.sel_int
+    label_col = four_state_vector_cfg.design_by[0] if four_state_vector_cfg.design_by else "design_id"
+    idx_cols = [col for col in four_state_vector_cfg.design_by if col]
+
+    if sel_logic.time_warning:
+        ctx.logger.warning("four_state_vector: %s", sel_logic.time_warning)
+
+    try:
+        chosen = sel_logic.chosen_time
+        flats = int(vector["flat_logic"].sum()) if "flat_logic" in vector.columns else 0
+        r_stats = vector["r_logic"].describe() if "r_logic" in vector.columns else None
+        ref_info = result.log.get("reference", {})
+
+        if flats:
+            fraction = float(result.log.get("flat_logic_fraction", 0.0))
+            samples = [str(value) for value in result.log.get("flat_logic_sample_design_ids", ())]
+            sample_note = f" Sample design_ids: {', '.join(samples)}." if samples else ""
+            ctx.logger.warning(
+                "four_state_vector: flat logic detected for %d/%d designs (%.1f%%).%s",
+                flats,
+                len(vector),
+                fraction * 100.0,
+                sample_note,
+            )
+
+        ctx.logger.info(
+            "four_state_vector • inputs: [accent]logic[/accent]=%s → v00..v11  |  [accent]intensity[/accent]=%s → y*00..y*11",
+            four_state_vector_cfg.response.logic_channel,
+            four_state_vector_cfg.response.intensity_channel,
+        )
+        ctx.logger.info(
+            "four_state_vector • transform semantics:"
+            "  v: log2(LOGIC) → per-row min-max → [0,1] (persisted NOT log)."
+            "  y*: log2( ((INTENSITY + eps_abs)/max(A + alpha, eps_ref)) + delta ) (persisted in log2)."
+        )
+        ctx.logger.info(
+            "four_state_vector • knobs: eps_ratio=%.1e eps_range=%.1e eps_ref=%.1e eps_abs=%.1e  |  alpha=%.3g delta=%.3g",
+            float(four_state_vector_cfg.eps_ratio),
+            float(four_state_vector_cfg.eps_range),
+            float(four_state_vector_cfg.eps_ref),
+            float(four_state_vector_cfg.eps_abs),
+            float(four_state_vector_cfg.ref_add_alpha),
+            float(four_state_vector_cfg.log2_offset_delta),
+        )
+        ctx.logger.info(
+            "four_state_vector • r_logic definition: per design dynamic range on LOGIC (linear, ε-guarded): max(L_i)/min(L_i)"
+        )
+        ctx.logger.info(
+            "four_state_vector • design_by=%s\n"
+            "   time: mode=%s target=%.3g tol=%.3g • chosen=%s\n"
+            "   reference: requested=%r → resolved=%r • sequence=%r • observation_stat=%s\n"
+            "   rows: per_corner_logic=%d per_corner_intensity=%d vector=%d (flat=%d)\n"
+            "   r_logic: median=%.3g iqr=[%.3g, %.3g]",
+            ", ".join(four_state_vector_cfg.design_by),
+            four_state_vector_cfg.time_mode,
+            float(four_state_vector_cfg.target_time_h or np.nan),
+            float(four_state_vector_cfg.time_tolerance_h),
+            (float(chosen) if chosen is not None else None),
+            ref_info.get("design_id"),
+            ref_info.get("design_id_resolved"),
+            ref_info.get("sequence"),
+            ref_info.get("observation_stat"),
+            int(len(sel_logic.per_corner)),
+            int(len(sel_int.per_corner)),
+            int(len(vector)),
+            int(flats),
+            (float(r_stats["50%"]) if r_stats is not None else float("nan")),
+            (float(r_stats["25%"]) if r_stats is not None else float("nan")),
+            (float(r_stats["75%"]) if r_stats is not None else float("nan")),
+        )
+
+        _log_four_state_vector_observation_summary(
+            ctx=ctx,
+            design_by=four_state_vector_cfg.design_by,
+            idx_cols=idx_cols,
+            sel_logic=sel_logic,
+            sel_int=sel_int,
+        )
+        _log_four_state_vector_vector_preview(
+            ctx=ctx,
+            vector=vector,
+            idx_cols=idx_cols,
+            label_col=label_col,
+            logic_channel=four_state_vector_cfg.response.logic_channel,
+            intensity_channel=four_state_vector_cfg.response.intensity_channel,
+            sel_logic=sel_logic,
+        )
+    except Exception:
+        pass
+
+
+def _log_four_state_vector_observation_summary(
+    *, ctx, design_by: list[str], idx_cols: list[str], sel_logic, sel_int
+) -> None:
+    try:
+        logic_counts = sel_logic.points.set_index(idx_cols)[["n00", "n10", "n01", "n11"]].rename(
+            columns={"n00": "n00_L", "n10": "n10_L", "n01": "n01_L", "n11": "n11_L"}
+        )
+        intensity_counts = sel_int.points.set_index(idx_cols)[["n00", "n10", "n01", "n11"]].rename(
+            columns={"n00": "n00_I", "n10": "n10_I", "n01": "n01_I", "n11": "n11_I"}
+        )
+        joined = logic_counts.join(intensity_counts, how="outer").reset_index().sort_values(idx_cols)
+        for _, row in joined.iterrows():
+            key = " | ".join(f"{col}={row[col]}" for col in design_by if col in row.index)
+            logic_observations = [
+                int(row.get("n00_L", 0) or 0),
+                int(row.get("n10_L", 0) or 0),
+                int(row.get("n01_L", 0) or 0),
+                int(row.get("n11_L", 0) or 0),
+            ]
+            intensity_observations = [
+                int(row.get("n00_I", 0) or 0),
+                int(row.get("n10_I", 0) or 0),
+                int(row.get("n01_I", 0) or 0),
+                int(row.get("n11_I", 0) or 0),
+            ]
+            ctx.logger.info(
+                "four_state_vector • %s: observations (logic)=%s  (intensity)=%s",
+                key,
+                logic_observations,
+                intensity_observations,
+            )
+    except Exception:
+        pass
+
+
+def _log_four_state_vector_vector_preview(
+    *,
+    ctx,
+    vector: pd.DataFrame,
+    idx_cols: list[str],
+    label_col: str,
+    logic_channel: str,
+    intensity_channel: str,
+    sel_logic,
+) -> None:
+    try:
+        observation_count_map: dict[tuple, tuple[int, ...]] = {}
+        if not sel_logic.points.empty:
+            counts = sel_logic.points.set_index(idx_cols)[["n00", "n10", "n01", "n11"]]
+            for key, values in counts.iterrows():
+                normalized_key = key if isinstance(key, tuple) else (key,)
+                observation_count_map[normalized_key] = tuple(int(item) for item in values.to_list())
+
+        sort_cols = [col for col in [label_col] if col in vector.columns]
+        lines: list[str] = []
+        for _, row in vector.sort_values(sort_cols).iterrows():
+            key = " | ".join(f"{col}={row[col]}" for col in sort_cols)
+            v_txt = [f"{float(row[col]):.3f}" for col in ("v00", "v10", "v01", "v11")]
+            y_txt = [f"{float(row[col]):.3f}" for col in ("y00_star", "y10_star", "y01_star", "y11_star")]
+            observation_key = tuple(row[col] for col in idx_cols if col in vector.columns)
+            count_text = ""
+            if observation_key in observation_count_map:
+                count_text = f"  observation_n={list(observation_count_map[observation_key])}"
+            lines.append(
+                f"   • {key}: v={v_txt} | y*={y_txt} | r_logic={float(row.get('r_logic', np.nan)):.3g} "
+                f"(max/min={float(row.get('r_logic_max', np.nan)):.3g}/{float(row.get('r_logic_min', np.nan)):.3g}; "
+                f"corners {row.get('r_logic_corner_max', '?')}/{row.get('r_logic_corner_min', '?')}; "
+                f"span_log2={float(row.get('logic_span_log2', np.nan)):.3g}){count_text}"
+            )
+        if lines:
+            more = "" if len(lines) <= 12 else f"\n   … (+{len(lines) - 12} more)"
+            ctx.logger.info(
+                "four_state_vector • vector per design  [muted](v from log2(%s) min-max; y* is log2 of anchor-normalized %s)[/muted]\n%s%s",
+                logic_channel,
+                intensity_channel,
+                "\n".join(lines[:12]),
+                more,
+            )
+    except Exception:
+        pass

reader_workbench/plugins/transform/_labeling.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import pandas as pd
+
+
+def build_norm_map(mapping: Mapping[str, str], *, case_insensitive: bool) -> Mapping[str, str]:
+    if case_insensitive:
+        return {str(key).casefold(): str(value) for key, value in mapping.items()}
+    return {str(key): str(value) for key, value in mapping.items()}
+
+
+def log_label_summary(
+    ctx,
+    *,
+    column: str,
+    output_column: str,
+    rules_total: int,
+    used_rules: int,
+    changed_rows: int,
+    unique_values: int,
+    examples: list[str],
+    unused_rules_preview: list[str],
+    label: str,
+) -> None:
+    unused_count = len(unused_rules_preview)
+    ctx.logger.info(
+        "%s • [accent]%s[/accent] → %s • rules=%d used=%d changed=%d uniques=%d%s",
+        label,
+        column,
+        output_column,
+        rules_total,
+        used_rules,
+        changed_rows,
+        unique_values,
+        f" • unused={unused_count}" if unused_count else "",
+    )
+    if examples or unused_rules_preview:
+        examples_block = "\n".join(f"      • {entry}" for entry in examples) if examples else "      —"
+        unused_block = (
+            "\n".join(f"      • {entry}" for entry in unused_rules_preview) if unused_rules_preview else "      —"
+        )
+        ctx.logger.debug(
+            ("%s details • %s → %s\n   examples:\n%s\n   unused_rule_keys:\n%s"),
+            label,
+            column,
+            output_column,
+            examples_block,
+            unused_block,
+        )
+
+
+def apply_label_mappings(
+    *,
+    ctx,
+    df: pd.DataFrame,
+    mappings: Mapping[str, Mapping[str, str]],
+    output_names: Mapping[str, str],
+    in_place: bool,
+    case_insensitive: bool,
+    label: str,
+) -> pd.DataFrame:
+    out = df.copy()
+    for column, mapping in mappings.items():
+        if column not in out.columns:
+            raise ValueError(f"{label}: column '{column}' not found in dataframe")
+
+        before = out[column].astype(str)
+        unique_values = int(before.nunique(dropna=False))
+        normalized_before = before.str.casefold() if case_insensitive else before
+        normalized_map = build_norm_map(mapping, case_insensitive=case_insensitive)
+        rules_total = len(normalized_map)
+
+        mapped = normalized_before.map(normalized_map)
+        after_series = mapped.fillna(before)
+
+        output_column = column if in_place else output_names[column]
+        if in_place:
+            out[column] = after_series
+        else:
+            out[output_column] = after_series
+
+        changed_mask = mapped.notna() & (mapped.astype(str) != before)
+        changed_rows = int(changed_mask.sum())
+        used_rule_keys = set(normalized_before[normalized_before.isin(normalized_map.keys())].unique())
+        used_rules = len(used_rule_keys)
+
+        if changed_rows:
+            sample = pd.DataFrame({"raw": before, "alias": after_series})[changed_mask].drop_duplicates("raw")
+            examples = [f"{raw!r} → {alias!r}" for raw, alias in sample.head(6).itertuples(index=False)]
+        else:
+            examples = []
+        unused_rules = sorted(set(normalized_map.keys()) - used_rule_keys)
+        unused_rules_preview = [repr(key) for key in unused_rules[:6]]
+
+        log_label_summary(
+            ctx,
+            column=column,
+            output_column=output_column,
+            rules_total=rules_total,
+            used_rules=used_rules,
+            changed_rows=changed_rows,
+            unique_values=unique_values,
+            examples=examples,
+            unused_rules_preview=unused_rules_preview,
+            label=label,
+        )
+    return out