reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/plugins/transform/sample_map.py

@@ -0,0 +1,170 @@
+"""Merge tidy measurement table with a sample metadata map. Cleans the map by:
+  1) dropping all-empty columns
+  2) dropping positions that carry no metadata beyond 'position'
+  3) asserting remaining raw positions exist in the map
+Then merges many:1 on 'position'."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+from pydantic import Field
+
+from reader_workbench.domains.plate_reader.io.sample_map import parse_sample_map
+from reader_workbench.errors import MergeError
+from reader_workbench.workbench.ports import dataframe_input, dataframe_output, file_path_input
+from reader_workbench.workbench.registry import Plugin, PluginConfig
+
+
+class SampleMapCfg(PluginConfig):
+    """
+    Flexible plate-map merge.
+    - require_columns: metadata columns that MUST exist after merge (presence-only by default).
+    - require_non_null: if true, also assert these columns are non-null for all merged rows.
+    """
+
+    require_columns: list[str] = Field(default_factory=list)
+    require_non_null: bool = False
+
+
+class SampleMapMerge(Plugin):
+    ConfigModel = SampleMapCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {
+            "df": dataframe_input("df", "tidy.v1"),
+            "sample_map": file_path_input("sample_map"),
+        }
+
+    @classmethod
+    def output_ports(cls):
+        return cls.promoted_output_ports(
+            outputs={"df": dataframe_output("df", "tidy.v1")},
+            promotions={"df": ("plate_reader.annotated.v1",)},
+            note="promotion requires mapped metadata columns that satisfy the richer contract",
+        )
+
+    def resolve_output_ports(self, *, inputs, outputs, cfg, where):
+        del inputs, cfg
+        resolved = dict(self.output_ports())
+        merged = outputs.get("df")
+        if not isinstance(merged, pd.DataFrame):
+            return resolved
+        try:
+            self.contracts.validate(merged, contract_id="plate_reader.annotated.v1", where=f"{where}:df")
+        except Exception:
+            return resolved
+        resolved["df"] = dataframe_output("df", "plate_reader.annotated.v1", surface=resolved["df"].surface)
+        return resolved
+
+    def _clean_plate_map(self, plate_map: pd.DataFrame) -> pd.DataFrame:
+        if "position" not in plate_map.columns:
+            raise MergeError("Plate map must contain a 'position' column")
+
+        # 1) drop all-empty columns (keeps 'position' even if empty by policy)
+        pm = plate_map.copy()
+        non_all_empty = [c for c in pm.columns if c == "position" or not pm[c].isna().all()]
+        pm = pm[non_all_empty]
+
+        # 2) drop rows with no metadata beyond 'position'
+        meta_cols = [c for c in pm.columns if c != "position"]
+        if not meta_cols:
+            # map has only 'position' with no metadata → nothing to merge
+            return pm.iloc[0:0].copy()
+
+        no_meta = pm[meta_cols].isna().all(axis=1)
+        pm = pm.loc[~no_meta].copy()
+
+        return pm
+
+    def run(self, ctx, inputs, cfg: SampleMapCfg):
+        df: pd.DataFrame = inputs["df"]
+        sm_path: Path = inputs["sample_map"]
+
+        try:
+            sm_raw = parse_sample_map(sm_path)
+            sm = self._clean_plate_map(sm_raw)
+            if sm.empty:
+                raise MergeError("Plate map has no usable metadata rows after cleaning")
+
+            # A position row with no metadata explicitly excludes that well from annotated output.
+            removed_positions = sorted(set(sm_raw["position"].astype(str)) - set(sm["position"].astype(str)))
+            if removed_positions:
+                before = len(df)
+                df = df[~df["position"].astype(str).isin(removed_positions)].copy()
+                after = len(df)
+                try:
+                    ctx.logger.info(
+                        "[muted]sample_map: dropped %d raw rows (%d positions without metadata)[/muted]",
+                        before - after,
+                        len(removed_positions),
+                    )
+                    head = ", ".join(removed_positions[:20])
+                    tail = " …" if len(removed_positions) > 20 else ""
+                    ctx.logger.debug("sample_map: removed positions: %s%s", head, tail)
+                    # Optional arithmetic trace (best-effort; relies on tidy schema)
+                    try:
+                        chans = df["channel"].astype(str).nunique()
+                        avg_rows_per_pos = (before - after) / max(len(removed_positions), 1)
+                        approx_time_slices = round(avg_rows_per_pos / max(chans, 1))
+                        ctx.logger.debug(
+                            "sample_map: consistency hint • removed_positions=%d • channels=%d • ~time_slices_per_channel=%d",
+                            len(removed_positions),
+                            chans,
+                            approx_time_slices,
+                        )
+                    except Exception:
+                        pass
+                except Exception:
+                    pass
+
+            # 3) ensure all remaining raw positions exist in the (cleaned) map
+            raw_positions = set(df["position"].astype(str).unique())
+            map_positions = set(sm["position"].astype(str).unique())
+            missing = sorted(raw_positions - map_positions)
+            if missing:
+                raise MergeError(
+                    f"Plate map missing entries for positions: {missing[:40]}{'…' if len(missing) > 40 else ''}"
+                )
+
+            merged = df.merge(sm, on="position", how="left", validate="m:1")
+
+            # Optional dtype normalization for 'batch' when present
+            if "batch" in merged.columns:
+                try:
+                    merged["batch"] = pd.to_numeric(merged["batch"], errors="raise").astype("Int64")
+                except Exception as e:
+                    raise MergeError(f"'batch' must be integer-typed: {e}") from e
+
+            # Assert required metadata columns per-experiment (config-driven)
+            missing_cols = [c for c in cfg.require_columns if c not in merged.columns]
+            if missing_cols:
+                raise MergeError(f"Required metadata column(s) missing after merge: {missing_cols}")
+            if cfg.require_non_null and cfg.require_columns:
+                nulls = {c: int(merged[c].isna().sum()) for c in cfg.require_columns}
+                bad = {c: n for c, n in nulls.items() if n > 0}
+                if bad:
+                    raise MergeError(f"Required metadata column(s) contain NaN: {bad}")
+
+            # Concise merge summary.
+            try:
+                added_cols = [c for c in merged.columns if c not in df.columns]
+                ctx.logger.info(
+                    "sample_map • positions: raw=%d • map=%d • intersect=%d • added_cols=%d [%s]",
+                    len(raw_positions),
+                    len(map_positions),
+                    len(raw_positions & map_positions),
+                    len(added_cols),
+                    ", ".join(added_cols[:6]) + (" …" if len(added_cols) > 6 else ""),
+                )
+            except Exception:
+                pass
+
+        except MergeError:
+            raise
+        except Exception as e:
+            raise MergeError(str(e)) from e
+
+        return {"df": merged}

reader_workbench/plugins/transform/sample_metadata.py

@@ -0,0 +1,94 @@
+"""Merge tidy measurements with a sample metadata table (keyed by sample_id by default)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+from pydantic import Field
+
+from reader_workbench.errors import MergeError
+from reader_workbench.workbench.ports import dataframe_input, dataframe_output, file_path_input
+from reader_workbench.workbench.registry import Plugin, PluginConfig
+
+
+class SampleMetadataCfg(PluginConfig):
+    key: str = "sample_id"
+    require_columns: list[str] = Field(default_factory=list)
+    require_non_null: bool = False
+
+
+class SampleMetadataMerge(Plugin):
+    ConfigModel = SampleMetadataCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {
+            "df": dataframe_input("df", "tidy.v1"),
+            "metadata": file_path_input("metadata"),
+        }
+
+    @classmethod
+    def output_ports(cls):
+        return {"df": dataframe_output("df", "tidy.v1")}
+
+    def _load_metadata(self, path: Path) -> pd.DataFrame:
+        if not path.exists():
+            raise MergeError(f"Metadata file does not exist: {path}")
+        if not path.is_file():
+            raise MergeError(f"Metadata path must be a regular file: {path}")
+        suffix = path.suffix.lower()
+        if suffix == ".xlsx":
+            return pd.read_excel(path)
+        if suffix == ".csv":
+            return pd.read_csv(path)
+        raise MergeError(f"Unsupported metadata format {suffix or '<none>'!r}; expected .csv or .xlsx")
+
+    def run(self, ctx, inputs, cfg: SampleMetadataCfg):
+        df: pd.DataFrame = inputs["df"]
+        meta_path: Path = inputs["metadata"]
+        key = str(cfg.key)
+
+        try:
+            meta = self._load_metadata(meta_path)
+        except Exception as e:
+            raise MergeError(f"Failed to read metadata file {meta_path}: {e}") from e
+
+        if key not in df.columns:
+            raise MergeError(f"Metadata merge key '{key}' missing from input dataframe")
+        if key not in meta.columns:
+            raise MergeError(f"Metadata merge key '{key}' missing from metadata file")
+        missing_keys = meta[key].isna() | meta[key].astype("string").str.strip().eq("")
+        if missing_keys.any():
+            rows = [int(index) + 2 for index in meta.index[missing_keys].tolist()]
+            raise MergeError(f"Metadata merge key '{key}' is blank at file rows: {rows}")
+        duplicate_keys = sorted(meta.loc[meta[key].duplicated(keep=False), key].astype(str).unique().tolist())
+        if duplicate_keys:
+            raise MergeError(f"Metadata merge key '{key}' must be unique; duplicates: {duplicate_keys}")
+
+        try:
+            merged = df.merge(meta, on=key, how="left", validate="m:1")
+        except (TypeError, ValueError, pd.errors.MergeError) as exc:
+            raise MergeError(f"Metadata merge failed for key '{key}': {exc}") from exc
+
+        missing_cols = [c for c in cfg.require_columns if c not in merged.columns]
+        if missing_cols:
+            raise MergeError(f"Required metadata column(s) missing after merge: {missing_cols}")
+        if cfg.require_non_null and cfg.require_columns:
+            nulls = {c: int(merged[c].isna().sum()) for c in cfg.require_columns}
+            bad = {c: n for c, n in nulls.items() if n > 0}
+            if bad:
+                raise MergeError(f"Required metadata column(s) contain NaN: {bad}")
+
+        try:
+            added_cols = [c for c in merged.columns if c not in df.columns]
+            ctx.logger.info(
+                "sample_metadata • rows=%d • added_cols=%d [%s]",
+                len(merged),
+                len(added_cols),
+                ", ".join(added_cols[:6]) + (" …" if len(added_cols) > 6 else ""),
+            )
+        except Exception:
+            pass
+
+        return {"df": merged}

reader_workbench/plugins/validator/__init__.py

@@ -0,0 +1 @@
+"""Built-in validators."""

reader_workbench/plugins/validator/to_tidy_plus_map.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from contextlib import suppress
+
+import numpy as np
+import pandas as pd
+from pydantic import Field
+
+from reader_workbench.errors import ExecutionError
+from reader_workbench.workbench.ports import dataframe_input, dataframe_output
+from reader_workbench.workbench.registry import Plugin, PluginConfig
+
+
+class PromoteCfg(PluginConfig):
+    require_columns: list[str] = Field(default_factory=lambda: ["treatment", "design_id"])
+    require_non_null: bool = True  # be strict when promoting
+    trim_and_require_non_blank: list[str] = Field(default_factory=list)
+    require_finite: list[str] = Field(default_factory=list)
+    allow_instrument_overflow: list[str] = Field(default_factory=list)
+    # Only promote a subset of rows (e.g., samples). If provided, we require the column to exist.
+    type_column: str = "type"
+    include_types: list[str] = Field(default_factory=list)  # e.g., ["SAMPLE"]
+    # Deterministically drop rows with NULL in these columns before assertions.
+    drop_where_null_in: list[str] = Field(default_factory=list)
+    synthesize_batch: bool = False
+    synthesized_batch_value: int = 0
+
+
+class PromoteToTidyPlusMap(Plugin):
+    ConfigModel = PromoteCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"df": dataframe_input("df", "tidy.v1")}
+
+    @classmethod
+    def output_ports(cls):
+        return {"df": dataframe_output("df", "plate_reader.annotated.v1")}
+
+    def run(self, ctx, inputs, cfg: PromoteCfg):
+        df: pd.DataFrame = inputs["df"].copy()
+
+        # 0) Optional row filtering by "type" (case-insensitive exact match)
+        if cfg.include_types:
+            if cfg.type_column not in df.columns:
+                raise ExecutionError(
+                    f"to_tidy_plus_map: include_types was provided but column {cfg.type_column!r} is missing"
+                )
+            keep = {str(x).casefold() for x in cfg.include_types}
+            before = len(df)
+            df = df[df[cfg.type_column].astype(str).str.casefold().isin(keep)].copy()
+            with suppress(Exception):
+                ctx.logger.info(
+                    "to_tidy_plus_map: filtered rows by %r ∈ %s → kept %d/%d",
+                    cfg.type_column,
+                    sorted(cfg.include_types),
+                    len(df),
+                    before,
+                )
+            if df.empty:
+                raise ExecutionError(
+                    f"to_tidy_plus_map: no rows remain after filtering by {cfg.type_column} ∈ {cfg.include_types}"
+                )
+
+        # 0b) Optional: drop rows with NULL in specific columns
+        if cfg.drop_where_null_in:
+            missing_cols = [c for c in cfg.drop_where_null_in if c not in df.columns]
+            if missing_cols:
+                raise ExecutionError(f"to_tidy_plus_map: drop_where_null_in refers to missing columns: {missing_cols}")
+            before = len(df)
+            df = df.dropna(subset=list(cfg.drop_where_null_in)).copy()
+            with suppress(Exception):
+                ctx.logger.info(
+                    "to_tidy_plus_map: dropped %d row(s) with NULL in %s",
+                    before - len(df),
+                    list(cfg.drop_where_null_in),
+                )
+
+        if "batch" not in df.columns or df["batch"].isna().all():
+            if cfg.synthesize_batch:
+                df = df.copy()
+                df["batch"] = int(cfg.synthesized_batch_value)
+                with suppress(Exception):
+                    ctx.logger.info(
+                        "to_tidy_plus_map: 'batch' missing → added constant %d for all rows (explicit config)",
+                        int(cfg.synthesized_batch_value),
+                    )
+        elif df["batch"].isna().any() and cfg.synthesize_batch:
+            df = df.copy()
+            df["batch"] = df["batch"].fillna(int(cfg.synthesized_batch_value))
+        missing = [c for c in cfg.require_columns if c not in df.columns]
+        if missing:
+            raise ExecutionError(f"Cannot promote to plate_reader.annotated.v1; missing columns: {missing}")
+        validation_columns = (
+            set(cfg.trim_and_require_non_blank) | set(cfg.require_finite) | set(cfg.allow_instrument_overflow)
+        )
+        missing_validation = sorted(validation_columns - set(df.columns))
+        if missing_validation:
+            raise ExecutionError(
+                "Cannot promote to plate_reader.annotated.v1; configured validation refers to "
+                f"missing columns: {missing_validation}"
+            )
+        unvalidated_overflow = sorted(set(cfg.allow_instrument_overflow) - set(cfg.require_finite))
+        if unvalidated_overflow:
+            raise ExecutionError(
+                f"Cannot promote; allow_instrument_overflow must name columns in require_finite: {unvalidated_overflow}"
+            )
+        if cfg.require_non_null:
+            bad = {c: int(df[c].isna().sum()) for c in cfg.require_columns if df[c].isna().any()}
+            if bad:
+                raise ExecutionError(f"Cannot promote; required columns contain NaN: {bad}")
+        blank: dict[str, int] = {}
+        for column in cfg.trim_and_require_non_blank:
+            normalized = df[column].astype("string").str.strip()
+            invalid = normalized.isna() | normalized.eq("")
+            if invalid.any():
+                blank[column] = int(invalid.sum())
+            df[column] = normalized
+        if blank:
+            raise ExecutionError(f"Cannot promote; configured identity columns contain blank values: {blank}")
+        nonfinite: dict[str, int] = {}
+        for column in cfg.require_finite:
+            numeric = pd.to_numeric(df[column], errors="coerce").to_numpy(dtype=float, na_value=np.nan)
+            invalid = ~np.isfinite(numeric)
+            if column in cfg.allow_instrument_overflow:
+                overflow_column = f"{column}_instrument_overflow"
+                bound_column = f"{column}_bound_kind"
+                missing_provenance = [name for name in (overflow_column, bound_column) if name not in df.columns]
+                if missing_provenance:
+                    raise ExecutionError(
+                        "Cannot promote; instrument-overflow validation requires provenance columns: "
+                        f"{missing_provenance}"
+                    )
+                raw_flags = df[overflow_column]
+                if raw_flags.isna().any() or not raw_flags.map(lambda value: isinstance(value, (bool, np.bool_))).all():
+                    raise ExecutionError(
+                        f"Cannot promote; {overflow_column!r} must contain booleans without missing values"
+                    )
+                declared_overflow = (
+                    np.isposinf(numeric)
+                    & raw_flags.to_numpy(dtype=bool)
+                    & df[bound_column].astype("string").eq("lower").to_numpy(dtype=bool)
+                )
+                invalid &= ~declared_overflow
+            invalid_count = int(invalid.sum())
+            if invalid_count:
+                nonfinite[column] = invalid_count
+        if nonfinite:
+            raise ExecutionError(
+                f"Cannot promote; configured measurement columns contain non-finite values: {nonfinite}"
+            )
+        # dtype normalization for 'batch' (if present)
+        if "batch" in df.columns:
+            df["batch"] = pd.to_numeric(df["batch"], errors="raise").astype("Int64")
+        return {"df": df}

reader_workbench/protocols/__init__.py

@@ -0,0 +1,80 @@
+from .builtins import BUILTIN_PROTOCOLS, builtin_protocol_catalog
+from .compiler import (
+    compile_cytometry_flow_panel,
+    compile_generic_protocol,
+    compile_logic_four_state_vector_screen,
+    compile_plate_reader_dual_reporter_screen,
+    compile_plate_reader_growth_screen,
+    compile_plate_reader_single_reporter_screen,
+)
+from .model import (
+    BoundProtocol,
+    CompiledProtocolPlan,
+    FigureKind,
+    MetricStage,
+    ProtocolArtifactSpec,
+    ProtocolBinding,
+    ProtocolBindingValueRef,
+    ProtocolCatalog,
+    ProtocolCompiler,
+    ProtocolConfigFieldSpec,
+    ProtocolControlRule,
+    ProtocolDescriptor,
+    ProtocolEffectSignSpec,
+    ProtocolExecutionPlan,
+    ProtocolFactorSpec,
+    ProtocolFigureSpec,
+    ProtocolMetricSpec,
+    ProtocolPlotProfileSpec,
+    ProtocolPluginDefaultsSpec,
+    ProtocolRankingSpec,
+    ProtocolResourceSpec,
+    ProtocolSemanticExecution,
+    ProtocolSemanticNode,
+    ProtocolSemanticProfileOverride,
+    ProtocolSemanticProfileSpec,
+    ProtocolSemanticProgram,
+    ProtocolWindowSpec,
+    RankingDirection,
+    binding_value,
+)
+
+__all__ = [
+    "BUILTIN_PROTOCOLS",
+    "BoundProtocol",
+    "CompiledProtocolPlan",
+    "FigureKind",
+    "MetricStage",
+    "ProtocolArtifactSpec",
+    "ProtocolBinding",
+    "ProtocolBindingValueRef",
+    "ProtocolCatalog",
+    "ProtocolCompiler",
+    "ProtocolConfigFieldSpec",
+    "ProtocolControlRule",
+    "ProtocolDescriptor",
+    "ProtocolExecutionPlan",
+    "ProtocolEffectSignSpec",
+    "ProtocolFactorSpec",
+    "ProtocolFigureSpec",
+    "ProtocolMetricSpec",
+    "ProtocolPlotProfileSpec",
+    "ProtocolPluginDefaultsSpec",
+    "ProtocolRankingSpec",
+    "ProtocolResourceSpec",
+    "ProtocolSemanticExecution",
+    "ProtocolSemanticNode",
+    "ProtocolSemanticProfileOverride",
+    "ProtocolSemanticProfileSpec",
+    "ProtocolSemanticProgram",
+    "ProtocolWindowSpec",
+    "RankingDirection",
+    "binding_value",
+    "builtin_protocol_catalog",
+    "compile_cytometry_flow_panel",
+    "compile_generic_protocol",
+    "compile_logic_four_state_vector_screen",
+    "compile_plate_reader_dual_reporter_screen",
+    "compile_plate_reader_growth_screen",
+    "compile_plate_reader_single_reporter_screen",
+]

reader_workbench/protocols/_builtins_plate_reader_growth.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import replace
+
+from reader_workbench.workbench.input_discovery import (
+    DEFAULT_INPUT_EXCLUDE as DEFAULT_EXCLUDE,
+)
+from reader_workbench.workbench.input_discovery import (
+    DEFAULT_WORKBOOK_INCLUDE as DEFAULT_INCLUDE,
+)
+
+from .compiler import compile_plate_reader_growth_screen
+from .model import (
+    ProtocolConfigFieldSpec,
+    ProtocolDescriptor,
+    ProtocolExecutionPlan,
+    ProtocolFigureSpec,
+    ProtocolMetricSpec,
+    ProtocolPlotProfileSpec,
+    ProtocolPluginDefaultsSpec,
+    ProtocolResourceSpec,
+    ProtocolSemanticProfileSpec,
+    binding_value,
+)
+
+
+def build_plate_reader_growth_protocol(
+    *,
+    dual_reporter_protocol: ProtocolDescriptor,
+    field_builder: Callable[..., ProtocolConfigFieldSpec],
+) -> ProtocolDescriptor:
+    """Build the one-channel growth protocol from shared plate-reader inputs."""
+
+    field = field_builder
+    ingest_field = next(item for item in dual_reporter_protocol.input_fields if item.key == "ingest")
+    channel_map_field = next(item for item in ingest_field.children if item.key == "channel_map")
+    growth_ingest = replace(
+        ingest_field,
+        children=tuple(
+            replace(
+                item,
+                summary=(
+                    "Optional raw workbook label to canonical channel mapping. Leave null for "
+                    "map-free kinetic discovery; snapshot and mixed parsing require a mapping."
+                ),
+                default={"OD600:600": "OD600"},
+            )
+            if item is channel_map_field
+            else item
+            for item in ingest_field.children
+        ),
+    )
+    inherited_preprocessing = next(
+        item for item in dual_reporter_protocol.analysis_fields if item.key == "preprocessing"
+    )
+    preprocessing_field = replace(
+        inherited_preprocessing,
+        children=tuple(
+            replace(
+                item,
+                children=tuple(
+                    replace(child, default="none") if child.key == "action" else child for child in item.children
+                ),
+            )
+            if item.key == "overflow"
+            else item
+            for item in inherited_preprocessing.children
+        ),
+    )
+
+    return ProtocolDescriptor(
+        protocol="plate_reader/growth_screen",
+        domain="plate_reader",
+        family="screen_analysis",
+        summary="One-channel plate-reader growth assay with explicit sample and treatment metadata.",
+        tags=("plate_reader", "growth", "screen", "single_channel"),
+        resources=(
+            ProtocolResourceSpec(
+                id="sample_map",
+                path="./inputs/metadata.xlsx",
+                summary="Well-to-sample metadata for the plate-reader workbook.",
+            ),
+        ),
+        input_fields=(growth_ingest,),
+        analysis_fields=(
+            field(
+                "growth_channel",
+                "Measured channel used as the growth readout.",
+                kind="string",
+                default="OD600",
+            ),
+            preprocessing_field,
+        ),
+        factors=dual_reporter_protocol.factors,
+        semantic_profiles=(
+            ProtocolSemanticProfileSpec(
+                id="growth_raw",
+                family="growth_panel",
+                summary="Growth-screen semantics over one configured measurement channel.",
+                primary_metric="Growth",
+                primary_readout="configured growth channel",
+                tags=("growth", "plate_reader", "panel"),
+            ),
+        ),
+        metrics=(
+            ProtocolMetricSpec(
+                id="Growth",
+                stage="raw",
+                summary="Raw configured growth trace.",
+                formula="configured_growth_channel",
+                profiles=("growth_raw",),
+            ),
+        ),
+        figures=(
+            ProtocolFigureSpec(
+                id="raw_kinetics",
+                kind="qc",
+                summary="Raw growth trajectories by sample and treatment.",
+                primary=True,
+            ),
+            ProtocolFigureSpec(
+                id="endpoint_by_condition",
+                kind="summary",
+                summary="Explicit-time growth comparison grouped by treatment or condition.",
+            ),
+            ProtocolFigureSpec(
+                id="endpoint_by_design",
+                kind="summary",
+                summary="Explicit-time growth comparison grouped by sample or design.",
+            ),
+            ProtocolFigureSpec(
+                id="growth_overview",
+                kind="kinetics",
+                summary="Growth trajectories and an explicitly timed endpoint in one view.",
+            ),
+            ProtocolFigureSpec(
+                id="value_distributions",
+                kind="qc",
+                summary="Distribution view of the configured growth channel.",
+            ),
+        ),
+        plot_profiles=(
+            ProtocolPlotProfileSpec(
+                id="screen_overview",
+                summary="Explicit-time growth screen review.",
+                figures=("raw_kinetics", "endpoint_by_condition", "endpoint_by_design", "growth_overview"),
+            ),
+            ProtocolPlotProfileSpec(
+                id="kinetics_qc",
+                summary="Growth trajectories and value distributions without an inferred endpoint.",
+                figures=("raw_kinetics", "value_distributions"),
+            ),
+        ),
+        default_plot_profile="kinetics_qc",
+        execution=ProtocolExecutionPlan(
+            plugin_defaults=(
+                ProtocolPluginDefaultsSpec(
+                    plugin="ingest/synergy_h1",
+                    summary="Generic one-channel plate-reader ingest settings.",
+                    with_={
+                        "mode": binding_value("ingest.mode", "kinetic_only"),
+                        "channel_map": binding_value("ingest.channel_map", {"OD600:600": "OD600"}),
+                        "sheet_names": binding_value("ingest.sheet_names", None),
+                        "time_round_decimals": binding_value("ingest.time_round_decimals", 12),
+                        "time_step_h": binding_value("ingest.time_step_h", None),
+                        "time_offset_h": binding_value("ingest.time_offset_h", 0.0),
+                        "auto_roots": binding_value("ingest.auto_roots", None),
+                        "auto_include": binding_value("ingest.auto_include", list(DEFAULT_INCLUDE)),
+                        "auto_exclude": binding_value("ingest.auto_exclude", list(DEFAULT_EXCLUDE)),
+                        "auto_pick": binding_value("ingest.auto_pick", "single"),
+                        "auto_recursive": binding_value("ingest.auto_recursive", False),
+                        "print_summary": binding_value("ingest.print_summary", True),
+                    },
+                ),
+            ),
+            compiler=compile_plate_reader_growth_screen,
+        ),
+    )