reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/domains/logic/logic_symmetry/extract_corners.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+import pandas as pd
+
+from reader_workbench.domains.logic.treatment_columns import choose_treatment_column, normalize_treatment_series
+
+LOG = logging.getLogger(__name__)
+
+REQUIRED_BASE_COLS = ["position", "time", "channel", "value"]
+
+
+@dataclass(frozen=True)
+class MappingConfig:
+    treatment_map: dict[str, str]  # keys: "00","10","01","11" → exact data labels
+    case_sensitive: bool
+    treatment_column: str | None
+    design_by: list[str]
+    batch_col: str
+    response_channel: str
+    observation_stat: str  # "mean" | "median"
+
+
+def _assert_required_columns(df: pd.DataFrame, cfg: MappingConfig) -> None:
+    missing = [c for c in REQUIRED_BASE_COLS if c not in df.columns]
+    if missing:
+        raise ValueError(f"Input DataFrame missing required columns: {missing}")
+    meta_missing = [c for c in cfg.design_by if c not in df.columns]
+    if meta_missing:
+        raise ValueError(f"Missing design_by columns: {meta_missing}")
+    if cfg.batch_col not in df.columns:
+        raise ValueError(f"Missing required batch column '{cfg.batch_col}'")
+
+    # Batch must be numeric ordinal
+    try:
+        pd.to_numeric(df[cfg.batch_col])
+    except Exception as err:
+        raise ValueError(f"Batch column '{cfg.batch_col}' must be numeric (0,1,2,...)") from err
+
+    if cfg.response_channel not in df["channel"].unique().tolist():
+        raise ValueError(f"response_channel '{cfg.response_channel}' not present in 'channel' column")
+
+
+def _observation_aggregate(series: pd.Series, how: str) -> float:
+    if how == "median":
+        return float(series.median())
+    return float(series.mean())
+
+
+def _sd(series: pd.Series) -> float:
+    # population-like SD with ddof=1 when n>1; 0 otherwise
+    n = series.size
+    if n <= 1:
+        return 0.0
+    return float(series.std(ddof=1))
+
+
+def _fail_if_multiple_times(df: pd.DataFrame, group_cols: list[str]) -> None:
+    """
+    Enforce: exactly ONE time per (design..., batch, treatment).
+    If violations exist, raise with the list of offending groups and their times.
+    """
+    chk = df.groupby(group_cols)["time"].nunique().reset_index(name="n_times")
+    bad = chk[chk["n_times"] > 1]
+    if not bad.empty:
+        offenders = []
+        for _, row in bad.iterrows():
+            filt = (df[group_cols] == row[group_cols]).all(axis=1)
+            times = sorted(df.loc[filt, "time"].unique().tolist())
+            key_str = ", ".join(f"{c}={row[c]!r}" for c in group_cols)
+            offenders.append(f"{key_str} → times={times}")
+        msg = "Snapshot violation: more than one 'time' for some (design…, batch, treatment).\n" + "\n".join(
+            offenders[:50]
+        )
+        raise ValueError(msg)
+
+
+def resolve_and_aggregate(df: pd.DataFrame, cfg: MappingConfig) -> tuple[pd.DataFrame, pd.DataFrame]:
+    """
+    Returns:
+        points_df: one row per (design_by…, batch) with corner means, SDs, counts
+        per_corner_df: per (design…, batch, corner) aggregated table
+    """
+    _assert_required_columns(df, cfg)
+
+    # Filter to the channel
+    before = len(df)
+    df = df[df["channel"] == cfg.response_channel].copy()
+    LOG.info("• extract: filtered to channel %r → %d/%d rows", cfg.response_channel, len(df), before)
+    if df.empty:
+        raise ValueError(f"No rows for response_channel '{cfg.response_channel}'")
+
+    treatment_col = choose_treatment_column(
+        df,
+        cfg.treatment_map,
+        case_sensitive=cfg.case_sensitive,
+        preferred=cfg.treatment_column,
+    )
+
+    # Keep only rows whose treatment matches one of the mapped labels
+    map_vals = list(cfg.treatment_map.values())
+    if not cfg.case_sensitive:
+        df["_t_norm"] = normalize_treatment_series(df[treatment_col])
+        map_norm = [str(v).strip().casefold() for v in map_vals]
+        df = df[df["_t_norm"].isin(map_norm)].copy()
+    else:
+        df = df[df[treatment_col].astype(str).isin([str(v) for v in map_vals])].copy()
+    LOG.info(
+        "• extract: kept rows matching treatment_map labels → %d rows; unique treatments kept=%d",
+        len(df),
+        df[treatment_col].nunique(),
+    )
+
+    if df.empty:
+        counts = (
+            df[treatment_col].value_counts().to_string() if treatment_col in df.columns else "(no treatment column)"
+        )
+        raise ValueError(f"No rows match any treatment_map labels. Check spelling/case.\nAvailable counts:\n{counts}")
+
+    # Add 'corner' column via reverse lookup (value→corner)
+    rev = {}
+    seen = set()
+    for corner in ("00", "10", "01", "11"):
+        val = cfg.treatment_map.get(corner)
+        if val in seen:
+            raise ValueError(f"Duplicate treatment_map values detected: {val!r} is used by multiple corners")
+        seen.add(val)
+        rev[str(val) if cfg.case_sensitive else str(val).strip().casefold()] = corner
+
+    if cfg.case_sensitive:
+        df["corner"] = df[treatment_col].astype(str).map(lambda x: rev.get(x))
+    else:
+        df["corner"] = normalize_treatment_series(df[treatment_col]).map(lambda x: rev.get(x))
+
+    # Enforce snapshot rule per (design…, batch, treatment/corner)
+    group_cols = cfg.design_by + [cfg.batch_col, "corner"]
+    _fail_if_multiple_times(df, group_cols)
+
+    # Aggregate observations per corner at that unique time.
+    agg_rows = []
+    for keys, g in df.groupby(group_cols, dropna=False):
+        # There is exactly one time by construction; keep it
+        t_unique = float(g["time"].iloc[0])
+        val = pd.to_numeric(g["value"], errors="coerce").dropna()
+        if val.empty:
+            key_str = ", ".join(f"{c}={k!r}" for c, k in zip(group_cols, keys, strict=False))
+            raise ValueError(f"Non-numeric or missing 'value' for group: {key_str}")
+        mean_or_med = _observation_aggregate(val, cfg.observation_stat)
+        sd = _sd(val)
+        n = int(val.size)
+        record = dict(zip(group_cols, keys, strict=False))
+        record.update(time=t_unique, y_mean=mean_or_med, y_sd=sd, y_n=n)
+        agg_rows.append(record)
+
+    per_corner = pd.DataFrame.from_records(agg_rows)
+    LOG.info("• extract: per-corner aggregates = %d rows (design×batch×corner)", len(per_corner))
+
+    # Pivot to wide per (design…, batch)
+    idx_cols = cfg.design_by + [cfg.batch_col]
+    pivot_mean = per_corner.pivot_table(index=idx_cols, columns="corner", values="y_mean", aggfunc="first")
+    pivot_sd = per_corner.pivot_table(index=idx_cols, columns="corner", values="y_sd", aggfunc="first")
+    pivot_n = per_corner.pivot_table(index=idx_cols, columns="corner", values="y_n", aggfunc="first")
+
+    # Ensure all four corners present for every group (fail-fast)
+    required = ["00", "10", "01", "11"]
+    missing_groups = []
+    for idx, row in pivot_mean.iterrows():
+        missing = [c for c in required if pd.isna(row.get(c))]
+        if missing:
+            key_str = ", ".join(
+                f"{c}={v!r}" for c, v in zip(idx_cols, (idx if isinstance(idx, tuple) else (idx,)), strict=False)
+            )
+            missing_groups.append(f"{key_str} → missing corners: {missing}")
+    if missing_groups:
+        LOG.error("• extract: incomplete corner set for some groups (%d shown):", len(missing_groups))
+        for line in missing_groups[:10]:
+            LOG.error("    %s", line)
+        msg = "Incomplete corner set: some (design…, batch) groups lack one or more of {00,10,01,11}.\n" + "\n".join(
+            missing_groups[:50]
+        )
+        raise ValueError(msg)
+
+    pivot_mean = pivot_mean[required].rename(columns={"00": "b00", "10": "b10", "01": "b01", "11": "b11"})
+    pivot_sd = pivot_sd[required].rename(columns={"00": "sd00", "10": "sd10", "01": "sd01", "11": "sd11"})
+    pivot_n = pivot_n[required].rename(columns={"00": "n00", "10": "n10", "01": "n01", "11": "n11"}).astype(int)
+
+    points = pivot_mean.join(pivot_sd, how="left").join(pivot_n, how="left").reset_index()
+
+    LOG.info("• extract: wide table rows (designxbatch) = %d", len(points))
+    return points, per_corner

reader_workbench/domains/logic/logic_symmetry/main.py

@@ -0,0 +1,236 @@
+"""Pure logic-symmetry summary and figure operations."""
+
+from __future__ import annotations
+
+import logging
+
+import pandas as pd
+
+from .encodings import EncodingConfig, apply_encodings
+from .extract_corners import MappingConfig, resolve_and_aggregate
+from .metrics import CornerStats, compute_metrics
+from .overlay import OverlayStyle
+from .prep import prepare_for_logic_symmetry
+from .render import VisualConfig, draw_scatter
+
+LOG = logging.getLogger(__name__)
+
+
+def _dget(values: dict | None, key: str, default):
+    if values is None:
+        return default
+    if key in values and values[key] is not None:
+        return values[key]
+    return default
+
+
+def _pick_baseline_corner(row: pd.Series) -> str:
+    corners = ("b00", "b10", "b01", "b11")
+    values = {corner: float(row[corner]) for corner in corners}
+    minimum = min(values.values())
+    for corner in corners:
+        if values[corner] == minimum:
+            return corner.removeprefix("b")
+    return "00"
+
+
+def summarize_logic_symmetry(
+    df: pd.DataFrame,
+    *,
+    response_channel: str,
+    design_by: list[str] | None = None,
+    batch_col: str = "batch",
+    treatment_column: str | None = None,
+    treatment_map: dict[str, str] | None = None,
+    treatment_case_sensitive: bool = True,
+    observation_stat: str = "mean",
+    prep: dict | None = None,
+) -> pd.DataFrame:
+    """Compute one contract-ready logic-symmetry row per design and batch."""
+
+    design_by = list(design_by or ["design_id"])
+    if treatment_map is None or set(treatment_map) != {"00", "10", "01", "11"}:
+        raise ValueError(
+            "treatment_map must be provided with keys {'00','10','01','11'} and single exact labels as values"
+        )
+    if observation_stat not in {"mean", "median"}:
+        raise ValueError(f"observation_stat must be 'mean' or 'median', got {observation_stat!r}")
+
+    LOG.info("logic_symmetry: computing summary")
+    LOG.info("response_channel=%s | design_by=%s | batch_col=%s", response_channel, design_by, batch_col)
+    LOG.info(
+        "state_map: 00=%r | 10=%r | 01=%r | 11=%r | case_sensitive=%s",
+        treatment_map["00"],
+        treatment_map["10"],
+        treatment_map["01"],
+        treatment_map["11"],
+        treatment_case_sensitive,
+    )
+
+    if prep and bool(prep.get("enable", False)):
+        df = prepare_for_logic_symmetry(
+            df,
+            response_channel=response_channel,
+            design_by=design_by,
+            batch_col=batch_col,
+            treatment_map=treatment_map,
+            treatment_column=treatment_column,
+            mode=str(prep.get("mode", "last")),
+            target_time=prep.get("target_time"),
+            tolerance=float(prep.get("tolerance", 0.51)),
+            align_corners=bool(prep.get("align_corners", False)),
+            case_sensitive=bool(prep.get("case_sensitive_treatments", treatment_case_sensitive)),
+            time_column=str(prep.get("time_column", "time")),
+        )
+        LOG.info("logic_symmetry: rows after time selection=%d", len(df))
+
+    mapping = MappingConfig(
+        treatment_map=treatment_map,
+        case_sensitive=treatment_case_sensitive,
+        treatment_column=treatment_column,
+        design_by=design_by,
+        batch_col=batch_col,
+        response_channel=response_channel,
+        observation_stat=observation_stat,
+    )
+    points, _ = resolve_and_aggregate(df, mapping)
+    LOG.info("logic_symmetry: aggregated groups=%d", len(points))
+
+    metrics = []
+    for _, row in points.iterrows():
+        metrics.append(
+            compute_metrics(
+                CornerStats(
+                    b00=float(row["b00"]),
+                    b10=float(row["b10"]),
+                    b01=float(row["b01"]),
+                    b11=float(row["b11"]),
+                    n00=int(row["n00"]),
+                    n10=int(row["n10"]),
+                    n01=int(row["n01"]),
+                    n11=int(row["n11"]),
+                    sd00=float(row["sd00"]),
+                    sd10=float(row["sd10"]),
+                    sd01=float(row["sd01"]),
+                    sd11=float(row["sd11"]),
+                )
+            )
+        )
+    metric_table = pd.DataFrame.from_records(metrics, index=points.index)
+    summary = pd.concat([points.reset_index(drop=True), metric_table.reset_index(drop=True)], axis=1)
+    summary["baseline_corner"] = summary.apply(_pick_baseline_corner, axis=1).astype("string")
+    summary["baseline_value"] = summary[["b00", "b10", "b01", "b11"]].min(axis=1).astype(float)
+
+    value_columns = [
+        "n00",
+        "n10",
+        "n01",
+        "n11",
+        "b00",
+        "b10",
+        "b01",
+        "b11",
+        "sd00",
+        "sd10",
+        "sd01",
+        "sd11",
+        "r",
+        "log_r",
+        "cv",
+        "u00",
+        "u10",
+        "u01",
+        "u11",
+        "L",
+        "A",
+        "baseline_corner",
+        "baseline_value",
+    ]
+    identity_columns = list(dict.fromkeys([*design_by, batch_col]))
+    return summary[[*identity_columns, *value_columns]].copy()
+
+
+def render_logic_symmetry(
+    table: pd.DataFrame,
+    *,
+    title: str = "Logic symmetry",
+    dispersion: str = "halo",
+    encodings: dict | None = None,
+    ideals_overlay: dict | None = None,
+    visuals: dict | None = None,
+    figsize: tuple[float, float] = (7, 6),
+    dpi: int = 300,
+):
+    """Render a logic-symmetry figure from a persisted summary table."""
+
+    if dispersion not in {"none", "bars", "halo"}:
+        raise ValueError(f"dispersion must be one of 'none'|'bars'|'halo', got {dispersion!r}")
+
+    hue = _dget(encodings, "hue", None)
+    if hue is None or str(hue).lower() in {"baseline", "baseline_corner", "min", "min_corner"}:
+        hue = "baseline_corner"
+    encoding = EncodingConfig(
+        size_by=str(_dget(encodings, "size_by", "log_r")),
+        size_fixed=float(_dget(encodings, "size_fixed", 80.0)),
+        hue=str(hue),
+        alpha_by=_dget(encodings, "alpha_by", "batch"),
+        alpha_min=float(_dget(encodings, "alpha_min", 0.35)),
+        alpha_max=float(_dget(encodings, "alpha_max", 1.0)),
+        shape_by=_dget(encodings, "shape_by", None),
+        shape_cycle=list(_dget(encodings, "shape_cycle", ["o", "s", "^", "D", "P", "X", "v", "*"])),
+        shape_max_categories=_dget(encodings, "shape_max_categories", None),
+    )
+    for column in {encoding.hue, encoding.alpha_by, encoding.shape_by} - {None}:
+        if column not in table.columns:
+            raise ValueError(f"Logic-symmetry encoding refers to missing column {column!r}")
+    encoded = apply_encodings(table, encoding)
+
+    overlay_enabled = bool(_dget(ideals_overlay, "enable", False))
+    overlay_gate_set = str(_dget(ideals_overlay, "gate_set", "logic_family"))
+    overlay_values = _dget(ideals_overlay, "style", {})
+    overlay_mode = _dget(overlay_values, "mode", None)
+    if overlay_mode is None:
+        overlay_mode = "tiles" if overlay_gate_set.startswith("tiles") else "dot"
+    overlay = OverlayStyle(
+        mode=str(overlay_mode),
+        alpha=float(_dget(overlay_values, "alpha", 0.25)),
+        size=float(_dget(overlay_values, "size", 40.0)),
+        face_color=str(_dget(overlay_values, "face_color", "#FFFFFF")),
+        edge_color=str(_dget(overlay_values, "edge_color", _dget(overlay_values, "color", "#888888"))),
+        show_labels=bool(_dget(overlay_values, "show_labels", True)),
+        label_offset=float(_dget(overlay_values, "label_offset", 0.02)),
+        label_line_height=float(_dget(overlay_values, "label_line_height", 0.018)),
+        label_fontsize=int(_dget(overlay_values, "label_fontsize", 12)),
+        tile_cell_w=float(_dget(overlay_values, "tile_cell_w", 0.035)),
+        tile_cell_h=float(_dget(overlay_values, "tile_cell_h", 0.035)),
+        tile_gap=float(_dget(overlay_values, "tile_gap", 0.0)),
+        tile_edge_width=float(_dget(overlay_values, "tile_edge_width", 0.6)),
+        tiles_stack_multiple=bool(_dget(overlay_values, "tiles_stack_multiple", True)),
+    )
+
+    visual = VisualConfig(
+        xlim=tuple(_dget(visuals, "xlim", (-1.02, 1.02))),
+        ylim=tuple(_dget(visuals, "ylim", (-1.02, 1.02))),
+        grid=bool(_dget(visuals, "grid", True)),
+        color=str(_dget(visuals, "color", "#6e6e6e")),
+        annotate_designs=bool(_dget(visuals, "annotate_designs", False)),
+        design_label_col=_dget(visuals, "design_label_col", None),
+        label_fontsize=int(_dget(visuals, "label_fontsize", 12)),
+        label_offset=float(_dget(visuals, "label_offset", 0.02)),
+        axis_label_fontsize=int(_dget(visuals, "axis_label_fontsize", 16)),
+        tick_label_fontsize=int(_dget(visuals, "tick_label_fontsize", 14)),
+        title_fontsize=int(_dget(visuals, "title_fontsize", 18)),
+        legend_fontsize=int(_dget(visuals, "legend_fontsize", 12)),
+    )
+    figure, _ = draw_scatter(
+        encoded,
+        hue_col=encoding.hue,
+        visuals=visual,
+        dispersion_mode=dispersion,
+        overlay_cfg=overlay if overlay_enabled else None,
+        overlay_gate_set=overlay_gate_set if overlay_enabled else None,
+        title=title,
+        figsize=figsize,
+        dpi=dpi,
+    )
+    return figure

reader_workbench/domains/logic/logic_symmetry/metrics.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+EPS_DEFAULT = 1e-9
+
+
+@dataclass(frozen=True)
+class CornerStats:
+    """Aggregated per-corner numbers for a single (design..., batch)."""
+
+    b00: float
+    b10: float
+    b01: float
+    b11: float
+    n00: int
+    n10: int
+    n01: int
+    n11: int
+    sd00: float
+    sd10: float
+    sd01: float
+    sd11: float
+
+
+def safe_log(x: np.ndarray | float, eps: float = EPS_DEFAULT) -> np.ndarray | float:
+    return np.log(np.maximum(x, eps))
+
+
+def normalize_u(b00: float, b10: float, b01: float, b11: float, eps: float = EPS_DEFAULT) -> tuple[np.ndarray, float]:
+    """
+    Returns:
+        u: np.array([u00,u10,u01,u11]) in [0,1]
+        r: dynamic range (>=1)
+    """
+    b = np.array([b00, b10, b01, b11], dtype=float)
+    b = np.maximum(b, eps)
+
+    m = float(np.min(b))
+    M = float(np.max(b))
+    r = (M / m) if (M > 0 and m > 0) else 1.0
+
+    if r <= 1.0 + 1e-12:
+        # Degenerate range: place all corners mid-scale
+        return np.array([0.5, 0.5, 0.5, 0.5], dtype=float), 1.0
+
+    u = (safe_log(b, eps) - safe_log(m, eps)) / (safe_log(r, eps))
+    u = np.clip(u, 0.0, 1.0)
+    return u, r
+
+
+def logic_asym(u: np.ndarray) -> tuple[float, float]:
+    """
+    L = u11 - 0.5*(u10+u01)
+    A = u10 - u01
+    """
+    u00, u10, u01, u11 = [float(x) for x in u]
+    L = float(u11 - 0.5 * (u10 + u01))
+    A = float(u10 - u01)
+    return float(np.clip(L, -1.0, 1.0)), float(np.clip(A, -1.0, 1.0))
+
+
+def cv_corners(
+    sd00: float, sd10: float, sd01: float, sd11: float, b00: float, b10: float, b01: float, b11: float
+) -> float:
+    """
+    Mean CV across corners using per-corner SD / mean, ignoring corners with n<2 or mean<=0.
+    """
+    pairs = [(sd00, b00), (sd10, b10), (sd01, b01), (sd11, b11)]
+    cvs = []
+    for sd, mean in pairs:
+        if mean > 0:
+            cvs.append(float(sd) / float(mean))
+    if not cvs:
+        return 0.0
+    return float(np.mean(cvs))
+
+
+def compute_metrics(cs: CornerStats, eps: float = EPS_DEFAULT) -> dict[str, float]:
+    u, r = normalize_u(cs.b00, cs.b10, cs.b01, cs.b11, eps=eps)
+    L, A = logic_asym(u)
+    cv = cv_corners(cs.sd00, cs.sd10, cs.sd01, cs.sd11, cs.b00, cs.b10, cs.b01, cs.b11)
+    out = {
+        "r": float(r),
+        "log_r": float(0.0 if r <= 1.0 else safe_log(r)),
+        "L": float(L),
+        "A": float(A),
+        "u00": float(u[0]),
+        "u10": float(u[1]),
+        "u01": float(u[2]),
+        "u11": float(u[3]),
+        "cv": float(max(cv, 0.0)),
+    }
+    return out

reader_workbench/domains/logic/logic_symmetry/overlay.py

@@ -0,0 +1,129 @@
+"""
+Ideal overlay definitions for the logic-symmetry plot.
+
+Adds a tile-rendering mode (4-square horizontal strip for 00,10,01,11) and
+a 'tiles_dual' gate set including antagonistic/negative counterparts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from .metrics import logic_asym
+
+
+@dataclass(frozen=True)
+class OverlayStyle:
+    # mode: "dot" or "tiles" (4-square horizontal strip for 00/10/01/11)
+    mode: str = "dot"
+
+    # shared appearance
+    alpha: float = 0.25
+    face_color: str = "#FFFFFF"
+    edge_color: str = "#888888"
+    show_labels: bool = True
+    label_offset: float = 0.02
+    label_line_height: float = 0.018
+    label_fontsize: int = 12
+
+    # dot-specific
+    size: float = 40.0
+
+    # tile-specific
+    tile_cell_w: float = 0.035
+    tile_cell_h: float = 0.035
+    tile_gap: float = 0.0
+    tile_edge_width: float = 0.6
+    tiles_stack_multiple: bool = True
+
+
+# Base gate sets (u = [u00,u10,u01,u11])
+_GATESETS: dict[str, dict[str, list[float]]] = {
+    "core": {
+        "AND": [0, 0, 0, 1],
+        "OR": [0, 1, 1, 1],
+        "XOR": [0, 1, 1, 0],
+        "SLOPE": [0, 0.5, 0.5, 1.0],
+        "SIG-A": [0, 1, 0, 1],
+        "SIG-B": [0, 0, 1, 1],
+    },
+    "logic_family": {
+        "AND": [0, 0, 0, 1],
+        "OR": [0, 1, 1, 1],
+        "XOR": [0, 1, 1, 0],
+        "NAND": [1, 1, 1, 0],
+        "NOR": [1, 0, 0, 0],
+        "XNOR": [1, 0, 0, 1],
+        "SIG-A": [0, 1, 0, 1],
+        "SIG-B": [0, 0, 1, 1],
+        "SLOPE": [0, 0.5, 0.5, 1.0],
+    },
+    "full16": {
+        "FALSE": [0, 0, 0, 0],
+        "TRUE": [1, 1, 1, 1],
+        "AND": [0, 0, 0, 1],
+        "OR": [0, 1, 1, 1],
+        "XOR": [0, 1, 1, 0],
+        "XNOR": [1, 0, 0, 1],
+        "NAND": [1, 1, 1, 0],
+        "NOR": [1, 0, 0, 0],
+        "A": [0, 1, 0, 1],
+        "NOT A": [1, 0, 1, 0],
+        "B": [0, 0, 1, 1],
+        "NOT B": [1, 1, 0, 0],
+        "A AND NOT B": [0, 1, 0, 0],
+        "NOT A AND B": [0, 0, 1, 0],
+        "A->B": [1, 1, 0, 1],
+        "B->A": [1, 0, 1, 1],
+    },
+}
+
+
+def _invert_u(u: list[float]) -> list[float]:
+    return [float(1.0 - float(x)) for x in u]
+
+
+def _tiles_dual_set() -> dict[str, list[float]]:
+    """OR/NOR, XNOR/AND, SIG-A/NOT A, SIG-B/NOT B, SLOPE/SLOPE− (antagonistic)."""
+    base = {
+        "OR": [0, 1, 1, 1],
+        "NOR": [1, 0, 0, 0],
+        "XNOR": [1, 0, 0, 1],
+        "AND": [0, 0, 0, 1],
+        "SIG-A": [0, 1, 0, 1],
+        "SIG-B": [0, 0, 1, 1],
+        "SLOPE": [0, 0.5, 0.5, 1.0],
+    }
+    dual = {
+        "NAND": [1, 1, 1, 0],
+        "XOR": [0, 1, 1, 0],
+        "NOT A": [1, 0, 1, 0],
+        "NOT B": [1, 1, 0, 0],
+        "SLOPE−": _invert_u(base["SLOPE"]),
+    }
+    out = dict(base)
+    out.update(dual)
+    return out
+
+
+def generate_overlay_points(gate_set: str) -> pd.DataFrame:
+    """
+    Return DataFrame with columns: label, L, A, u  (u = [u00,u10,u01,u11])
+    """
+    if gate_set == "tiles_dual":
+        src = _tiles_dual_set()
+    else:
+        if gate_set not in _GATESETS:
+            valid = list(_GATESETS) + ["tiles_dual"]
+            raise ValueError(f"Unknown gate_set '{gate_set}'. Choose from {valid}")
+        src = _GATESETS[gate_set]
+
+    rows: list[dict[str, object]] = []
+    for label, u in src.items():
+        uu = [float(x) for x in u]
+        L, A = logic_asym(np.array(uu, dtype=float))
+        rows.append({"label": label, "L": L, "A": A, "u": uu})
+    return pd.DataFrame.from_records(rows)