reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/domains/logic/four_state_vector/builder.py

@@ -0,0 +1,321 @@
+"""Pure four-state vector builder: tidy data to vector."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from .config import FourStateVectorConfig, load_four_state_vector_config
+from .math import compute_four_state_vector
+from .reference import compute_reference_table, resolve_reference_design_id
+from .selection import CornerizeResult, cornerize_and_aggregate
+
+
+def _assert_same_times(time_a: float | None, time_b: float | None) -> None:
+    if time_a is None and time_b is None:
+        return
+    if time_a is None or time_b is None:
+        raise ValueError("four-state vector: logic and intensity selections produced different times.")
+    ta = float(time_a)
+    tb = float(time_b)
+    if not np.isclose(ta, tb, rtol=0, atol=1e-9):
+        raise ValueError(f"four-state vector: logic and intensity channels selected different times: {ta} vs {tb}")
+
+
+def _attach_sequence(vector: pd.DataFrame, tidy_df: pd.DataFrame, *, design_by: list[str]) -> pd.DataFrame:
+    # If vector already has a usable 'sequence' column, keep it.
+    if "sequence" in vector.columns and vector["sequence"].notna().any():
+        return vector
+
+    if "sequence" not in tidy_df.columns:
+        return vector
+
+    idx_cols = [c for c in design_by if c in tidy_df.columns]
+    if not idx_cols:
+        return vector
+
+    seq_map = (
+        tidy_df[idx_cols + ["sequence"]].dropna(subset=["sequence"]).drop_duplicates(subset=idx_cols, keep="first")
+    )
+
+    merged = vector.merge(seq_map, on=idx_cols, how="left", suffixes=("", "_ref"))
+    # Prefer existing 'sequence' if present; otherwise use attached value
+    if "sequence_ref" in merged.columns:
+        if "sequence" not in merged.columns:
+            merged["sequence"] = merged["sequence_ref"]
+        else:
+            merged["sequence"] = merged["sequence"].fillna(merged["sequence_ref"])
+        merged = merged.drop(columns=["sequence_ref"])
+
+    return merged
+
+
+def _reorder_and_filter(
+    vector: pd.DataFrame,
+    *,
+    design_by: list[str],
+    ref_design_id: str | None,
+    exclude_reference: bool,
+) -> pd.DataFrame:
+    """
+    Apply user-requested:
+      - drop REF design_id rows
+      - reorder columns to:
+        design_id, sequence, time_selected_h, reference_design_id, r_logic, v00, v10, v01, v11,
+        y00_star, y10_star, y01_star, y11_star, flat_logic (then keep remaining columns)
+    """
+    label_col = design_by[0]
+
+    df = vector.copy()
+
+    # Exclude REF (if specified)
+    if exclude_reference and ref_design_id is not None and label_col in df.columns:
+        df = df[df[label_col].astype(str) != str(ref_design_id)].copy()
+
+    # Ensure 'sequence' exists even if missing upstream
+    if "sequence" not in df.columns:
+        df["sequence"] = pd.NA
+
+    if "reference_sequence" in df.columns:
+        df = df.drop(columns=["reference_sequence"])
+
+    if label_col not in df.columns:
+        raise ValueError(f"four-state vector: expected label column '{label_col}' in vector output.")
+
+    desired = [
+        label_col,
+        "sequence",
+        "time_selected_h",
+        "reference_design_id",
+        "r_logic",
+        "v00",
+        "v10",
+        "v01",
+        "v11",
+        "y00_star",
+        "y10_star",
+        "y01_star",
+        "y11_star",
+        "flat_logic",
+    ]
+
+    # Reorder preferred columns first, then keep remaining diagnostics/metadata.
+    front = [c for c in desired if c in df.columns]
+    rest = [c for c in df.columns if c not in front]
+    out = df[front + rest].copy()
+
+    # Final tidy: drop duplicates just in case and reset index
+    out = out.drop_duplicates().reset_index(drop=True)
+    return out
+
+
+def _anchors_payload(anchor_table: pd.DataFrame | None) -> dict[str, float] | None:
+    if anchor_table is None or anchor_table.empty:
+        return None
+    row = anchor_table.iloc[0]
+    return {
+        "00": float(row.get("b00")),
+        "10": float(row.get("b10")),
+        "01": float(row.get("b01")),
+        "11": float(row.get("b11")),
+    }
+
+
+@dataclass(frozen=True)
+class FourStateVectorBuildResult:
+    vector: pd.DataFrame
+    log: dict[str, Any]
+    cfg: FourStateVectorConfig
+    sel_logic: CornerizeResult
+    sel_int: CornerizeResult
+    ref_design_id: str | None
+
+
+def build_four_state_vector_from_tidy(
+    tidy_df: pd.DataFrame, xform_cfg: Mapping[str, Any]
+) -> FourStateVectorBuildResult:
+    """
+    Shared four-state vector builder for pipeline + notebooks.
+    Returns vector + log payload + selection diagnostics without writing to disk.
+    """
+    cfg = load_four_state_vector_config(xform_cfg)
+
+    # 1) Cornerize + aggregate (LOGIC channel)
+    sel_logic = cornerize_and_aggregate(
+        tidy_df,
+        design_by=cfg.design_by,
+        treatment_map=cfg.treatment_map,
+        case_sensitive=cfg.treatment_case_sensitive,
+        preferred_treatment_column=cfg.treatment_column,
+        time_column=cfg.time_column,
+        channel=cfg.response.logic_channel,
+        target_time_h=cfg.target_time_h,
+        time_mode=cfg.time_mode,
+        time_tolerance_h=cfg.time_tolerance_h,
+        require_all_corners_per_design=cfg.require_all_corners_per_design,
+    )
+
+    # 2) Cornerize + aggregate (INTENSITY channel)
+    sel_int = cornerize_and_aggregate(
+        tidy_df,
+        design_by=cfg.design_by,
+        treatment_map=cfg.treatment_map,
+        case_sensitive=cfg.treatment_case_sensitive,
+        preferred_treatment_column=cfg.treatment_column,
+        time_column=cfg.time_column,
+        channel=cfg.response.intensity_channel,
+        target_time_h=cfg.target_time_h,
+        time_mode=cfg.time_mode,
+        time_tolerance_h=cfg.time_tolerance_h,
+        require_all_corners_per_design=cfg.require_all_corners_per_design,
+    )
+
+    # 3) Safety: same chosen snapshot times
+    _assert_same_times(sel_logic.chosen_time, sel_int.chosen_time)
+
+    tol_note = sel_logic.time_warning
+
+    # 4) Compute vector (logic from logic channel, y* from intensity channel + anchors)
+    ref_raw = resolve_reference_design_id(tidy_df, design_by=cfg.design_by, ref_label=cfg.reference.design_id)
+    vector = compute_four_state_vector(
+        points_logic=sel_logic.points,
+        points_intensity=sel_int.points,
+        per_corner_intensity=sel_int.per_corner,
+        design_by=cfg.design_by,
+        reference_design_id=ref_raw,
+        reference_stat=cfg.reference.observation_stat,
+        eps_ratio=cfg.eps_ratio,
+        eps_range=cfg.eps_range,
+        eps_ref=cfg.eps_ref,
+        eps_abs=cfg.eps_abs,
+        ref_add_alpha=cfg.ref_add_alpha,
+        log2_offset_delta=cfg.log2_offset_delta,
+    )
+
+    # 4a) Attach selected snapshot time
+    if sel_logic.chosen_time is not None:
+        vector["time_selected_h"] = float(sel_logic.chosen_time)
+        vector["time_selected_h"] = pd.to_numeric(vector["time_selected_h"], errors="coerce").astype(float)
+
+    # 4b) Attach 'sequence' if available in the tidy inputs
+    vector = _attach_sequence(vector, tidy_df, design_by=cfg.design_by)
+    # 4b.5) Persist intensity log2 offset delta for downstream enforcement
+    if "intensity_log2_offset_delta" not in vector.columns:
+        vector["intensity_log2_offset_delta"] = float(cfg.log2_offset_delta)
+    # Carry additional metadata columns if requested
+    idx_cols = [c for c in cfg.design_by if c in tidy_df.columns]
+    for col in cfg.carry_metadata or []:
+        if col in tidy_df.columns and col not in vector.columns:
+            meta = tidy_df[idx_cols + [col]].dropna(subset=[col]).drop_duplicates(subset=idx_cols, keep="first")
+            vector = vector.merge(meta, on=idx_cols, how="left", validate="m:1")
+
+    # 4c) Reference provenance columns
+    if "reference_design_id" not in vector.columns:
+        vector["reference_design_id"] = ref_raw
+
+    # 4d) Apply requested filtering and column order
+    vector_out = _reorder_and_filter(
+        vector,
+        design_by=cfg.design_by,
+        ref_design_id=ref_raw,
+        exclude_reference=cfg.exclude_reference_from_output,
+    )
+
+    # 5) Compose a log payload (unchanged)
+    # Compute r_logic distribution for quick provenance metrics
+    r_desc = vector_out["r_logic"].describe().to_dict() if "r_logic" in vector_out.columns else {}
+    flat_count = 0
+    flat_fraction = 0.0
+    flat_samples: list[str] = []
+    if "flat_logic" in vector_out.columns and len(vector_out) > 0:
+        flat_mask = vector_out["flat_logic"].astype(bool)
+        flat_count = int(flat_mask.sum())
+        flat_fraction = float(flat_count) / float(len(vector_out)) if len(vector_out) else 0.0
+        label_col = cfg.design_by[0] if cfg.design_by else None
+        if label_col and label_col in vector_out.columns and flat_count > 0:
+            flat_samples = vector_out.loc[flat_mask, label_col].astype(str).dropna().drop_duplicates().head(5).tolist()
+
+    log_payload: dict[str, Any] = {
+        "operation": "four_state_vector",
+        "design_by": cfg.design_by,
+        "time_column": cfg.time_column,
+        "channels": {
+            "logic": cfg.response.logic_channel,
+            "intensity": cfg.response.intensity_channel,
+        },
+        "treatment_map": cfg.treatment_map,
+        "treatment_case_sensitive": cfg.treatment_case_sensitive,
+        "time": {
+            "target_time_h": cfg.target_time_h,
+            "mode": cfg.time_mode,
+            "tolerance_h": cfg.time_tolerance_h,
+            "tolerance_policy": "soft-warning",
+            "chosen_time": sel_logic.chosen_time,
+            "out_of_tolerance": tol_note,
+        },
+        "reference": {
+            "design_id": cfg.reference.design_id,
+            "design_id_resolved": ref_raw,
+            "observation_stat": cfg.reference.observation_stat,
+            "anchors": _anchors_payload(
+                compute_reference_table(
+                    sel_int.per_corner,
+                    design_by=cfg.design_by,
+                    ref_design_id=ref_raw,
+                    stat=cfg.reference.observation_stat,
+                )
+                if ref_raw is not None
+                else None,
+            ),
+        },
+        "eps": {
+            "ratio": cfg.eps_ratio,
+            "range": cfg.eps_range,
+            "eta": cfg.eps_range,
+            "ref": cfg.eps_ref,
+            "abs": cfg.eps_abs,
+        },
+        "semantics": {
+            "v": {
+                "source_channel": cfg.response.logic_channel,
+                "transform": "u = log2(L); v = (u - min(u))/((max(u)-min(u)) + eta)",
+                "persisted_units": "unit-interval [0,1] (not log)",
+                "eta": cfg.eps_range,
+            },
+            "y_star": {
+                "source_channel": cfg.response.intensity_channel,
+                "transform": "y* = log2( ((I + eps_abs)/max(A + alpha, eps_ref)) + delta )",
+                "persisted_units": "log2",
+                "alpha": cfg.ref_add_alpha,
+                "delta": cfg.log2_offset_delta,
+            },
+            "r_logic": {
+                "definition": "per design dynamic range on LOGIC (linear, ε-guarded): max(L_i)/min(L_i)",
+                "epsilon_guard_ratio": cfg.eps_ratio,
+                "stats_over_vector": r_desc,
+            },
+        },
+        "rows": {
+            "per_corner_logic": int(len(sel_logic.per_corner)),
+            "per_corner_intensity": int(len(sel_int.per_corner)),
+            "points_logic": int(len(sel_logic.points)),
+            "points_intensity": int(len(sel_int.points)),
+            "vector": int(len(vector_out)),
+        },
+        "flat_logic_count": int(flat_count),
+        "flat_logic_fraction": float(flat_fraction),
+        "flat_logic_sample_design_ids": flat_samples,
+    }
+
+    return FourStateVectorBuildResult(
+        vector=vector_out,
+        log=log_payload,
+        cfg=cfg,
+        sel_logic=sel_logic,
+        sel_int=sel_int,
+        ref_design_id=ref_raw,
+    )

reader_workbench/domains/logic/four_state_vector/collection/__init__.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from .constants import VECTOR_CHANNELS
+from .model import FourStateVectorCollection, FourStateVectorSource
+from .sources import collect_four_state_vector_sources
+
+
+def render_four_state_vector_collection_heatmap(*args, **kwargs):
+    from .render import render_four_state_vector_collection_heatmap as render  # noqa: PLC0415
+
+    return render(*args, **kwargs)
+
+
+__all__ = [
+    "FourStateVectorCollection",
+    "FourStateVectorSource",
+    "VECTOR_CHANNELS",
+    "collect_four_state_vector_sources",
+    "render_four_state_vector_collection_heatmap",
+]

reader_workbench/domains/logic/four_state_vector/collection/checks.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import math
+
+import pandas as pd
+
+from reader_workbench.errors import FourStateVectorError
+
+from ..validation import require_intensity_delta_column
+from .constants import REQUIRED_VECTOR_COLUMNS
+
+
+def require_vector_columns(frame: pd.DataFrame) -> None:
+    require_intensity_delta_column(frame)
+    missing = [column for column in REQUIRED_VECTOR_COLUMNS if column not in frame.columns]
+    if missing:
+        raise FourStateVectorError(f"four-state vector input requires columns: {', '.join(missing)}.")
+
+
+def require_normalized_frame(frame: pd.DataFrame) -> None:
+    require_vector_columns(frame)
+    source_columns = {"source_resource_id", "source_experiment_id"} & set(frame.columns)
+    missing = ([] if source_columns else ["source_resource_id or source_experiment_id"]) + (
+        [] if "row_label" in frame.columns else ["row_label"]
+    )
+    if missing:
+        raise FourStateVectorError(f"four-state vector collection requires normalized columns: {', '.join(missing)}.")
+    if frame.empty:
+        raise FourStateVectorError("four-state vector collection has no rows to plot.")
+
+
+def finite_numeric_column(
+    series: pd.Series,
+    *,
+    column: str,
+    source: str,
+    allow_nan: bool = False,
+) -> pd.Series:
+    values = pd.to_numeric(series, errors="coerce")
+    coerced_to_nan = series.notna() & values.isna()
+    nonfinite = values.notna() & ~values.fillna(0.0).map(lambda value: math.isfinite(float(value)))
+    invalid = coerced_to_nan | nonfinite
+    if not allow_nan:
+        invalid |= values.isna()
+    if invalid.any():
+        raise FourStateVectorError(
+            f"four-state vector collection column {column!r} must be finite numeric values in {source}."
+        )
+    return values.astype(float)

reader_workbench/domains/logic/four_state_vector/collection/constants.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+VECTOR_CHANNELS = ("v00", "v10", "v01", "v11", "y00_star", "y10_star", "y01_star", "y11_star")
+REQUIRED_VECTOR_COLUMNS = (
+    "design_id",
+    "reference_design_id",
+    "intensity_log2_offset_delta",
+    "r_logic",
+    *VECTOR_CHANNELS,
+    "flat_logic",
+)
+
+METADATA_COLUMNS = (
+    "source_index",
+    "source_resource_id",
+    "source_experiment_id",
+    "source_record_id",
+    "source_record_revision_digest",
+    "source_row_index",
+    "row_label",
+    "design_id",
+    "sequence",
+    "id",
+    "time_selected_h",
+    "reference_design_id",
+    "intensity_log2_offset_delta",
+    "r_logic",
+    "flat_logic",
+)

reader_workbench/domains/logic/four_state_vector/collection/model.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import pandas as pd
+
+
+@dataclass(frozen=True)
+class FourStateVectorSource:
+    resource_id: str
+    experiment_id: str
+    record_id: str
+    revision_digest: str
+    frame: pd.DataFrame
+
+
+@dataclass(frozen=True)
+class FourStateVectorCollection:
+    frame: pd.DataFrame