reader-workbench 1.0.0__py3-none-any.whl

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

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping, Sequence
+
+import pandas as pd
+
+from ._shared import (
+    canonical_channel,
+    coerce_measurements,
+    is_blank_measurement,
+    require,
+    resolve_channel,
+    time_column,
+    well_headers,
+)
+
+
+def tidy_kinetic_blocks(
+    kinetic: pd.DataFrame,
+    *,
+    elapsed_h: float,
+    sheet_index: int,
+    sheet_name: str,
+    channels: Sequence[str] | None,
+    channel_map_ci: Mapping[str, str],
+    map_free_raw_by_channel: dict[str, tuple[str, str, str]],
+) -> pd.DataFrame:
+    logger = logging.getLogger("reader")
+    raw_to_resolved: dict[str, str] = {}
+    raw_to_canonical: dict[str, str] = {}
+
+    def row_has(frame: pd.DataFrame, index: int, pattern: str) -> bool:
+        return frame.iloc[index].astype(str).str.contains(pattern, case=False, na=False).any()
+
+    def looks_like_label(first_cell: object) -> bool:
+        value = str(first_cell or "").strip()
+        if not value or value.lower() == "nan":
+            return False
+        if ":" in value:
+            return True
+        try:
+            return resolve_channel(value, channels=channels, channel_map_ci=channel_map_ci) is not None
+        except ValueError as error:
+            raise ValueError(f"{error} in kinetic sheet {sheet_name!r}") from error
+
+    label_rows = [index for index, row in kinetic.iterrows() if looks_like_label(row.iat[0])]
+    require(
+        label_rows,
+        "No kinetic blocks found: expected a channel label in column A "
+        "(e.g., 'OD600' or 'OD600: …') preceding a 'Time' header row.",
+    )
+
+    parts: list[pd.DataFrame] = []
+    for block_index, start in enumerate(label_rows):
+        end = label_rows[block_index + 1] if block_index + 1 < len(label_rows) else len(kinetic)
+        block = kinetic.iloc[start:end].reset_index(drop=True)
+        section_end = next((index for index in range(1, len(block)) if row_has(block, index, r"^Results$")), None)
+        if section_end is not None:
+            block = block.iloc[:section_end].reset_index(drop=True)
+
+        raw_channel = str(block.iat[0, 0]).strip()
+        canonical = canonical_channel(raw_channel)
+        channel = resolve_channel(raw_channel, channels=channels, channel_map_ci=channel_map_ci)
+        if channel is None:
+            continue
+
+        if not channel_map_ci:
+            normalized_canonical = canonical.lower()
+            previous_raw = map_free_raw_by_channel.get(channel)
+            if previous_raw is not None and previous_raw[0] != normalized_canonical:
+                raise ValueError(
+                    f"Ambiguous map-free kinetic channel {channel!r} in sheet {sheet_name!r}: "
+                    f"raw labels {previous_raw[1]!r} from sheet {previous_raw[2]!r} and "
+                    f"{canonical!r} from sheet {sheet_name!r} resolve to the same declared channel; "
+                    "provide channel_map to select raw labels explicitly"
+                )
+            if previous_raw is None:
+                map_free_raw_by_channel[channel] = (normalized_canonical, canonical, sheet_name)
+
+        raw_to_canonical.setdefault(raw_channel, canonical)
+        previous = raw_to_resolved.get(raw_channel)
+        if previous is not None and previous != channel:
+            logger.warning(
+                "[warn]inconsistent channel resolution[/warn] • raw=%r canon=%r previously→%r now→%r",
+                raw_channel,
+                canonical,
+                previous,
+                channel,
+            )
+        raw_to_resolved[raw_channel] = channel
+
+        header_index = next((index for index in range(1, len(block)) if row_has(block, index, r"^Time")), None)
+        require(header_index is not None, f"Time header not found in kinetic block for channel {channel!r}")
+        header = block.iloc[header_index].astype(str).tolist()
+        time_key = time_column(header)
+        wells = well_headers(header)
+        require(wells, f"No well columns (A1..H12) in kinetic header for {channel!r}")
+
+        data = block.iloc[header_index + 1 :].reset_index(drop=True)
+        data.columns = header
+        raw_times = data[time_key]
+        parsed_times = pd.to_timedelta(raw_times, errors="coerce")
+        has_measurement = data[wells].map(lambda value: not is_blank_measurement(value)).any(axis=1)
+        invalid_time = parsed_times.isna() & (
+            raw_times.map(lambda value: not is_blank_measurement(value)) | has_measurement
+        )
+        if invalid_time.any():
+            index = invalid_time[invalid_time].index[0]
+            token = raw_times.loc[index]
+            raise ValueError(f"Invalid kinetic time token {token!r} in sheet {sheet_name!r}, channel {channel!r}")
+        time_hours = parsed_times.dt.total_seconds() / 3600.0
+        data = data.assign(__time_hr=time_hours).loc[lambda frame: frame["__time_hr"].notna()].reset_index(drop=True)
+        require(not data.empty, f"Non-parsable time values in kinetic block for {channel!r}")
+
+        first_relative_time = float(data["__time_hr"].iloc[0])
+        data["__time_hr"] = float(elapsed_h) + (data["__time_hr"] - first_relative_time)
+
+        melted = data.melt(
+            id_vars=["__time_hr"],
+            value_vars=wells,
+            var_name="position",
+            value_name="value",
+        ).rename(columns={"__time_hr": "time"})
+        melted["channel"] = channel
+        melted["sheet_index"] = sheet_index
+        melted["sheet_name"] = sheet_name
+        melted["source"] = "kinetic"
+        parts.append(melted)
+
+    require(parts, f"No configured kinetic channel blocks found in sheet {sheet_name!r}")
+    result = coerce_measurements(pd.concat(parts, ignore_index=True), source="kinetic")
+
+    if raw_to_resolved:
+        pairs = [
+            f"{raw!r} → {raw_to_canonical.get(raw, '?')!r} → {raw_to_resolved[raw]!r}"
+            for raw in sorted(raw_to_resolved)
+        ]
+        logger.debug("channel normalization (kinetic, sheet %s): %s", sheet_name, "; ".join(pairs))
+
+    return result

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

@@ -0,0 +1,295 @@
+from __future__ import annotations
+
+import logging
+import math
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from ._kinetic import tidy_kinetic_blocks
+from ._shared import (
+    ensure_excel_path,
+    extract_sheet_datetime,
+    is_blank_measurement,
+    normalize_channel_map,
+    normalize_time_series,
+    require,
+    require_unique_measurements,
+    resolve_channel,
+)
+from ._snapshot import tidy_snapshot_block
+
+
+def _selected_sheets(excel: pd.ExcelFile, sheet_names: Sequence[str] | None) -> list[str]:
+    sheets = list(sheet_names or excel.sheet_names)
+    require(sheets, "Workbook has no sheets")
+    for sheet in sheets:
+        require(sheet in excel.sheet_names, f"Sheet {sheet!r} not found in workbook")
+    return sheets
+
+
+def _elapsed_hours_by_sheet(excel: pd.ExcelFile, sheets: Sequence[str]) -> dict[str, float]:
+    datetimes = {sheet: extract_sheet_datetime(excel, sheet) for sheet in sheets}
+    first_datetime = min(datetimes.values())
+    return {sheet: (value - first_datetime).total_seconds() / 3600.0 for sheet, value in datetimes.items()}
+
+
+def _split_snapshot_vs_kinetic(
+    frame: pd.DataFrame,
+    *,
+    channels: Sequence[str] | None,
+    channel_map_ci: Mapping[str, str],
+) -> tuple[pd.DataFrame | None, pd.DataFrame | None]:
+    def row_has(index: int, keyword: str) -> bool:
+        return frame.iloc[index].astype(str).str.contains(keyword, case=False, na=False).any()
+
+    results_index = next((index for index in frame.index if row_has(index, "Results")), None)
+    if results_index is None:
+        return None, None
+
+    start = results_index + 1
+    for index in frame.index[start:]:
+        if frame.iloc[index].dropna(how="all").empty:
+            start = index + 1
+            break
+    time_index = next((index for index in frame.index[start:] if row_has(index, "Time")), None)
+
+    def starts_kinetic_block(index: int) -> bool:
+        first_cell = frame.iat[index, 0]
+        if is_blank_measurement(first_cell):
+            return False
+        return resolve_channel(str(first_cell), channels=channels, channel_map_ci=channel_map_ci) is not None
+
+    channel_index = next((index for index in frame.index[start:] if starts_kinetic_block(index)), None)
+    boundaries = [index for index in (time_index, channel_index) if index is not None]
+    cut = min(boundaries) if boundaries else None
+    snapshot = (
+        frame.iloc[start:cut].reset_index(drop=True) if cut is not None else frame.iloc[start:].reset_index(drop=True)
+    )
+    kinetic = frame.iloc[cut:].reset_index(drop=True) if cut is not None else None
+    return snapshot, kinetic
+
+
+def _find_kinetic_section(
+    frame: pd.DataFrame,
+    *,
+    sheet_name: str,
+    channels: Sequence[str] | None,
+    channel_map_ci: Mapping[str, str],
+) -> pd.DataFrame | None:
+    for index in frame.index:
+        cell = str(frame.iat[index, 0]).strip()
+        if not cell:
+            continue
+        try:
+            resolved = resolve_channel(cell, channels=channels, channel_map_ci=channel_map_ci)
+        except ValueError as error:
+            raise ValueError(f"{error} in kinetic sheet {sheet_name!r}") from error
+        if resolved is not None:
+            return frame.iloc[index:].reset_index(drop=True)
+    return None
+
+
+def _finalize_measurements(
+    frame: pd.DataFrame,
+    *,
+    channels: Sequence[str] | None,
+    expected_channels: set[str],
+    missing_message: str,
+    time_round_decimals: int | None,
+    time_step_h: float | None,
+    time_offset_h: float,
+    filter_to_channels: bool,
+) -> pd.DataFrame:
+    require(not isinstance(time_offset_h, (bool, np.bool_)), "time_offset_h must not be a boolean")
+    require(math.isfinite(time_offset_h), "time_offset_h must be finite")
+    require(time_offset_h >= 0.0, "time_offset_h must be greater than or equal to 0")
+    result = frame
+    if filter_to_channels and channels:
+        result = result[result["channel"].isin(channels)].reset_index(drop=True)
+
+    result["time"] = normalize_time_series(
+        result["time"],
+        time_round_decimals=time_round_decimals,
+        time_step_h=time_step_h,
+    )
+    with np.errstate(over="ignore", invalid="ignore"):
+        result["time"] = result["time"] + float(time_offset_h)
+    require(
+        result["time"].map(math.isfinite).all(),
+        "time values must remain finite after applying time_offset_h",
+    )
+    if time_round_decimals is not None:
+        with np.errstate(over="ignore", invalid="ignore"):
+            result["time"] = result["time"].round(int(time_round_decimals))
+    require(
+        result["time"].map(math.isfinite).all(),
+        "time values must remain finite after applying time_offset_h",
+    )
+    result["value"] = pd.to_numeric(result["value"], errors="raise")
+    require(result["time"].ge(0).all(), "Internal error: negative time encountered after alignment")
+    require(result["time"].notna().all(), "Internal error: time contains NaN after alignment")
+
+    missing = expected_channels - set(result["channel"].astype(str).unique())
+    require(not missing, f"{missing_message}: {sorted(missing)}")
+
+    result["position"] = result["position"].astype(str)
+    result["channel"] = result["channel"].astype(str)
+    require_unique_measurements(result)
+    return result.reset_index(drop=True)
+
+
+def parse_snapshot_and_timeseries(
+    path: str | Path,
+    *,
+    channels: Sequence[str] | None = None,
+    channel_map: Mapping[str, str] | None = None,
+    sheet_names: Sequence[str] | None = None,
+    time_round_decimals: int | None = 12,
+    time_step_h: float | None = None,
+    time_offset_h: float = 0.0,
+    include_snapshot: bool = True,
+    include_kinetic: bool = True,
+) -> pd.DataFrame:
+    """Parse snapshot and kinetic blocks from one Synergy H1 workbook."""
+    workbook = Path(path)
+    ensure_excel_path(workbook)
+    channel_map_ci = normalize_channel_map(channel_map)
+    require(channels or channel_map_ci, "Provide either 'channels' or 'channel_map'")
+    expected_channels = set(channels or channel_map_ci.values())
+
+    frames: list[pd.DataFrame] = []
+    map_free_raw_by_channel: dict[str, tuple[str, str, str]] = {}
+    with pd.ExcelFile(workbook) as excel:
+        sheets = _selected_sheets(excel, sheet_names)
+        elapsed_by_sheet = _elapsed_hours_by_sheet(excel, sheets)
+        for sheet_index, sheet in enumerate(sheets):
+            raw = excel.parse(sheet_name=sheet, header=None, dtype=str)
+            snapshot, kinetic = _split_snapshot_vs_kinetic(
+                raw,
+                channels=channels,
+                channel_map_ci=channel_map_ci,
+            )
+
+            if include_snapshot and snapshot is not None and not snapshot.empty:
+                frames.append(
+                    tidy_snapshot_block(
+                        snapshot,
+                        elapsed_h=elapsed_by_sheet[sheet],
+                        sheet_index=sheet_index,
+                        sheet_name=sheet,
+                        channels=channels,
+                        channel_map_ci=channel_map_ci,
+                    )
+                )
+                declared_channels = sorted(set(channels or channel_map_ci.values()))
+                logging.getLogger("reader").debug(
+                    "channel normalization (snapshot, sheet %s): declared=%s",
+                    sheet,
+                    declared_channels,
+                )
+            if include_kinetic and kinetic is not None and not kinetic.empty:
+                frames.append(
+                    tidy_kinetic_blocks(
+                        kinetic,
+                        elapsed_h=elapsed_by_sheet[sheet],
+                        sheet_index=sheet_index,
+                        sheet_name=sheet,
+                        channels=channels,
+                        channel_map_ci=channel_map_ci,
+                        map_free_raw_by_channel=map_free_raw_by_channel,
+                    )
+                )
+
+    require(frames, f"No parsable data found in {workbook.name}")
+    result = pd.concat(frames, ignore_index=True)
+
+    requested_sources = {
+        source for source, requested in (("snapshot", include_snapshot), ("kinetic", include_kinetic)) if requested
+    }
+    sheet_has_snapshot = result.groupby("sheet_index")["source"].transform(lambda values: (values == "snapshot").any())
+    sheet_min_time = result.groupby("sheet_index")["time"].transform("min")
+    overlapping_initial_kinetic = (
+        (result["source"] == "kinetic") & sheet_has_snapshot & (result["time"] == sheet_min_time)
+    )
+    result = result.loc[~overlapping_initial_kinetic]
+
+    observed_sources = set(result["source"].astype(str).unique())
+    missing_sources = requested_sources - observed_sources
+    require(not missing_sources, f"Missing requested Synergy data sources: {sorted(missing_sources)}")
+    for source in sorted(requested_sources):
+        observed_channels = set(result.loc[result["source"] == source, "channel"].astype(str).unique())
+        missing_source_channels = expected_channels - observed_channels
+        require(
+            not missing_source_channels,
+            f"{source.title()} data missing for channels: {sorted(missing_source_channels)}",
+        )
+
+    return _finalize_measurements(
+        result,
+        channels=channels,
+        expected_channels=expected_channels,
+        missing_message="Missing data for channels",
+        time_round_decimals=time_round_decimals,
+        time_step_h=time_step_h,
+        time_offset_h=time_offset_h,
+        filter_to_channels=True,
+    )
+
+
+def parse_kinetic_only(
+    path: str | Path,
+    *,
+    channels: Sequence[str] | None = None,
+    channel_map: Mapping[str, str] | None = None,
+    sheet_names: Sequence[str] | None = None,
+    time_round_decimals: int | None = 12,
+    time_step_h: float | None = None,
+    time_offset_h: float = 0.0,
+) -> pd.DataFrame:
+    """Parse kinetic blocks from one Synergy H1 workbook."""
+    workbook = Path(path)
+    ensure_excel_path(workbook)
+    channel_map_ci = normalize_channel_map(channel_map)
+    require(channels or channel_map_ci, "Provide either 'channels' or 'channel_map'")
+
+    frames: list[pd.DataFrame] = []
+    map_free_raw_by_channel: dict[str, tuple[str, str, str]] = {}
+    with pd.ExcelFile(workbook) as excel:
+        sheets = _selected_sheets(excel, sheet_names)
+        elapsed_by_sheet = _elapsed_hours_by_sheet(excel, sheets)
+        for sheet_index, sheet in enumerate(sheets):
+            raw = excel.parse(sheet_name=sheet, header=None, dtype=str)
+            kinetic = _find_kinetic_section(
+                raw,
+                sheet_name=sheet,
+                channels=channels,
+                channel_map_ci=channel_map_ci,
+            )
+            require(kinetic is not None, f"No kinetic data found in sheet {sheet!r}")
+            frames.append(
+                tidy_kinetic_blocks(
+                    kinetic,
+                    elapsed_h=elapsed_by_sheet[sheet],
+                    sheet_index=sheet_index,
+                    sheet_name=sheet,
+                    channels=channels,
+                    channel_map_ci=channel_map_ci,
+                    map_free_raw_by_channel=map_free_raw_by_channel,
+                )
+            )
+
+    require(frames, f"No kinetic readings found in {workbook.name}")
+    expected_channels = {str(channel) for channel in (channels or channel_map_ci.values())}
+    return _finalize_measurements(
+        pd.concat(frames, ignore_index=True),
+        channels=channels,
+        expected_channels=expected_channels,
+        missing_message="Kinetic data missing for channels",
+        time_round_decimals=time_round_decimals,
+        time_step_h=time_step_h,
+        time_offset_h=time_offset_h,
+        filter_to_channels=False,
+    )

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

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Mapping, Sequence
+from datetime import datetime
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+
+def require(condition: bool, message: str) -> None:
+    if not condition:
+        raise ValueError(message)
+
+
+def drop_all_empty_rows(frame: pd.DataFrame) -> pd.DataFrame:
+    with pd.option_context("future.no_silent_downcasting", True):
+        normalized = frame.replace(r"^\s*$", pd.NA, regex=True)
+    return normalized.infer_objects(copy=False).dropna(how="all").reset_index(drop=True)
+
+
+def ensure_excel_path(path: Path) -> None:
+    require(path.exists(), f"Input file not found: {path}")
+    require(path.is_file(), f"Synergy H1 input is not a regular file: {path}")
+    require(
+        path.suffix.lower() == ".xlsx",
+        f"Synergy H1 ingest requires a modern .xlsx workbook, got {path.suffix or '<no extension>'!r}",
+    )
+
+
+def require_unique_measurements(frame: pd.DataFrame) -> None:
+    keys = ["position", "channel", "time"]
+    duplicate_mask = frame.duplicated(subset=keys, keep=False)
+    if not duplicate_mask.any():
+        return
+    preview = frame.loc[duplicate_mask, keys].drop_duplicates().head(8).to_dict(orient="records")
+    raise ValueError(f"Synergy measurements must be unique by {keys}; duplicate keys include {preview}")
+
+
+def probe_synergy_workbook(path: str | Path) -> tuple[str, ...]:
+    """Open a Synergy workbook and return its sheet names without parsing sheet data."""
+    workbook = Path(path)
+    ensure_excel_path(workbook)
+    with pd.ExcelFile(workbook) as excel:
+        return tuple(str(sheet) for sheet in excel.sheet_names)
+
+
+def extract_sheet_datetime(excel: pd.ExcelFile, sheet: str) -> datetime:
+    metadata = excel.parse(sheet_name=sheet, header=None, nrows=20, dtype=str)
+
+    def row_has(index: int, pattern: str) -> bool:
+        return metadata.iloc[index].astype(str).str.fullmatch(pattern, case=False).any()
+
+    date_row = next((index for index in metadata.index if row_has(index, r"Date")), None)
+    time_row = next((index for index in metadata.index if row_has(index, r"Time")), None)
+    require(date_row is not None and time_row is not None, f"Missing 'Date'/'Time' rows in sheet {sheet!r}")
+    date = pd.to_datetime(metadata.iloc[date_row, 1]).date()
+    time = pd.to_datetime(metadata.iloc[time_row, 1]).time()
+    return datetime.combine(date, time)
+
+
+def normalize_time_series(
+    time: pd.Series,
+    *,
+    time_round_decimals: int | None,
+    time_step_h: float | None,
+) -> pd.Series:
+    normalized = pd.to_numeric(time, errors="raise")
+    if time_step_h is not None:
+        step = float(time_step_h)
+        require(step > 0, "time_step_h must be > 0")
+        normalized = (normalized / step).round() * step
+    if time_round_decimals is not None:
+        decimals = int(time_round_decimals)
+        require(decimals >= 0, "time_round_decimals must be >= 0")
+        normalized = normalized.round(decimals)
+    return normalized
+
+
+def canonical_channel(value: str) -> str:
+    raw = str(value or "").strip()
+    prefix, separator, suffix = raw.partition(":")
+    normalized_prefix = re.sub(r"\s+[AB]$", "", prefix.strip(), flags=re.IGNORECASE)
+    normalized_prefix = re.sub(r"\s+", " ", normalized_prefix).strip()
+    if not separator:
+        return normalized_prefix
+    normalized_suffix = re.sub(r"\s+", "", suffix)
+    return f"{normalized_prefix}:{normalized_suffix}"
+
+
+_OVERFLOW_TOKENS = frozenset({"overflow", "ovrflw", "ovr", "over", "inf", "infinity", "∞"})
+_GREATER_THAN_NUMBER = re.compile(r"^>\s*[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$")
+
+
+def is_overflow_token(value: object) -> bool:
+    normalized = str(value or "").strip()
+    if not normalized:
+        return False
+    return normalized.lower() in _OVERFLOW_TOKENS or bool(_GREATER_THAN_NUMBER.fullmatch(normalized))
+
+
+def normalize_channel_map(channel_map: Mapping[str, str] | None) -> Mapping[str, str]:
+    if not channel_map:
+        return {}
+    normalized: dict[str, str] = {}
+    for raw_label, output_channel in channel_map.items():
+        key = canonical_channel(str(raw_label)).lower()
+        value = str(output_channel).strip()
+        require(key != "", "channel_map keys must contain a channel label")
+        require(value != "", f"channel_map[{raw_label!r}] must name an output channel")
+        require(
+            key not in normalized,
+            f"Duplicate channel_map declaration after normalization: {raw_label!r} resolves to {key!r}",
+        )
+        normalized[key] = value
+    return normalized
+
+
+def resolve_channel_from_map(raw_label: str, *, channel_map_ci: Mapping[str, str]) -> str | None:
+    label = canonical_channel(raw_label).lower()
+    return channel_map_ci.get(label)
+
+
+def resolve_channel(
+    raw_label: str,
+    *,
+    channels: Sequence[str] | None,
+    channel_map_ci: Mapping[str, str],
+) -> str | None:
+    normalized_label = canonical_channel(raw_label).lower()
+    mapped = resolve_channel_from_map(raw_label, channel_map_ci=channel_map_ci)
+    if mapped is not None:
+        return mapped
+
+    if channels:
+        declared = [(canonical_channel(channel).lower(), channel) for channel in channels]
+        matches = [channel for normalized, channel in declared if normalized == normalized_label]
+        if not matches and not channel_map_ci and ":" in normalized_label:
+            base_label = normalized_label.partition(":")[0]
+            matches = [channel for normalized, channel in declared if normalized == base_label]
+        require(
+            len(matches) <= 1,
+            f"Ambiguous configured channels for raw label {raw_label!r}: {matches}",
+        )
+        return matches[0] if matches else None
+
+    if channel_map_ci:
+        return None
+    raise ValueError("Provide at least one of: channels or channel_map")
+
+
+def time_column(header: Iterable[str]) -> str:
+    for value in header:
+        if str(value).strip().lower().startswith("time"):
+            return str(value)
+    raise ValueError("Time column not found in kinetic block header")
+
+
+def well_headers(header: Iterable[str]) -> list[str]:
+    candidates = [str(value).strip() for value in header if re.fullmatch(r"[A-H][0-9]+", str(value).strip())]
+    invalid = [value for value in candidates if not re.fullmatch(r"[A-H](?:[1-9]|1[0-2])", value)]
+    require(not invalid, f"Kinetic header contains positions outside the 96-well range A1..H12: {invalid}")
+    duplicates = sorted({value for value in candidates if candidates.count(value) > 1})
+    require(not duplicates, f"Kinetic header contains duplicate well columns: {duplicates}")
+    return candidates
+
+
+def is_blank_measurement(value: object) -> bool:
+    return value is None or bool(pd.isna(value)) or str(value).strip() == ""
+
+
+def coerce_measurements(frame: pd.DataFrame, *, source: str) -> pd.DataFrame:
+    result = frame.loc[~frame["value"].map(is_blank_measurement)].copy()
+    if result.empty:
+        result["overflow"] = pd.Series(dtype=bool)
+        result["value"] = pd.Series(dtype=float)
+        return result
+
+    raw_values = result["value"].astype(str)
+    overflow = raw_values.map(is_overflow_token)
+    numeric = pd.to_numeric(raw_values, errors="coerce")
+    invalid = numeric.isna() & ~overflow
+    if invalid.any():
+        index = invalid[invalid].index[0]
+        row = result.loc[index]
+        raise ValueError(
+            f"Invalid {source} measurement token {raw_values.loc[index]!r} in sheet {row['sheet_name']!r}, "
+            f"channel {row['channel']!r}, well {row['position']!r}"
+        )
+
+    result["overflow"] = overflow.astype(bool)
+    result["value"] = numeric.astype(float)
+    result.loc[overflow, "value"] = np.inf
+    return result.reset_index(drop=True)