reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/domains/logic/four_state_vector/config.py

@@ -0,0 +1,214 @@
+"""Strict configuration model for the four-state vector transform."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+_CONFIG_KEYS = frozenset(
+    {
+        "carry_metadata",
+        "design_by",
+        "eps_abs",
+        "eps_range",
+        "eps_ratio",
+        "eps_ref",
+        "exclude_reference_from_output",
+        "log2_offset_delta",
+        "ref_add_alpha",
+        "reference",
+        "require_all_corners_per_design",
+        "response",
+        "target_time_h",
+        "time_column",
+        "time_mode",
+        "time_tolerance_h",
+        "treatment_case_sensitive",
+        "treatment_column",
+        "treatment_map",
+    }
+)
+
+
+def _sub(obj: Mapping[str, Any], key: str, *, allowed: frozenset[str]) -> dict[str, Any]:
+    value = obj.get(key)
+    if value is None:
+        return {}
+    if isinstance(value, Mapping):
+        payload = dict(value)
+    else:
+        raise ValueError(f"four_state_vector.{key} must be a mapping.")
+    unsupported = sorted(str(item) for item in payload if item not in allowed)
+    if unsupported:
+        noun = "setting" if len(unsupported) == 1 else "settings"
+        raise ValueError(f"four_state_vector.{key} has unsupported {noun}: {', '.join(unsupported)}.")
+    return payload
+
+
+def _nonempty_text(value: object, *, field_name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"four_state_vector.{field_name} must be a non-empty string.")
+    return value.strip()
+
+
+def _string_list(value: object, *, field_name: str) -> list[str]:
+    if not isinstance(value, list) or any(not isinstance(item, str) or not item.strip() for item in value):
+        raise ValueError(f"four_state_vector.{field_name} must be a list of non-empty strings.")
+    return [item.strip() for item in value]
+
+
+@dataclass(frozen=True)
+class FourStateVectorResponseCfg:
+    """Channels used for logic shape and reference-anchored intensity."""
+
+    logic_channel: str
+    intensity_channel: str
+
+
+@dataclass(frozen=True)
+class FourStateVectorReferenceCfg:
+    design_id: str
+    observation_stat: Literal["mean", "median"] = "mean"
+
+
+@dataclass(frozen=True)
+class FourStateVectorConfig:
+    # experiment structure
+    design_by: list[str]
+    time_column: str
+
+    # channels
+    response: FourStateVectorResponseCfg
+
+    # mapping
+    treatment_map: dict[str, str]  # keys = {"00","10","01","11"}
+    reference: FourStateVectorReferenceCfg
+    treatment_case_sensitive: bool = True
+    treatment_column: str | None = None
+
+    # snapshot/time picking
+    target_time_h: float | None = None
+    time_mode: Literal["nearest", "last_before", "first_after", "exact"] = "nearest"
+    time_tolerance_h: float | None = 0.5
+    # misc rules
+    require_all_corners_per_design: bool = True
+
+    # intensity math knobs (spec §1.1b)
+    ref_add_alpha: float = 0.0  # α: additive to A_i in denominator
+    log2_offset_delta: float = 0.0  # δ: additive inside log2(y_linear + δ)
+
+    # numerical guards
+    eps_ratio: float = 1e-9  # ratio/log guard for logic & intensity
+    eps_range: float = 1e-12  # min range for min-max (logic)
+    eps_ref: float = 1e-9  # reference denom guard
+    eps_abs: float = 0.0  # tiny add in numerator for intensity
+
+    # output table policy
+    exclude_reference_from_output: bool = True
+    carry_metadata: list[str] = field(default_factory=lambda: ["sequence", "id"])
+
+
+def load_four_state_vector_config(xform_cfg: Mapping[str, Any]) -> FourStateVectorConfig:
+    """
+    Validate an explicit transform mapping and build an FourStateVectorConfig.
+    Requires explicit 'response.logic_channel' and 'response.intensity_channel'.
+    """
+    if not isinstance(xform_cfg, Mapping):
+        raise ValueError("four-state vector settings must be a mapping.")
+    unsupported = sorted(str(key) for key in xform_cfg if key not in _CONFIG_KEYS)
+    if unsupported:
+        raise ValueError(f"Unsupported four-state vector settings: {', '.join(unsupported)}.")
+
+    design_by = _string_list(xform_cfg.get("design_by", ["design_id"]), field_name="design_by")
+    if not design_by or design_by[0] != "design_id":
+        raise ValueError(
+            "four_state_vector.design_by must start with 'design_id' to align with the four-state vector spec."
+        )
+    time_column = _nonempty_text(xform_cfg.get("time_column", "time"), field_name="time_column")
+
+    resp_in = _sub(xform_cfg, "response", allowed=frozenset({"logic_channel", "intensity_channel"}))
+    logic_channel = resp_in.get("logic_channel", None)
+    intensity_channel = resp_in.get("intensity_channel", None)
+    response = FourStateVectorResponseCfg(
+        logic_channel=_nonempty_text(logic_channel, field_name="response.logic_channel"),
+        intensity_channel=_nonempty_text(intensity_channel, field_name="response.intensity_channel"),
+    )
+
+    # mapping
+    raw_treatment_map = xform_cfg.get("treatment_map", {})
+    if not isinstance(raw_treatment_map, Mapping):
+        raise ValueError("four_state_vector.treatment_map must be a mapping.")
+    tmap = dict(raw_treatment_map)
+    if set(tmap.keys()) != {"00", "10", "01", "11"}:
+        raise ValueError("four_state_vector.treatment_map must have exactly the keys {'00','10','01','11'}.")
+    if any(not isinstance(value, str) or not value.strip() for value in tmap.values()):
+        raise ValueError("four_state_vector.treatment_map values must be non-empty strings.")
+    tmap = {key: value.strip() for key, value in tmap.items()}
+    tcase = bool(xform_cfg.get("treatment_case_sensitive", True))
+    treatment_column_raw = xform_cfg.get("treatment_column")
+    if treatment_column_raw is not None and (
+        not isinstance(treatment_column_raw, str) or not treatment_column_raw.strip()
+    ):
+        raise ValueError("four_state_vector.treatment_column must be a non-empty string when provided.")
+    treatment_column = str(treatment_column_raw).strip() if isinstance(treatment_column_raw, str) else None
+
+    # time picking
+    target_time_h = xform_cfg.get("target_time_h")
+    time_mode = str(xform_cfg.get("time_mode", "nearest")).lower()
+    tol = xform_cfg.get("time_tolerance_h", 0.5)
+    if time_mode not in {"nearest", "last_before", "first_after", "exact"}:
+        raise ValueError(f"Invalid four_state_vector.time_mode='{time_mode}'")
+    require_all = bool(xform_cfg.get("require_all_corners_per_design", True))
+
+    ref = _sub(xform_cfg, "reference", allowed=frozenset({"design_id", "observation_stat"}))
+    ref_label = _nonempty_text(ref.get("design_id"), field_name="reference.design_id")
+    reference = FourStateVectorReferenceCfg(
+        design_id=ref_label,
+        observation_stat=(str(ref.get("observation_stat", "mean")).lower() if ref.get("observation_stat") else "mean"),
+    )
+    if reference.observation_stat not in {"mean", "median"}:
+        raise ValueError(f"Invalid four_state_vector.reference.observation_stat='{reference.observation_stat}'")
+    # eps / table policy
+    eps_ratio = float(xform_cfg.get("eps_ratio", 1e-9))
+    eps_range = float(xform_cfg.get("eps_range", 1e-12))
+    eps_ref = float(xform_cfg.get("eps_ref", 1e-9))
+    eps_abs = float(xform_cfg.get("eps_abs", 0.0))
+
+    ref_add_alpha = float(xform_cfg.get("ref_add_alpha", 0.0))
+    log2_offset_delta = float(xform_cfg.get("log2_offset_delta", 0.0))
+    exclude_ref = bool(xform_cfg.get("exclude_reference_from_output", True))
+    carry_metadata = _string_list(
+        xform_cfg.get("carry_metadata", ["sequence", "id"]),
+        field_name="carry_metadata",
+    )
+    cfg = FourStateVectorConfig(
+        design_by=design_by,
+        time_column=time_column,
+        response=response,
+        treatment_map=tmap,
+        treatment_case_sensitive=tcase,
+        treatment_column=treatment_column,
+        target_time_h=(float(target_time_h) if target_time_h is not None else None),
+        time_mode=time_mode,
+        time_tolerance_h=(float(tol) if tol is not None else None),
+        require_all_corners_per_design=require_all,
+        reference=reference,
+        eps_ratio=eps_ratio,
+        eps_range=eps_range,
+        eps_ref=eps_ref,
+        eps_abs=eps_abs,
+        ref_add_alpha=ref_add_alpha,
+        log2_offset_delta=log2_offset_delta,
+        exclude_reference_from_output=exclude_ref,
+        carry_metadata=carry_metadata,
+    )
+    return cfg
+
+
+__all__ = [
+    "FourStateVectorConfig",
+    "FourStateVectorResponseCfg",
+    "FourStateVectorReferenceCfg",
+    "load_four_state_vector_config",
+]

reader_workbench/domains/logic/four_state_vector/diagnostic.py

@@ -0,0 +1,361 @@
+"""Pure preparation and rendering for persisted four-state vector diagnostics.
+
+The diagnostic joins an annotated measurement trace to the already-persisted
+vector summary. It does not select a new acquisition time or recompute vector.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from reader_workbench.domains.plate_reader.plots.dual_reporter_triptych import (
+    DualReporterTriptychData,
+    build_triptych_data,
+)
+
+STATE_ORDER = ("00", "10", "01", "11")
+_LOGIC_COLUMNS = {state: f"v{state}" for state in STATE_ORDER}
+_INTENSITY_COLUMNS = {state: f"y{state}_star" for state in STATE_ORDER}
+_STATE_COLORS = {
+    "00": "#364152",
+    "10": "#237A70",
+    "01": "#2F65D9",
+    "11": "#B82E3F",
+}
+_STATE_MARKERS = {"00": "o", "10": "s", "01": "^", "11": "D"}
+
+
+@dataclass(frozen=True)
+class FourStateVectorDiagnosticData:
+    design_id: str
+    selected_time_h: float
+    reference_design_id: str
+    time_column: str
+    state_column: str
+    triptych: DualReporterTriptychData
+    logic_components: dict[str, float]
+    intensity_components: dict[str, float]
+
+
+def prepare_four_state_vector_diagnostics(
+    annotated: pd.DataFrame,
+    vector: pd.DataFrame,
+    *,
+    treatment_column: str,
+    treatment_map: Mapping[str, str],
+    treatment_case_sensitive: bool,
+    time_column: str,
+    growth_channel: str,
+    response_channel: str,
+    design_ids: Sequence[str] | None = None,
+    time_atol: float = 1e-9,
+    trajectory_interval_mass: float = 0.95,
+    trajectory_resamples: int = 300,
+) -> tuple[FourStateVectorDiagnosticData, ...]:
+    """Prepare one diagnostic per persisted vector design.
+
+    Four-state vector row order is the default output order. An explicit ``design_ids``
+    selection preserves caller order and fails when any id is unavailable.
+    """
+
+    _require_columns(
+        annotated,
+        ("design_id", treatment_column, time_column, "channel", "value", "position"),
+        where="four-state vector diagnostic annotated data",
+    )
+    _require_columns(
+        vector,
+        (
+            "design_id",
+            "time_selected_h",
+            "reference_design_id",
+            *_LOGIC_COLUMNS.values(),
+            *_INTENSITY_COLUMNS.values(),
+        ),
+        where="four-state vector diagnostic vector data",
+    )
+    if annotated.empty:
+        raise ValueError("four-state vector diagnostic annotated data must not be empty")
+    if vector.empty:
+        raise ValueError("four-state vector diagnostic vector data must not be empty")
+    if not math.isfinite(float(time_atol)) or float(time_atol) < 0.0:
+        raise ValueError("four-state vector diagnostic time_atol must be finite and non-negative")
+
+    source_to_state = _source_to_state(
+        treatment_map,
+        case_sensitive=treatment_case_sensitive,
+    )
+    vector_work = vector.copy().reset_index(drop=True)
+    vector_work["design_id"] = _non_empty_text_series(vector_work["design_id"], field="vector.design_id")
+    duplicate_designs = vector_work.loc[vector_work["design_id"].duplicated(keep=False), "design_id"].unique().tolist()
+    if duplicate_designs:
+        raise ValueError(f"four-state vector diagnostic vector has duplicate design_id values: {duplicate_designs}")
+
+    selected_designs = _selected_design_ids(vector_work, design_ids=design_ids)
+    annotated_work = annotated.copy()
+    annotated_work["design_id"] = _non_empty_text_series(
+        annotated_work["design_id"],
+        field="annotated.design_id",
+    )
+    source_values = annotated_work[treatment_column].astype(str)
+    if not treatment_case_sensitive:
+        source_values = source_values.str.strip().str.casefold()
+    annotated_work["__four_state_vector_state"] = source_values.map(source_to_state)
+    annotated_work = annotated_work[annotated_work["__four_state_vector_state"].isin(STATE_ORDER)].copy()
+
+    prepared: list[FourStateVectorDiagnosticData] = []
+    by_design = vector_work.set_index("design_id", drop=False)
+    for design_id in selected_designs:
+        vector_row = by_design.loc[design_id]
+        selected_time_h = _finite_scalar(vector_row["time_selected_h"], field=f"{design_id}.time_selected_h")
+        reference_design_id = _non_empty_text(
+            vector_row["reference_design_id"],
+            field=f"{design_id}.reference_design_id",
+        )
+        design_traces = annotated_work[annotated_work["design_id"].eq(design_id)].copy()
+        if design_traces.empty:
+            raise ValueError(f"four-state vector diagnostic has no annotated rows for vector design_id {design_id!r}")
+        _require_state_channel_coverage(
+            design_traces,
+            design_id=design_id,
+            channels=(growth_channel, response_channel),
+        )
+        _require_persisted_time_in_traces(
+            design_traces,
+            design_id=design_id,
+            selected_time_h=selected_time_h,
+            time_column=time_column,
+            channels=(growth_channel, response_channel),
+            time_atol=float(time_atol),
+        )
+        triptych = build_triptych_data(
+            design_traces,
+            time_col=time_column,
+            treatment_col="__four_state_vector_state",
+            growth_channel=growth_channel,
+            ratio_channel=response_channel,
+            snapshot_channel=response_channel,
+            snapshot_time=selected_time_h,
+            treatment_order=STATE_ORDER,
+            time_atol=float(time_atol),
+            trajectory_interval_mass=float(trajectory_interval_mass),
+            trajectory_resamples=int(trajectory_resamples),
+        )
+        logic_components = {
+            state: _finite_scalar(vector_row[column], field=f"{design_id}.{column}")
+            for state, column in _LOGIC_COLUMNS.items()
+        }
+        invalid_logic = {state: value for state, value in logic_components.items() if value < 0.0 or value > 1.0}
+        if invalid_logic:
+            raise ValueError(
+                f"four-state vector diagnostic logic-shape components must lie in [0, 1] for {design_id!r}: {invalid_logic}"
+            )
+        intensity_components = {
+            state: _finite_scalar(vector_row[column], field=f"{design_id}.{column}")
+            for state, column in _INTENSITY_COLUMNS.items()
+        }
+        prepared.append(
+            FourStateVectorDiagnosticData(
+                design_id=design_id,
+                selected_time_h=selected_time_h,
+                reference_design_id=reference_design_id,
+                time_column=time_column,
+                state_column="__four_state_vector_state",
+                triptych=triptych,
+                logic_components=logic_components,
+                intensity_components=intensity_components,
+            )
+        )
+    return tuple(prepared)
+
+
+def render_four_state_vector_diagnostic(
+    data: FourStateVectorDiagnosticData,
+    *,
+    title: str | None = None,
+    figsize: tuple[float, float] = (15.0, 5.5),
+    dpi: int = 300,
+) -> Any:
+    """Render trajectories beside the persisted vector components."""
+
+    if len(figsize) != 2 or any(not math.isfinite(float(value)) or float(value) <= 0.0 for value in figsize):
+        raise ValueError("four-state vector diagnostic figsize must contain two positive finite values")
+    if int(dpi) < 1:
+        raise ValueError("four-state vector diagnostic dpi must be positive")
+
+    from reader_workbench.domains.plate_reader.plots.dual_reporter_triptych_render import (  # noqa: PLC0415
+        render_dual_reporter_triptych,
+    )
+
+    figure = render_dual_reporter_triptych(
+        data.triptych,
+        time_col=data.time_column,
+        treatment_col=data.state_column,
+        title=None,
+        figsize=figsize,
+    )
+    figure.set_dpi(int(dpi))
+    figure.axes[0].set_title("Growth trajectory")
+    figure.axes[1].set_title("Response trajectory")
+    snapshot_spec = figure.axes[2].get_subplotspec()
+    figure.delaxes(figure.axes[2])
+    component_grid = snapshot_spec.subgridspec(2, 1, hspace=0.7)
+    logic_axis = figure.add_subplot(component_grid[0, 0])
+    intensity_axis = figure.add_subplot(component_grid[1, 0])
+    _render_components(
+        logic_axis,
+        data.logic_components,
+        title="Logic shape",
+        x_label="Persisted value (unit interval)",
+        x_limits=(-0.05, 1.05),
+    )
+    _render_components(
+        intensity_axis,
+        data.intensity_components,
+        title="Relative intensity",
+        x_label="Persisted value (log2)",
+        draw_zero=True,
+    )
+
+    heading = title.strip() if isinstance(title, str) and title.strip() else "four-state vector diagnostic"
+    figure.suptitle(
+        f"{heading} · {data.design_id}\n"
+        f"selected time {data.selected_time_h:g} h · reference {data.reference_design_id}",
+        fontsize=13,
+    )
+    return figure
+
+
+def _render_components(
+    axis: Any,
+    values: Mapping[str, float],
+    *,
+    title: str,
+    x_label: str,
+    x_limits: tuple[float, float] | None = None,
+    draw_zero: bool = False,
+) -> None:
+    positions = np.arange(len(STATE_ORDER), dtype=float)
+    component_values = np.array([values[state] for state in STATE_ORDER], dtype=float)
+    if draw_zero:
+        axis.axvline(0.0, color="#8A94A6", linewidth=0.9)
+    for position, state, value in zip(positions, STATE_ORDER, component_values, strict=True):
+        axis.hlines(position, min(0.0, value), max(0.0, value), color=_STATE_COLORS[state], linewidth=1.5)
+        axis.scatter(
+            value,
+            position,
+            color=_STATE_COLORS[state],
+            marker=_STATE_MARKERS[state],
+            s=34,
+            zorder=3,
+        )
+    axis.set_yticks(positions, labels=STATE_ORDER)
+    axis.invert_yaxis()
+    axis.set_title(title)
+    axis.set_xlabel(x_label)
+    axis.set_ylabel("State")
+    if x_limits is not None:
+        axis.set_xlim(*x_limits)
+    axis.grid(axis="x", color="#D8DEE8", linewidth=0.6, alpha=0.7)
+
+
+def _selected_design_ids(vector: pd.DataFrame, *, design_ids: Sequence[str] | None) -> tuple[str, ...]:
+    available = tuple(vector["design_id"].astype(str).tolist())
+    if design_ids is None:
+        return available
+    selected = tuple(_non_empty_text(value, field="design_ids") for value in design_ids)
+    if not selected:
+        raise ValueError("four-state vector diagnostic design_ids must not be empty when provided")
+    if len(set(selected)) != len(selected):
+        raise ValueError("four-state vector diagnostic design_ids must be unique")
+    missing = [design_id for design_id in selected if design_id not in set(available)]
+    if missing:
+        raise ValueError(f"four-state vector diagnostic design_ids are absent from vector: {missing}")
+    return selected
+
+
+def _source_to_state(treatment_map: Mapping[str, str], *, case_sensitive: bool) -> dict[str, str]:
+    if set(treatment_map) != set(STATE_ORDER):
+        raise ValueError("four-state vector diagnostic treatment_map must contain exactly 00, 10, 01, and 11")
+    reverse: dict[str, str] = {}
+    for state in STATE_ORDER:
+        source_value = _non_empty_text(treatment_map[state], field=f"treatment_map.{state}")
+        key = source_value if case_sensitive else source_value.strip().casefold()
+        if key in reverse:
+            raise ValueError("four-state vector diagnostic treatment_map source values must be unique")
+        reverse[key] = state
+    return reverse
+
+
+def _require_state_channel_coverage(frame: pd.DataFrame, *, design_id: str, channels: Sequence[str]) -> None:
+    for channel in channels:
+        observed = set(
+            frame.loc[frame["channel"].astype(str).eq(str(channel)), "__four_state_vector_state"].astype(str)
+        )
+        missing = [state for state in STATE_ORDER if state not in observed]
+        if missing:
+            raise ValueError(
+                f"four-state vector diagnostic design {design_id!r} channel {channel!r} is missing state traces: {missing}"
+            )
+
+
+def _require_persisted_time_in_traces(
+    frame: pd.DataFrame,
+    *,
+    design_id: str,
+    selected_time_h: float,
+    time_column: str,
+    channels: Sequence[str],
+    time_atol: float,
+) -> None:
+    times = pd.to_numeric(frame[time_column], errors="coerce")
+    for channel in channels:
+        channel_times = times[frame["channel"].astype(str).eq(str(channel))].dropna().to_numpy(dtype=float)
+        if not np.isclose(channel_times, selected_time_h, rtol=0.0, atol=time_atol).any():
+            raise ValueError(
+                f"four-state vector diagnostic persisted selection time {selected_time_h:g} h for {design_id!r} "
+                f"is absent from channel {channel!r} traces"
+            )
+
+
+def _require_columns(frame: pd.DataFrame, columns: Sequence[str], *, where: str) -> None:
+    missing = [column for column in columns if column not in frame.columns]
+    if missing:
+        raise ValueError(f"{where} is missing columns: {missing}")
+
+
+def _finite_scalar(value: object, *, field: str) -> float:
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        raise ValueError(f"four-state vector diagnostic {field} must be a finite number") from None
+    if not math.isfinite(number):
+        raise ValueError(f"four-state vector diagnostic {field} must be a finite number")
+    return number
+
+
+def _non_empty_text_series(series: pd.Series, *, field: str) -> pd.Series:
+    values = series.astype(str).str.strip()
+    if values.eq("").any() or values.str.casefold().eq("nan").any():
+        raise ValueError(f"four-state vector diagnostic {field} must contain non-empty values")
+    return values
+
+
+def _non_empty_text(value: object, *, field: str) -> str:
+    text = str(value).strip()
+    if not text or text.casefold() in {"nan", "<na>"}:
+        raise ValueError(f"four-state vector diagnostic {field} must be a non-empty string")
+    return text
+
+
+__all__ = [
+    "FourStateVectorDiagnosticData",
+    "prepare_four_state_vector_diagnostics",
+    "render_four_state_vector_diagnostic",
+]

reader_workbench/domains/logic/four_state_vector/heatmap.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+
+import pandas as pd
+
+from reader_workbench.errors import FourStateVectorError
+
+from .collection.checks import require_vector_columns
+from .collection.constants import VECTOR_CHANNELS
+from .collection.render import render_four_state_vector_collection_heatmap
+
+_NUMERIC_COLUMNS = (
+    "intensity_log2_offset_delta",
+    "r_logic",
+    *VECTOR_CHANNELS,
+)
+
+
+def normalize_experiment_heatmap_frame(vector: pd.DataFrame, *, experiment_id: str) -> pd.DataFrame:
+    """Adapt one experiment's logic.four_state_vector.v1 table to the heatmap renderer contract."""
+
+    require_vector_columns(vector)
+    if vector.empty:
+        raise FourStateVectorError("four-state vector heatmap has no rows to plot.")
+    normalized_experiment_id = _non_empty_text(experiment_id, field="experiment_id")
+
+    frame = vector.copy().reset_index(drop=True)
+    _require_non_empty_text_columns(frame, columns=("design_id", "reference_design_id"))
+    for column in _NUMERIC_COLUMNS:
+        frame[column] = _finite_numeric(frame[column], column=column)
+    if "time_selected_h" in frame.columns:
+        frame["time_selected_h"] = _finite_numeric(
+            frame["time_selected_h"],
+            column="time_selected_h",
+            allow_nan=True,
+        )
+    frame["flat_logic"] = frame["flat_logic"].astype(bool)
+
+    frame["source_index"] = 0
+    frame["source_experiment_id"] = normalized_experiment_id
+    frame["source_row_index"] = range(len(frame))
+    frame["row_label"] = _row_labels(frame, experiment_id=normalized_experiment_id)
+    return frame
+
+
+def render_experiment_four_state_vector_heatmap(
+    vector: pd.DataFrame,
+    *,
+    experiment_id: str,
+    title: str | None = None,
+    max_y_tick_labels: int = 80,
+):
+    frame = normalize_experiment_heatmap_frame(vector, experiment_id=experiment_id)
+    return render_four_state_vector_collection_heatmap(frame, title=title, max_y_tick_labels=max_y_tick_labels)
+
+
+def _row_labels(frame: pd.DataFrame, *, experiment_id: str) -> list[str]:
+    return [f"{experiment_id}::{design_id}" for design_id in frame["design_id"].astype(str).tolist()]
+
+
+def _finite_numeric(series: pd.Series, *, column: 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 heatmap column {column!r} must contain finite numeric values.")
+    return values.astype(float)
+
+
+def _require_non_empty_text_columns(frame: pd.DataFrame, *, columns: Sequence[str]) -> None:
+    for column in columns:
+        values = frame[column].astype(str).str.strip()
+        if values.eq("").any():
+            raise FourStateVectorError(f"four-state vector heatmap column {column!r} must contain non-empty values.")
+
+
+def _non_empty_text(value: str, *, field: str) -> str:
+    text = str(value).strip()
+    if not text:
+        raise FourStateVectorError(f"four-state vector heatmap {field} must be a non-empty string.")
+    return text