reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/domains/logic/four_state_vector/math.py

@@ -0,0 +1,191 @@
+"""four-state vector math: build vector from logic/intensity per-corner points.
+
+Compute the vector = [v00,v10,v01,v11, y00*,y10*,y01*,y11*] per design.
+
+- v* are computed from the LOGIC CHANNEL (e.g., YFP/CFP):
+    # r_logic and v computation are derived from the LOGIC channel corner means.
+    # r_logic is the dynamic range on the linear scale (after ε guard),
+    # while v is obtained by log2 + min-max on the *log* scale.
+    if max(u)-min(u) <= eps_range: v_i = 0.25
+    else: v = (u - u_min) / ((u_max - u_min) + eta)
+
+- y* are computed from the INTENSITY CHANNEL (e.g., YFP/OD600):
+    y_linear_i = (b_i + eps_abs) / max(anchor_i + ref_add_alpha, eps_ref)
+    y*_i       = log2( max(y_linear_i + log2_offset_delta, eps_ratio) )
+
+Anchors are computed from the INTENSITY per-corner table for the reference design_id."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from pandas.api.types import is_bool_dtype
+
+
+def _safe_log2(x: np.ndarray | float, eps: float) -> np.ndarray | float:
+    return np.log2(np.maximum(x, eps))
+
+
+def _logic_minmax_from_four(
+    vals: tuple[float, float, float, float], *, eps_ratio: float, eps_range: float, eta: float
+) -> tuple[np.ndarray, float, bool, float, float, float, str, str]:
+    a = np.array(vals, dtype=float)
+    # ε‑guarded linear values (used for r_logic = max/min)
+    a_guard = np.maximum(a, eps_ratio)
+    # log2 for min–max shape mapping
+    u = _safe_log2(a_guard, eps_ratio)
+    umin, umax = float(np.min(u)), float(np.max(u))
+    span = umax - umin
+    flat = bool(span <= eps_range)
+    if flat:
+        v = np.full(4, 0.25, dtype=float)
+    else:
+        denom = span + float(eta)
+        if not np.isfinite(denom) or denom <= 0.0:
+            raise ValueError(f"four-state vector: invalid logic min-max denom (span={span}, eta={eta}).")
+        v = np.clip((u - umin) / denom, 0.0, 1.0)
+    M = float(np.max(a_guard))
+    m = float(np.min(a_guard))
+    r = (M / m) if M > 0 and m > 0 else 1.0
+    # Corner labels for clarity in logs/diagnostics
+    corners = np.array(["00", "10", "01", "11"])
+    cmax = str(corners[int(np.argmax(a_guard))])
+    cmin = str(corners[int(np.argmin(a_guard))])
+    # Return v, r, flat, plus diagnostics:
+    #   M (max), m (min) on linear scale; span on log2 scale; and which corners hit them.
+    return v.astype(float), r, flat, M, m, span, cmax, cmin
+
+
+def compute_four_state_vector(
+    *,
+    points_logic: pd.DataFrame,  # b00..b11 from LOGIC channel
+    points_intensity: pd.DataFrame,  # b00..b11 from INTENSITY channel
+    per_corner_intensity: pd.DataFrame,  # per-corner table for anchors
+    design_by: list[str],
+    reference_design_id: str | None,
+    reference_stat: str,
+    eps_ratio: float,
+    eps_range: float,
+    eps_ref: float,  # hard lower bound for (A + α)
+    eps_abs: float,  # small add to numerator b_i (absolute intensity)
+    ref_add_alpha: float,  # α
+    log2_offset_delta: float,  # δ
+) -> pd.DataFrame:
+    label_col = design_by[0]
+
+    # anchors from INTENSITY per-corner table for the reference design_id
+    ref_tab: pd.DataFrame | None = None
+    if reference_design_id:
+        ref_rows = per_corner_intensity[per_corner_intensity[label_col].astype(str) == str(reference_design_id)].copy()
+        if not ref_rows.empty:
+            agg_fun = "median" if reference_stat == "median" else "mean"
+            ref_tab = (
+                ref_rows.groupby(["corner"])["y_mean"]
+                .agg(agg_fun)
+                .reset_index()
+                .rename(columns={"y_mean": "anchor_mean"})
+            )
+
+    idx_cols = design_by
+    L = points_logic.set_index(idx_cols)
+    I_vec = points_intensity.set_index(idx_cols)
+    merged = (
+        L[["b00", "b10", "b01", "b11"]]
+        .join(I_vec[["b00", "b10", "b01", "b11"]], how="inner", lsuffix="_logic", rsuffix="_intensity")
+        .reset_index()
+    )
+
+    out_rows: list[dict[str, object]] = []
+    for _, row in merged.iterrows():
+        v, r_logic, flat, rmax, rmin, span_log2, cmax, cmin = _logic_minmax_from_four(
+            (float(row["b00_logic"]), float(row["b10_logic"]), float(row["b01_logic"]), float(row["b11_logic"])),
+            eps_ratio=eps_ratio,
+            eps_range=eps_range,
+            eta=eps_range,
+        )
+
+        anchors: dict[str, float] = {"00": np.nan, "10": np.nan, "01": np.nan, "11": np.nan}
+        if ref_tab is not None and not ref_tab.empty:
+            for _, rr in ref_tab.iterrows():
+                anchors[str(rr["corner"])] = float(rr["anchor_mean"])
+
+        def ystar(b: float, a: float, *, corner: str, design_label: object) -> float:
+            # Spec-aligned:
+            #   denom = max(a + α, eps_ref)
+            #   y_linear = (b + eps_abs) / denom
+            #   y* = log2( max(y_linear + δ, eps_ratio) )
+            anchor = float(a)
+            sample = float(b)
+            if not np.isfinite(anchor):
+                raise ValueError(
+                    f"four-state vector: missing anchor or non-finite anchor for corner {corner}; check reference configuration"
+                )
+            if not np.isfinite(sample):
+                raise ValueError(
+                    f"four-state vector: non-finite intensity for design {design_label!r} corner {corner}; check input data"
+                )
+            denom = max(anchor + float(ref_add_alpha), float(eps_ref))
+            if not np.isfinite(denom) or denom <= 0:
+                raise ValueError(f"four-state vector: invalid anchor denominator (max(A+alpha, eps_ref))={denom}")
+            y_linear = (sample + float(eps_abs)) / denom
+            log_arg = y_linear + float(log2_offset_delta)
+            # Guard only for the log argument (assertive, no silent backfills elsewhere)
+            return float(np.log2(np.maximum(log_arg, float(eps_ratio))))
+
+        design_label = row[idx_cols[0]] if idx_cols else "<unknown>"
+        y00 = ystar(float(row["b00_intensity"]), anchors["00"], corner="00", design_label=design_label)
+        y10 = ystar(float(row["b10_intensity"]), anchors["10"], corner="10", design_label=design_label)
+        y01 = ystar(float(row["b01_intensity"]), anchors["01"], corner="01", design_label=design_label)
+        y11 = ystar(float(row["b11_intensity"]), anchors["11"], corner="11", design_label=design_label)
+
+        rec: dict[str, object] = {c: row[c] for c in idx_cols}
+        rec.update(
+            v00=float(v[0]),
+            v10=float(v[1]),
+            v01=float(v[2]),
+            v11=float(v[3]),
+            y00_star=y00,
+            y10_star=y10,
+            y01_star=y01,
+            y11_star=y11,
+            r_logic=r_logic,
+            flat_logic=flat,
+            # Self-describing diagnostics for r_logic:
+            r_logic_min=float(rmin),
+            r_logic_max=float(rmax),
+            logic_span_log2=float(span_log2),
+            r_logic_corner_min=cmin,
+            r_logic_corner_max=cmax,
+        )
+        out_rows.append(rec)
+
+    df = pd.DataFrame.from_records(out_rows)
+
+    # Keep numerics as float for stability and downstream math.
+    float_cols = [
+        "v00",
+        "v10",
+        "v01",
+        "v11",
+        "y00_star",
+        "y10_star",
+        "y01_star",
+        "y11_star",
+        "r_logic",
+        "r_logic_min",
+        "r_logic_max",
+        "logic_span_log2",
+    ]
+    for c in float_cols:
+        if c in df.columns:
+            df[c] = pd.to_numeric(df[c], errors="coerce").astype(float)
+
+    # Contract compliance: flat_logic must be a proper boolean dtype.
+    if "flat_logic" in df.columns:
+        df["flat_logic"] = df["flat_logic"].astype(bool)
+        if not is_bool_dtype(df["flat_logic"]):
+            raise TypeError(
+                f"four-state vector internal error: expected boolean dtype for 'flat_logic', got {df['flat_logic'].dtype!r}"
+            )
+
+    return df

reader_workbench/domains/logic/four_state_vector/reference.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from typing import Literal
+
+import pandas as pd
+
+
+def _reduce(series: pd.Series, stat: Literal["mean", "median"]) -> float:
+    s = pd.to_numeric(series, errors="coerce").dropna()
+    if s.empty:
+        return float("nan")
+    return float(s.median()) if stat == "median" else float(s.mean())
+
+
+def resolve_reference_design_id(
+    df: pd.DataFrame,
+    *,
+    design_by: list[str],
+    ref_label: str | None,
+) -> str | None:
+    """
+    Deterministically resolve the configured reference label to the *raw* design label.
+    Policy:
+      1) If ref_label matches the raw label column exactly → use it.
+      2) Else, if <label>_alias exists and matches exactly → map to the single raw label.
+      3) Else → raise a clear error (no silent fallback).
+    """
+    if ref_label is None:
+        return None
+    label_col = design_by[0] if design_by else "design_id"
+    alias_col = f"{label_col}_alias"
+    want = str(ref_label)
+
+    if label_col in df.columns and df[label_col].astype(str).eq(want).any():
+        return want  # exact raw match
+
+    if alias_col in df.columns:
+        pairs = df[[label_col, alias_col]].dropna().astype(str).drop_duplicates()
+        matches = pairs.loc[pairs[alias_col] == want, label_col].unique()
+        if len(matches) == 1:
+            return str(matches[0])  # unique alias→raw mapping
+        if len(matches) > 1:
+            raise ValueError(
+                f"four_state_vector: reference.{label_col} {want!r} resolves via {alias_col!r} to multiple {label_col!r} values: "
+                f"{sorted(map(str, matches))!r}"
+            )
+
+    # diagnostics (short previews)
+    raw_vals = df[label_col].astype(str).unique().tolist() if label_col in df.columns else []
+    alias_vals = df[alias_col].astype(str).unique().tolist() if alias_col in df.columns else []
+    raw_prev = ", ".join(sorted(raw_vals)[:8]) + (" …" if len(raw_vals) > 8 else "")
+    alias_prev = ", ".join(sorted(alias_vals)[:8]) + (" …" if len(alias_vals) > 8 else "")
+    raise ValueError(
+        f"four_state_vector: reference.{label_col} {want!r} not found under {label_col!r} or {alias_col!r}.\n"
+        f"   available raw:   [{raw_prev}]\n"
+        f"   available alias: [{alias_prev or '—'}]"
+    )
+
+
+def compute_reference_table(
+    per_corner: pd.DataFrame,
+    *,
+    design_by: list[str],
+    ref_design_id: str,
+    stat: Literal["mean", "median"] = "mean",
+) -> pd.DataFrame:
+    """
+    Build a table of reference b00/b10/b01/b11 values.
+
+    Returns a DataFrame:
+      one row with columns ['b00','b10','b01','b11']
+    """
+    if not design_by:
+        raise ValueError("design_by must contain at least one column to locate the reference")
+
+    label_col = design_by[0]
+    ref_rows = per_corner[per_corner[label_col].astype(str) == str(ref_design_id)].copy()
+    if ref_rows.empty:
+        raise ValueError(f"Reference design_id {ref_design_id!r} has no rows in per-corner table.")
+
+    agg = ref_rows.groupby("corner")["y_mean"].agg(lambda s: _reduce(s, stat))
+    mean = pd.DataFrame([agg.to_dict()])
+    # Rename columns to b00..b11
+    mean = mean.rename(columns={"00": "b00", "10": "b10", "01": "b01", "11": "b11"})
+    return mean

reader_workbench/domains/logic/four_state_vector/selection.py

@@ -0,0 +1,228 @@
+"""four-state vector selection: time picking and corner-level observation aggregation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from reader_workbench.domains.logic.treatment_columns import choose_treatment_column, normalize_treatment_series
+
+REQUIRED_COLS = ["position", "time", "channel", "value"]
+
+
+@dataclass(frozen=True)
+class CornerizeResult:
+    per_corner: pd.DataFrame  # one row per (design×corner)
+    points: pd.DataFrame  # wide one row per design with b00.., sd00.., n00..
+    chosen_time: float | None
+    time_warning: str | None = None
+
+
+def _enforce_columns(df: pd.DataFrame, design_by: list[str]) -> None:
+    miss = [c for c in REQUIRED_COLS if c not in df.columns]
+    if miss:
+        raise ValueError(f"four-state vector: tidy data missing required columns: {miss}")
+    m2 = [c for c in design_by if c not in df.columns]
+    if m2:
+        raise ValueError(f"four-state vector: missing design_by columns: {m2}")
+
+
+def _pick_time(times: np.ndarray, target: float | None, mode: str) -> float | None:
+    if times.size == 0:
+        return None
+    times = np.unique(times.astype(float))
+    if target is None:
+        return float(np.max(times))
+    if mode == "exact":
+        hits = times[np.isclose(times, float(target), rtol=0, atol=1e-12)]
+        return float(hits[0]) if hits.size else None
+    if mode == "nearest":
+        return float(times[np.argmin(np.abs(times - float(target)))])
+    if mode == "last_before":
+        candidates = times[times <= float(target)]
+        return float(candidates.max()) if candidates.size else None
+    if mode == "first_after":
+        candidates = times[times >= float(target)]
+        return float(candidates.min()) if candidates.size else None
+    raise ValueError(f"Unknown time mode {mode!r}")
+
+
+def select_times(
+    df: pd.DataFrame,
+    *,
+    channel: str,
+    treatment_map: dict[str, str],
+    case_sensitive: bool,
+    target_time_h: float | None,
+    time_mode: str,
+    tolerance_h: float | None,
+    preferred_treatment_column: str | None = None,
+) -> tuple[pd.DataFrame, float | None, str | None]:
+    work = df[df["channel"] == channel].copy()
+    # Decide which column to match against (raw preferred; alias tolerated).
+    treatment_col = choose_treatment_column(
+        work,
+        treatment_map,
+        case_sensitive=case_sensitive,
+        preferred=preferred_treatment_column,
+    )
+    if case_sensitive:
+        mapped = [str(v) for v in treatment_map.values()]
+        work = work[work[treatment_col].astype(str).isin(mapped)].copy()
+    else:
+        mapped = [str(v).strip().casefold() for v in treatment_map.values()]
+        norm_col = "__norm_treatment"
+        work[norm_col] = normalize_treatment_series(work[treatment_col])
+        work = work[work[norm_col].isin(mapped)].copy()
+        work["_t_norm"] = work[norm_col]
+
+    if work.empty:
+        # Helpful, assertive diagnostics
+        present_unfiltered = df[df["channel"] == channel]
+        present_vals = (
+            present_unfiltered[treatment_col].astype(str).dropna().unique().tolist()
+            if treatment_col in present_unfiltered.columns
+            else []
+        )
+        preview_present = ", ".join(map(str, present_vals[:8])) + (" …" if len(present_vals) > 8 else "")
+        preview_expected = ", ".join(map(str, list(treatment_map.values())))
+        raise ValueError(
+            "four-state vector: no rows matched the requested channel/treatment_map.\n"
+            f"  channel: {channel!r}\n"
+            f"  using treatment column: {treatment_col!r}\n"
+            f"  expected (from treatment_map): [{preview_expected}]\n"
+            f"  present  (in data at channel): [{preview_present}]\n"
+            "Hints: ensure aliases map raw treatments to the configured labels, or update treatment_map to "
+            "match the values in the chosen treatment column."
+        )
+
+    t = _pick_time(work["time"].to_numpy(dtype=float), target_time_h, time_mode)
+    if t is None:
+        raise ValueError("four-state vector: could not choose a global time.")
+    out = work[np.isclose(work["time"].astype(float), float(t), rtol=0, atol=1e-9)].copy()
+
+    warn_note = None
+    if tolerance_h is not None and target_time_h is not None:
+        tol = float(tolerance_h)
+        tgt = float(target_time_h)
+        delta = abs(float(t) - tgt)
+        if delta > tol:
+            warn_note = (
+                f"Config requested time={tgt:.3f} h (mode={time_mode}, tol={tol:.3f} h) "
+                f"but closest time={float(t):.3f} h (|Δ|={delta:.3f} h); using {float(t):.3f} h."
+            )
+
+    return out, float(t), warn_note
+
+
+def cornerize_and_aggregate(
+    df: pd.DataFrame,
+    *,
+    design_by: list[str],
+    treatment_map: dict[str, str],
+    case_sensitive: bool,
+    time_column: str,
+    channel: str,
+    target_time_h: float | None,
+    time_mode: str,
+    time_tolerance_h: float | None,
+    require_all_corners_per_design: bool,
+    preferred_treatment_column: str | None = None,
+) -> CornerizeResult:
+    if time_column != "time":
+        if time_column not in df.columns:
+            raise ValueError(f"four-state vector: time column '{time_column}' not found.")
+        df = df.copy()
+        df["time"] = df[time_column]
+
+    _enforce_columns(df, design_by)
+
+    snap, chosen_time, warn_note = select_times(
+        df,
+        channel=channel,
+        treatment_map=treatment_map,
+        case_sensitive=case_sensitive,
+        preferred_treatment_column=preferred_treatment_column,
+        target_time_h=target_time_h,
+        time_mode=time_mode,
+        tolerance_h=time_tolerance_h,
+    )
+    if snap.empty:
+        raise ValueError("four-state vector: no rows remain after time selection.")
+
+    rev: dict[str, str] = {}
+    for k in ("00", "10", "01", "11"):
+        v = treatment_map[k]
+        key = str(v) if case_sensitive else str(v).strip().casefold()
+        if key in rev:
+            raise ValueError(f"four-state vector: duplicate treatment_map value: {v!r}")
+        rev[key] = k
+
+    # Map treatments → {00,10,01,11} using the same column we matched on.
+    corner_source = choose_treatment_column(
+        snap,
+        treatment_map,
+        case_sensitive=case_sensitive,
+        preferred=preferred_treatment_column,
+    )
+    if case_sensitive:
+        corner_values = snap[corner_source].astype(str)
+        rev_keys = {str(k): v for k, v in rev.items()}
+    else:
+        corner_values = normalize_treatment_series(snap[corner_source])
+        rev_keys = {str(k).strip().casefold(): v for k, v in rev.items()}
+    snap["corner"] = corner_values.map(rev_keys)
+
+    chk = snap.groupby(design_by + ["corner"])["time"].nunique().reset_index(name="n_times")
+    bad = chk[chk["n_times"] > 1]
+    if not bad.empty:
+        raise ValueError("four-state vector: more than one time within (design×corner) after selection.")
+
+    def _agg_mean(series: pd.Series) -> float:
+        s = pd.to_numeric(series, errors="coerce").dropna()
+        return float(s.mean()) if s.size else float("nan")
+
+    def _agg_sd(series: pd.Series) -> float:
+        s = pd.to_numeric(series, errors="coerce").dropna()
+        return float(s.std(ddof=1)) if s.size >= 2 else 0.0
+
+    def _agg_n(series: pd.Series) -> int:
+        return int(pd.to_numeric(series, errors="coerce").dropna().size)
+
+    grp_cols = design_by + ["corner"]
+    g = snap.groupby(grp_cols, dropna=False)
+    per_corner = g.agg(
+        time=("time", "first"), y_mean=("value", _agg_mean), y_sd=("value", _agg_sd), y_n=("value", _agg_n)
+    ).reset_index()
+
+    idx_cols = design_by
+    m = per_corner.pivot_table(index=idx_cols, columns="corner", values="y_mean", aggfunc="first")
+    s = per_corner.pivot_table(index=idx_cols, columns="corner", values="y_sd", aggfunc="first")
+    n = per_corner.pivot_table(index=idx_cols, columns="corner", values="y_n", aggfunc="first")
+
+    req = ["00", "10", "01", "11"]
+    if require_all_corners_per_design:
+        missing_groups = []
+        for idx, row in m.iterrows():
+            miss = [c for c in req if pd.isna(row.get(c))]
+            if miss:
+                key = idx if isinstance(idx, tuple) else (idx,)
+                missing_groups.append(f"{dict(zip(idx_cols, key, strict=False))} → missing corners {miss}")
+        if missing_groups:
+            raise ValueError("four-state vector: incomplete corner sets:\n" + "\n".join(missing_groups[:40]))
+
+    points = (
+        m[req]
+        .rename(columns={"00": "b00", "10": "b10", "01": "b01", "11": "b11"})
+        .join(s[req].rename(columns={"00": "sd00", "10": "sd10", "01": "sd01", "11": "sd11"}))
+        .join(n[req].rename(columns={"00": "n00", "10": "n10", "01": "n01", "11": "n11"}))
+        .reset_index()
+    )
+    return CornerizeResult(
+        per_corner=per_corner,
+        points=points,
+        chosen_time=chosen_time,
+        time_warning=warn_note,
+    )

reader_workbench/domains/logic/four_state_vector/treatment_semantics.py

@@ -0,0 +1,51 @@
+"""Bind metric-neutral experiment states to the four-state four-state vector contract."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class FourStateVectorTreatmentSemantics:
+    treatment_column: str
+    corners: dict[str, str]
+    case_sensitive: bool
+
+    def inject(self, config: dict[str, Any]) -> dict[str, Any]:
+        """Return a copy of ``config`` with the resolved treatment contract."""
+
+        resolved = dict(config)
+        resolved["treatment_column"] = self.treatment_column
+        resolved["treatment_map"] = dict(self.corners)
+        resolved["treatment_case_sensitive"] = self.case_sensitive
+        return resolved
+
+
+def bind_four_state_vector_treatment_semantics(
+    *,
+    state_ids: Sequence[str],
+    source_column: str,
+    source_values: Mapping[str, str],
+    case_sensitive: bool,
+    treatment_column: str | None = None,
+) -> FourStateVectorTreatmentSemantics:
+    """Validate explicit state-space values for the four-state four-state vector transform."""
+
+    normalized_state_ids = tuple(str(state_id) for state_id in state_ids)
+    if normalized_state_ids != ("00", "10", "01", "11"):
+        raise ValueError("four-state vector state space must declare exactly 00, 10, 01, 11 in that order")
+    if set(source_values) != set(normalized_state_ids):
+        raise ValueError("four-state vector state values must define exactly 00, 10, 01, and 11")
+    column = treatment_column or source_column
+    if not isinstance(column, str) or not column.strip():
+        raise ValueError("four_state_vector treatment column must be a non-empty string")
+    return FourStateVectorTreatmentSemantics(
+        treatment_column=column.strip(),
+        corners={state_id: str(source_values[state_id]) for state_id in normalized_state_ids},
+        case_sensitive=bool(case_sensitive),
+    )
+
+
+__all__ = ["FourStateVectorTreatmentSemantics", "bind_four_state_vector_treatment_semantics"]

reader_workbench/domains/logic/four_state_vector/validation.py

@@ -0,0 +1,19 @@
+"""Shared validation for strict four-state vector dataframe contracts."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from reader_workbench.errors import FourStateVectorError
+
+
+def require_intensity_delta_column(frame: pd.DataFrame) -> None:
+    column = "intensity_log2_offset_delta"
+    if column not in frame.columns:
+        raise FourStateVectorError(
+            f"four-state vector input requires column {column!r}. "
+            "Regenerate an logic.four_state_vector.v1 table instead of inferring a default."
+        )
+
+
+__all__ = ["require_intensity_delta_column"]

reader_workbench/domains/logic/logic_symmetry/__init__.py

@@ -0,0 +1,3 @@
+from .main import render_logic_symmetry, summarize_logic_symmetry
+
+__all__ = ["render_logic_symmetry", "summarize_logic_symmetry"]

reader_workbench/domains/logic/logic_symmetry/encodings.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+
+@dataclass(frozen=True)
+class EncodingConfig:
+    size_by: str  # "log_r" | "cv" | "fixed"
+    size_fixed: float
+    hue: str | None  # None | column name
+    alpha_by: str | None
+    alpha_min: float
+    alpha_max: float
+    shape_by: str | None
+    shape_cycle: list[str]
+    shape_max_categories: int | None
+
+
+def _scale_to_range(values: pd.Series, vmin: float, vmax: float, lo: float, hi: float) -> pd.Series:
+    if values.empty or np.all(values == values.iloc[0]):
+        return pd.Series([lo] * len(values), index=values.index, dtype=float)
+    # guard inf/nan
+    s = values.replace([np.inf, -np.inf], np.nan).fillna(vmin)
+    s = s.clip(lower=vmin, upper=vmax)
+    norm = (s - vmin) / max(vmax - vmin, 1e-12)
+    return lo + norm * (hi - lo)
+
+
+def _compute_size(df: pd.DataFrame, cfg: EncodingConfig) -> pd.Series:
+    if cfg.size_by == "fixed":
+        return pd.Series([float(cfg.size_fixed)] * len(df), index=df.index, dtype=float)
+    elif cfg.size_by == "log_r":
+        # Robustly scale log_r into visually distinct point areas
+        v = df["log_r"].clip(lower=0.0)
+        vmax = float(np.nanpercentile(v, 95)) if len(v) else 1.0
+        return _scale_to_range(v, 0.0, max(vmax, 1e-6), 40.0, 300.0)
+    elif cfg.size_by == "cv":
+        v = df["cv"].clip(lower=0.0)
+        vmax = float(np.nanpercentile(v, 95)) if len(v) else 1.0
+        return _scale_to_range(v, 0.0, max(vmax, 1e-6), 40.0, 300.0)
+    raise ValueError(f"Unknown size_by '{cfg.size_by}'")
+
+
+def _compute_alpha(df: pd.DataFrame, cfg: EncodingConfig) -> pd.Series:
+    if not cfg.alpha_by:
+        return pd.Series([cfg.alpha_max] * len(df), index=df.index, dtype=float)
+    col = cfg.alpha_by
+    if col not in df.columns:
+        raise ValueError(f"alpha_by refers to missing column '{col}'")
+    # Order categories numerically if possible (batch typically numeric)
+    series = df[col]
+    try:
+        order = np.sort(series.astype(float).unique())
+        order = [float(x) for x in order]
+        order_map = {v: i for i, v in enumerate(order)}
+        keys = series.astype(float).map(order_map)
+    except Exception:
+        cats = pd.Categorical(series.astype(str))
+        keys = pd.Series(cats.codes, index=series.index)  # -1 for NaN
+    kmin, kmax = float(keys.min()), float(keys.max())
+    return _scale_to_range(keys.astype(float), kmin, kmax, cfg.alpha_min, cfg.alpha_max)
+
+
+def _compute_shape(df: pd.DataFrame, cfg: EncodingConfig) -> pd.Series:
+    if not cfg.shape_by:
+        return pd.Series(["o"] * len(df), index=df.index, dtype=object)
+    col = cfg.shape_by
+    if col not in df.columns:
+        raise ValueError(f"shape_by refers to missing column '{col}'")
+    cats = pd.Categorical(df[col].astype(str))
+    ncat = int(len(cats.categories))
+    if cfg.shape_max_categories is not None and ncat > int(cfg.shape_max_categories):
+        raise ValueError(
+            f"shape_by={col!r} has {ncat} categories, exceeding shape_max_categories={cfg.shape_max_categories}"
+        )
+    if ncat > len(cfg.shape_cycle):
+        raise ValueError(
+            f"Not enough markers in shape_cycle ({len(cfg.shape_cycle)}) for {ncat} categories; extend the cycle or lower categories."
+        )
+    mapping = {cat: cfg.shape_cycle[i] for i, cat in enumerate(cats.categories)}
+    return pd.Series([mapping[str(v)] for v in cats.astype(str)], index=df.index, dtype=object)
+
+
+def apply_encodings(df_points: pd.DataFrame, cfg: EncodingConfig) -> pd.DataFrame:
+    out = df_points.copy()
+    out["size_value"] = _compute_size(out, cfg)
+    out["alpha_value"] = _compute_alpha(out, cfg)
+    out["hue_value"] = (out[cfg.hue] if cfg.hue else pd.Series([None] * len(out), index=out.index)).astype(object)
+    out["shape_value"] = _compute_shape(out, cfg)
+    return out