reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/domains/plate_reader/analysis/four_state_event_window/sources.py

@@ -0,0 +1,308 @@
+"""Manifest-backed source loading for four-state event-window analysis."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from .contracts import EventSpec, FourStateEventWindowSourceSpec
+from .well_exclusions import WellExclusion
+
+STATE_ORDER = ("00", "10", "01", "11")
+ANNOTATED_CONTRACT = "plate_reader.annotated.v1"
+
+
+@dataclass(frozen=True)
+class EventInterval:
+    experiment_id: str
+    event_id: str
+    event_kind: str
+    interval_start_assay_h: float
+    interval_end_assay_h: float
+    estimate_assay_h: float
+    estimate_method: str
+    uncertainty_h: float
+    post_event_coverage_h: float
+    declaration: str
+
+
+@dataclass(frozen=True)
+class ExperimentSource:
+    experiment_id: str
+    response: pd.DataFrame
+    magnitude: pd.DataFrame
+    trajectory: pd.DataFrame
+    event: EventInterval
+    well_exclusions: tuple[WellExclusion, ...] = ()
+
+
+def event_record(event: EventInterval) -> pd.DataFrame:
+    return pd.DataFrame.from_records(
+        [
+            {
+                "experiment_id": event.experiment_id,
+                "event_id": event.event_id,
+                "event_kind": event.event_kind,
+                "event_interval_start_assay_h": event.interval_start_assay_h,
+                "event_interval_end_assay_h": event.interval_end_assay_h,
+                "event_time_estimate_assay_h": event.estimate_assay_h,
+                "event_time_estimate_method": event.estimate_method,
+                "event_time_uncertainty_h": event.uncertainty_h,
+                "post_event_coverage_h": event.post_event_coverage_h,
+                "declaration": event.declaration,
+            }
+        ]
+    )
+
+
+def build_experiment_source(
+    *,
+    experiment_id: str,
+    response_frame: pd.DataFrame,
+    magnitude_frame: pd.DataFrame,
+    trajectory_frame: pd.DataFrame,
+    source_spec: FourStateEventWindowSourceSpec,
+    event_spec: EventSpec,
+) -> ExperimentSource:
+    """Normalize three already-resolved records into one analysis source."""
+
+    state_column = source_spec.state_column
+    treatment_map = source_spec.state_values
+    case_sensitive = source_spec.state_values_case_sensitive
+    if set(treatment_map) != set(STATE_ORDER) or len(set(treatment_map.values())) != len(STATE_ORDER):
+        raise ValueError(f"{experiment_id}: resolved state map must define four distinct 00, 10, 01, and 11 values.")
+    response = _load_signal(
+        response_frame,
+        channel=source_spec.response_channel,
+        state_column=state_column,
+        treatment_map=treatment_map,
+        case_sensitive=case_sensitive,
+        event_spec=event_spec,
+        context=f"{experiment_id}:response",
+    )
+    magnitude = _load_signal(
+        magnitude_frame,
+        channel=source_spec.magnitude_channel,
+        state_column=state_column,
+        treatment_map=treatment_map,
+        case_sensitive=case_sensitive,
+        event_spec=event_spec,
+        context=f"{experiment_id}:magnitude",
+    )
+    trajectory = _load_signal(
+        trajectory_frame,
+        channel=source_spec.growth_channel,
+        state_column=state_column,
+        treatment_map=treatment_map,
+        case_sensitive=case_sensitive,
+        event_spec=event_spec,
+        context=f"{experiment_id}:growth",
+        require_positive=False,
+    )
+    well_exclusions = tuple(item for item in source_spec.well_exclusions if item.experiment_id == experiment_id)
+    _validate_well_exclusions(
+        well_exclusions,
+        response=response,
+        magnitude=magnitude,
+        trajectory=trajectory,
+        experiment_id=experiment_id,
+    )
+    event = resolve_event_interval(response, experiment_id=experiment_id, event_spec=event_spec)
+    magnitude_event = resolve_event_interval(magnitude, experiment_id=experiment_id, event_spec=event_spec)
+    growth_event = resolve_event_interval(trajectory, experiment_id=experiment_id, event_spec=event_spec)
+    _require_event_parity(event, magnitude_event, context=f"{experiment_id}:response/magnitude")
+    _require_event_parity(event, growth_event, context=f"{experiment_id}:response/growth")
+
+    for frame in (response, magnitude, trajectory):
+        frame["experiment_id"] = experiment_id
+        frame["time_from_event_h"] = frame["time"].to_numpy(dtype=float) - event.estimate_assay_h
+    reference_id = source_spec.reference_design_id
+    if reference_id not in set(magnitude["design_id"].astype(str)):
+        raise ValueError(f"{experiment_id}: reference design {reference_id!r} is absent from magnitude records.")
+
+    return ExperimentSource(
+        experiment_id=experiment_id,
+        response=response,
+        magnitude=magnitude,
+        trajectory=trajectory,
+        event=event,
+        well_exclusions=well_exclusions,
+    )
+
+
+def _validate_well_exclusions(
+    exclusions: tuple[WellExclusion, ...],
+    *,
+    response: pd.DataFrame,
+    magnitude: pd.DataFrame,
+    trajectory: pd.DataFrame,
+    experiment_id: str,
+) -> None:
+    for exclusion in exclusions:
+        expected = {(exclusion.design_id, exclusion.state)}
+        for signal_kind, frame in (
+            ("response", response),
+            ("magnitude", magnitude),
+            ("growth", trajectory),
+        ):
+            selected = frame.loc[frame["position"].astype(str).eq(exclusion.position)]
+            observed = set(zip(selected["design_id"].astype(str), selected["state"].astype(str), strict=True))
+            if observed != expected:
+                raise ValueError(
+                    f"{experiment_id}:{signal_kind} well exclusion {exclusion.position!r} "
+                    f"does not match design/state {exclusion.design_id!r}/{exclusion.state!r}."
+                )
+
+
+def resolve_event_interval(
+    frame: pd.DataFrame,
+    *,
+    experiment_id: str,
+    event_spec: EventSpec,
+) -> EventInterval:
+    segments = pd.to_numeric(frame[event_spec.segment_column], errors="coerce")
+    segment_values = segments.to_numpy(dtype=float, na_value=np.nan)
+    if not np.isfinite(segment_values).all() or not np.equal(segment_values, np.trunc(segment_values)).all():
+        raise ValueError(f"{experiment_id}: event segment indexes must be finite integers.")
+    segment_indexes = segments.astype(int)
+    indexes = set(segment_indexes)
+    expected = {event_spec.pre_segment_index, event_spec.post_segment_index}
+    if indexes != expected:
+        raise ValueError(
+            f"{experiment_id}: event requires segment indexes {sorted(expected)}; found {sorted(indexes)}."
+        )
+    times = pd.to_numeric(frame["time"], errors="coerce")
+    if not np.isfinite(times.to_numpy(dtype=float)).all():
+        raise ValueError(f"{experiment_id}: event alignment requires finite acquisition times.")
+    pre = times.loc[segment_indexes.eq(event_spec.pre_segment_index)]
+    post = times.loc[segment_indexes.eq(event_spec.post_segment_index)]
+    last_pre = float(pre.max())
+    first_post = float(post.min())
+    assay_end = float(post.max())
+    if not last_pre < first_post <= assay_end:
+        raise ValueError(
+            f"{experiment_id}: event segments are not chronological: "
+            f"last_pre={last_pre}, first_post={first_post}, assay_end={assay_end}."
+        )
+    estimate = (last_pre + first_post) / 2.0
+    return EventInterval(
+        experiment_id=experiment_id,
+        event_id=event_spec.event_id,
+        event_kind=event_spec.event_kind,
+        interval_start_assay_h=last_pre,
+        interval_end_assay_h=first_post,
+        estimate_assay_h=estimate,
+        estimate_method=event_spec.estimate_method,
+        uncertainty_h=(first_post - last_pre) / 2.0,
+        post_event_coverage_h=assay_end - first_post,
+        declaration=event_spec.declaration,
+    )
+
+
+def _load_signal(
+    frame: pd.DataFrame,
+    *,
+    channel: str,
+    state_column: str,
+    treatment_map: Mapping[str, str],
+    case_sensitive: bool,
+    event_spec: EventSpec,
+    context: str,
+    require_positive: bool = True,
+) -> pd.DataFrame:
+    frame = frame.copy()
+    required = {"design_id", "position", "time", "channel", "value", state_column, event_spec.segment_column}
+    missing = sorted(required - set(frame.columns))
+    if missing:
+        raise ValueError(f"{context} record is missing columns: {missing}.")
+    work = frame.loc[frame["channel"].astype(str).eq(channel)].copy()
+    if work.empty:
+        raise ValueError(f"{context} record has no rows for channel {channel!r}.")
+    reverse = {(value if case_sensitive else value.strip().casefold()): state for state, value in treatment_map.items()}
+    values = work[state_column].astype(str)
+    if not case_sensitive:
+        values = values.str.strip().str.casefold()
+    work["state"] = values.map(reverse)
+    unknown = sorted(work.loc[work["state"].isna(), state_column].astype(str).unique().tolist())
+    if unknown:
+        raise ValueError(f"{context} record contains unmapped state values: {unknown}.")
+    work["design_id"] = work["design_id"].astype(str)
+    work["position"] = work["position"].astype(str)
+    work["state"] = work["state"].astype(str)
+    work["time"] = pd.to_numeric(work["time"], errors="coerce")
+    work["value"] = pd.to_numeric(work["value"], errors="coerce")
+    if not np.isfinite(work[["time", "value"]].to_numpy(dtype=float)).all():
+        raise ValueError(f"{context} record contains non-finite time or values.")
+    if require_positive and (work["value"].to_numpy(dtype=float) <= 0.0).any():
+        raise ValueError(
+            f"{context} record contains non-positive values; "
+            "four-state event-window log-space reduction requires strictly positive source values."
+        )
+    _normalize_value_provenance(work, context=context)
+    return work.loc[
+        :,
+        [
+            "design_id",
+            "position",
+            "state",
+            "time",
+            "channel",
+            "value",
+            "value_policy_clipped",
+            "value_instrument_overflow",
+            "value_bound_kind",
+            event_spec.segment_column,
+        ],
+    ].reset_index(drop=True)
+
+
+def _normalize_value_provenance(frame: pd.DataFrame, *, context: str) -> None:
+    required = {"value_policy_clipped", "value_instrument_overflow", "value_bound_kind"}
+    missing = sorted(required - set(frame.columns))
+    if missing:
+        raise ValueError(f"{context} record is missing required value provenance columns: {missing}.")
+    policy = _boolean_provenance(frame["value_policy_clipped"], context=f"{context}:value_policy_clipped")
+    overflow = _boolean_provenance(frame["value_instrument_overflow"], context=f"{context}:value_instrument_overflow")
+    frame["value_policy_clipped"] = policy
+    frame["value_instrument_overflow"] = overflow
+    bounds = frame["value_bound_kind"].astype(str)
+    allowed = {"exact", "lower", "upper", "indeterminate"}
+    unknown = sorted(set(bounds) - allowed)
+    if unknown:
+        raise ValueError(f"{context} record contains unsupported value_bound_kind values: {unknown}.")
+    if ((policy | overflow) & bounds.eq("exact")).any():
+        raise ValueError(f"{context} record marks clipped or overflowed values as exact.")
+    if (bounds.ne("exact") & ~(policy | overflow)).any():
+        raise ValueError(f"{context} record contains a value bound without clipping or overflow provenance.")
+    frame["value_bound_kind"] = bounds
+
+
+def _boolean_provenance(values: pd.Series, *, context: str) -> pd.Series:
+    if values.isna().any() or not values.map(lambda value: isinstance(value, (bool, np.bool_))).all():
+        raise ValueError(f"{context} must contain booleans without missing values.")
+    return values.astype(bool)
+
+
+def _require_event_parity(left: EventInterval, right: EventInterval, *, context: str) -> None:
+    fields = (
+        "interval_start_assay_h",
+        "interval_end_assay_h",
+        "estimate_assay_h",
+        "post_event_coverage_h",
+    )
+    if any(not np.isclose(getattr(left, field), getattr(right, field), rtol=0.0, atol=1.0e-12) for field in fields):
+        raise ValueError(f"{context} event bounds disagree across source records.")
+
+
+__all__ = [
+    "ANNOTATED_CONTRACT",
+    "STATE_ORDER",
+    "EventInterval",
+    "ExperimentSource",
+    "build_experiment_source",
+    "event_record",
+    "resolve_event_interval",
+]

reader_workbench/domains/plate_reader/analysis/four_state_event_window/well_exclusion_validation.py

@@ -0,0 +1,94 @@
+"""Verify that declared well exclusions correspond to missing temporal support."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+import pandas as pd
+
+from .contracts import QualitySpec, ReductionSpec
+from .reduction import four_state_event_window_temporal_spec, reduce_temporal_trace
+from .well_exclusions import WellExclusion
+
+
+def require_well_exclusion_support_failure(
+    exclusions: Sequence[WellExclusion],
+    *,
+    reductions: Mapping[str, ReductionSpec],
+    quality: QualitySpec,
+    response: pd.DataFrame,
+    magnitude: pd.DataFrame,
+    event_estimates_h: Sequence[float],
+    pre_window_end_h: float,
+    experiment_id: str,
+) -> None:
+    for exclusion in exclusions:
+        try:
+            reduction = reductions[exclusion.reduction_id]
+        except KeyError as exc:
+            raise ValueError(
+                f"{experiment_id}: well exclusion names unknown reduction {exclusion.reduction_id!r}."
+            ) from exc
+        support_failures: list[str] = []
+        for frame in (response, magnitude):
+            trace = frame.loc[frame["position"].astype(str).eq(exclusion.position)]
+            for event_estimate_h in event_estimates_h:
+                try:
+                    reduce_temporal_trace(
+                        trace["time"].to_numpy(dtype=float),
+                        trace["value"].to_numpy(dtype=float),
+                        spec=four_state_event_window_temporal_spec(reduction, quality),
+                        trace_id=f"{experiment_id}:{exclusion.position}:{reduction.id}:support",
+                        origin_h=event_estimate_h,
+                        policy_clipped=trace["value_policy_clipped"].to_numpy(dtype=bool),
+                        instrument_overflow=trace["value_instrument_overflow"].to_numpy(dtype=bool),
+                        bound_kinds=trace["value_bound_kind"].to_numpy(dtype=object),
+                    )
+                except ValueError as exc:
+                    if _is_support_failure(str(exc)):
+                        support_failures.append(str(exc))
+        if reduction.response_basis == "post_minus_pre":
+            if reduction.pre_window_duration_h is None:
+                raise ValueError(f"{experiment_id}:{reduction.id}: delta response lacks an explicit pre-event window.")
+            trace = response.loc[response["position"].astype(str).eq(exclusion.position)]
+            try:
+                reduce_temporal_trace(
+                    trace["time"].to_numpy(dtype=float),
+                    trace["value"].to_numpy(dtype=float),
+                    spec=four_state_event_window_temporal_spec(
+                        reduction,
+                        quality,
+                        absolute_window_h=(
+                            pre_window_end_h - reduction.pre_window_duration_h,
+                            pre_window_end_h,
+                        ),
+                    ),
+                    trace_id=f"{experiment_id}:{exclusion.position}:{reduction.id}:pre-support",
+                    policy_clipped=trace["value_policy_clipped"].to_numpy(dtype=bool),
+                    instrument_overflow=trace["value_instrument_overflow"].to_numpy(dtype=bool),
+                    bound_kinds=trace["value_bound_kind"].to_numpy(dtype=object),
+                )
+            except ValueError as exc:
+                if _is_support_failure(str(exc)):
+                    support_failures.append(str(exc))
+        if not support_failures:
+            raise ValueError(
+                f"{experiment_id}:{exclusion.position}:{exclusion.reduction_id} "
+                "does not have insufficient event-window coverage."
+            )
+
+
+def _is_support_failure(message: str) -> bool:
+    return any(
+        token in message
+        for token in (
+            "does not cover",
+            "interior gap",
+            "observations in the selected interval",
+            "requires observed interval boundaries",
+            "selected interval contains no observations",
+        )
+    )
+
+
+__all__ = ["require_well_exclusion_support_failure"]

reader_workbench/domains/plate_reader/analysis/four_state_event_window/well_exclusions.py

@@ -0,0 +1,54 @@
+"""Define explicit, reduction-bound exclusions for unsupported assay wells."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from .contract_fields import exact_fields, nonempty
+
+_COVERAGE_REASON = "insufficient_event_window_coverage"
+
+
+@dataclass(frozen=True)
+class WellExclusion:
+    experiment_id: str
+    design_id: str
+    state: str
+    position: str
+    reduction_id: str
+    reason: str
+
+
+def parse_well_exclusions(value: object) -> tuple[WellExclusion, ...]:
+    if isinstance(value, (str, bytes)) or not isinstance(value, Sequence):
+        raise ValueError("source.well_exclusions must be a sequence.")
+    exclusions: list[WellExclusion] = []
+    for index, item in enumerate(value):
+        fields = {"experiment_id", "design_id", "state", "position", "reduction_id", "reason"}
+        payload = exact_fields(item, context=f"source.well_exclusions[{index}]", required=fields)
+        state = nonempty(payload["state"], context=f"source.well_exclusions[{index}].state")
+        if state not in {"00", "10", "01", "11"}:
+            raise ValueError(f"source.well_exclusions[{index}].state must be 00, 10, 01, or 11.")
+        reason = nonempty(payload["reason"], context=f"source.well_exclusions[{index}].reason")
+        if reason != _COVERAGE_REASON:
+            raise ValueError(f"source.well_exclusions[{index}].reason must be {_COVERAGE_REASON!r}.")
+        exclusions.append(
+            WellExclusion(
+                experiment_id=nonempty(
+                    payload["experiment_id"], context=f"source.well_exclusions[{index}].experiment_id"
+                ),
+                design_id=nonempty(payload["design_id"], context=f"source.well_exclusions[{index}].design_id"),
+                state=state,
+                position=nonempty(payload["position"], context=f"source.well_exclusions[{index}].position"),
+                reduction_id=nonempty(payload["reduction_id"], context=f"source.well_exclusions[{index}].reduction_id"),
+                reason=reason,
+            )
+        )
+    keys = [(item.experiment_id, item.position, item.reduction_id) for item in exclusions]
+    if len(keys) != len(set(keys)):
+        raise ValueError("source.well_exclusions must not repeat an experiment, position, and reduction.")
+    return tuple(exclusions)
+
+
+__all__ = ["WellExclusion", "parse_well_exclusions"]

reader_workbench/domains/plate_reader/analysis/timepoints.py

@@ -0,0 +1,76 @@
+"""Plate-reader timepoint selection and nearest-snapshot helpers."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+
+import numpy as np
+import pandas as pd
+import polars as pl
+
+
+def nearest_time_per_key(df: pd.DataFrame, *, target_time: float, keys: Sequence[str], tol: float) -> pd.DataFrame:
+    work = pl.from_pandas(df.reset_index(drop=True)).with_row_index("__row__")
+    time_col = "time"
+    time_expr = pl.col(time_col).cast(pl.Float64, strict=False)
+    time_expr = pl.when(time_expr.is_nan()).then(None).otherwise(time_expr)
+    work = work.with_columns(time_expr.alias(time_col))
+    work = work.filter(pl.col(time_col).is_not_null())
+    work = work.with_columns((pl.col(time_col) - float(target_time)).abs().alias("__dt__"))
+    work = work.with_columns(pl.col("__dt__").min().over(list(keys)).alias("__dt_min__"))
+    work = work.filter(pl.col("__dt__") == pl.col("__dt_min__"))
+    work = work.sort("__row__").unique(subset=list(keys), keep="first")
+    work = work.filter(pl.col("__dt__") <= float(tol))
+    work = work.drop(["__dt__", "__dt_min__", "__row__"])
+    return work.to_pandas(use_pyarrow_extension_array=False)
+
+
+def choose_nearest_time(
+    times: Sequence[object] | np.ndarray,
+    *,
+    target_time: float,
+    tol: float | None,
+    where: str,
+    logger: logging.Logger | None = None,
+) -> float:
+    cleaned = pd.to_numeric(pd.Series(times), errors="coerce").dropna().to_numpy(dtype=float)
+    if cleaned.size == 0:
+        raise ValueError(f"{where}: no valid time values")
+    unique_times = np.asarray(sorted(np.unique(cleaned)), dtype=float)
+    diffs = np.abs(unique_times - float(target_time))
+    chosen_index = int(np.argmin(diffs))
+    chosen_time = float(unique_times[chosen_index])
+    chosen_delta = float(diffs[chosen_index])
+    if tol is not None and chosen_delta > float(tol) and logger is not None:
+        logger.info(
+            "[warn]%s[/warn] • requested t=%.2f h; nearest available t=%.2f h (Δ=%.2f h) — using nearest",
+            where,
+            float(target_time),
+            chosen_time,
+            chosen_delta,
+        )
+    return chosen_time
+
+
+def infer_acquisition_transition_time_h(df: pd.DataFrame, *, time_col: str) -> float | None:
+    """Return the first time in a later workbook acquisition segment.
+
+    A sheet transition is acquisition provenance. It does not identify a
+    biological intervention unless a separate, explicit event contract says
+    that it does.
+    """
+    if "sheet_index" not in df.columns:
+        return None
+    sheet_values = pd.to_numeric(df["sheet_index"], errors="coerce").dropna()
+    if sheet_values.empty:
+        return None
+    min_sheet = float(sheet_values.min())
+    sheet_series = pd.to_numeric(df["sheet_index"], errors="coerce")
+    times = pd.to_numeric(df.loc[sheet_series > min_sheet, time_col], errors="coerce").dropna()
+    if times.empty:
+        return None
+    return float(times.min())
+
+
+__all__ = ["choose_nearest_time", "infer_acquisition_transition_time_h", "nearest_time_per_key"]

reader_workbench/domains/plate_reader/io/__init__.py

@@ -0,0 +1,6 @@
+"""Plate-reader instrument parsers."""
+
+from .sample_map import parse_sample_map
+from .synergy_h1 import parse_kinetic_only, parse_snapshot_and_timeseries
+
+__all__ = ["parse_kinetic_only", "parse_sample_map", "parse_snapshot_and_timeseries"]

reader_workbench/domains/plate_reader/io/sample_map.py

@@ -0,0 +1,65 @@
+"""Plate-reader sample-map parsing."""
+
+from collections import Counter
+from pathlib import Path
+
+import pandas as pd
+
+
+def parse_sample_map(path: str | Path) -> pd.DataFrame:
+    """
+    Load a sample metadata map with a 'position' key.
+
+    Accepted inputs:
+      1) A table with an explicit 'position' column (preferred).
+      2) A table with 'row' and 'col' columns (will be combined into 'position').
+
+    This parser is plate-reader oriented: the join key is a well position.
+    """
+    p = Path(path)
+    if not p.exists():
+        raise ValueError(f"Sample map does not exist: {p}")
+    if not p.is_file():
+        raise ValueError(f"Sample map must be a regular file: {p}")
+    suffix = p.suffix.lower()
+    if suffix == ".xlsx":
+        df = pd.read_excel(p)
+    elif suffix == ".csv":
+        df = pd.read_csv(p)
+    else:
+        raise ValueError(f"Unsupported sample-map format {suffix or '<none>'!r}; expected .csv or .xlsx")
+
+    normalized_columns = [str(column).strip().lower() for column in df.columns]
+    duplicate_columns = sorted(name for name, count in Counter(normalized_columns).items() if count > 1)
+    if duplicate_columns:
+        raise ValueError(f"Sample map has duplicate column names after normalization: {duplicate_columns}")
+    cols = dict(zip(normalized_columns, df.columns, strict=True))
+    if "position" in cols:
+        if cols["position"] != "position":
+            df = df.rename(columns={cols["position"]: "position"})
+    elif {"row", "col"}.issubset(cols):
+        row_col = cols["row"]
+        col_col = cols["col"]
+        out = df.copy()
+        row_values = out[row_col].astype("string").str.strip()
+        col_values = out[col_col].astype("string").str.strip()
+        invalid_parts = row_values.isna() | row_values.eq("") | col_values.isna() | col_values.eq("")
+        if invalid_parts.any():
+            rows = [int(index) + 2 for index in out.index[invalid_parts].tolist()]
+            raise ValueError(f"Sample map has blank row/col values at file rows: {rows}")
+        out["position"] = row_values + col_values
+        df = out.drop(columns=[row_col, col_col])
+    else:
+        raise ValueError("Sample map must contain either a 'position' column or a ('row','col') pair.")
+
+    positions = df["position"].astype("string").str.strip().str.upper()
+    invalid = positions.isna() | positions.eq("") | positions.eq("NAN") | positions.eq("<NA>")
+    if invalid.any():
+        rows = [int(index) + 2 for index in df.index[invalid].tolist()]
+        raise ValueError(f"Sample map has blank position values at file rows: {rows}")
+    duplicates = sorted(positions[positions.duplicated(keep=False)].unique().tolist())
+    if duplicates:
+        raise ValueError(f"Sample map positions must be unique; duplicates: {duplicates}")
+    df = df.copy()
+    df["position"] = positions
+    return df

reader_workbench/domains/plate_reader/io/synergy_h1/__init__.py

@@ -0,0 +1,6 @@
+"""Public parser surface for BioTek Synergy H1 workbooks."""
+
+from ._parser import parse_kinetic_only, parse_snapshot_and_timeseries
+from ._shared import probe_synergy_workbook
+
+__all__ = ["parse_kinetic_only", "parse_snapshot_and_timeseries", "probe_synergy_workbook"]