reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/plugins/transform/alias.py

@@ -0,0 +1,70 @@
+"""Alias mappings for categorical columns. Either replace in-place or create
+<column>_alias columns. Prints a succinct per-column summary of applied aliases."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from reader_workbench.plugins.transform._labeling import apply_label_mappings
+from reader_workbench.workbench.ports import dataframe_input, dataframe_output
+from reader_workbench.workbench.registry import Plugin, PluginConfig
+
+
+class AliasCfg(PluginConfig):
+    """
+    mappings:
+      <column_name>:
+        <raw_value>: <alias_value>
+        ...
+    in_place:      if true, mutate <column_name> directly; else create <column_name>_alias
+    case_insensitive: map using casefold() on incoming values (keys in 'aliases' are matched case-insensitively)
+    """
+
+    mappings: Mapping[str, Mapping[str, str]] | None = None
+    in_place: bool = False
+    case_insensitive: bool = True
+    suffix: str = "_alias"
+
+
+class AliasTransform(Plugin):
+    ConfigModel = AliasCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"df": dataframe_input("df", "tidy.v1")}
+
+    @classmethod
+    def output_ports(cls):
+        return cls.passthrough_output_ports(
+            outputs={"df": dataframe_output("df", "tidy.v1")},
+            passthrough={"df": "df"},
+            promoted_examples={"df": ("plate_reader.annotated.v1",)},
+        )
+
+    def resolve_output_ports(self, *, inputs, outputs, cfg, where):
+        del cfg
+        return self.inherit_dataframe_output_ports(
+            inputs=inputs,
+            outputs=outputs,
+            passthrough={"df": "df"},
+            where=where,
+        )
+
+    def run(self, ctx, inputs, cfg: AliasCfg):
+        if cfg.mappings is None:
+            raise ValueError("alias: provide with.mappings")
+        if not isinstance(cfg.mappings, Mapping):
+            raise ValueError("alias: mappings must be a mapping of column -> {raw: alias}")
+        mappings = {str(col): mapping for col, mapping in cfg.mappings.items()}
+        output_names = {str(col): f"{col}{cfg.suffix}" for col in mappings}
+        return {
+            "df": apply_label_mappings(
+                ctx=ctx,
+                df=inputs["df"],
+                mappings=mappings,
+                output_names=output_names,
+                in_place=cfg.in_place,
+                case_insensitive=cfg.case_insensitive,
+                label="alias",
+            )
+        }

reader_workbench/plugins/transform/assay_labels.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from reader_workbench.plugins.transform._labeling import apply_label_mappings
+from reader_workbench.workbench.ports import dataframe_input, dataframe_output
+from reader_workbench.workbench.registry import Plugin, PluginConfig
+
+
+class AnnotationLabelsCfg(PluginConfig):
+    refs: list[str] | None = None
+    in_place: bool = False
+    case_insensitive: bool = True
+    suffix: str = "_alias"
+
+
+class AnnotationLabelsTransform(Plugin):
+    ConfigModel = AnnotationLabelsCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"df": dataframe_input("df", "tidy.v1")}
+
+    @classmethod
+    def output_ports(cls):
+        return cls.passthrough_output_ports(
+            outputs={"df": dataframe_output("df", "tidy.v1")},
+            passthrough={"df": "df"},
+            promoted_examples={"df": ("plate_reader.annotated.v1",)},
+        )
+
+    def resolve_output_ports(self, *, inputs, outputs, cfg, where):
+        del cfg
+        return self.inherit_dataframe_output_ports(
+            inputs=inputs,
+            outputs=outputs,
+            passthrough={"df": "df"},
+            where=where,
+        )
+
+    def run(self, ctx, inputs, cfg: AnnotationLabelsCfg):
+        if ctx.experiment is None:
+            raise ValueError("assay_labels requires experiment annotations in the run context")
+        label_specs = ctx.experiment.annotations.resolve_label_specs(cfg.refs)
+        if not label_specs:
+            raise ValueError("assay_labels: no annotations.labels are configured")
+
+        mappings: dict[str, dict[str, str]] = {}
+        output_names: dict[str, str] = {}
+        for spec in label_specs:
+            mappings[spec.source] = dict(spec.values)
+            output_names[spec.source] = spec.output or f"{spec.source}{cfg.suffix}"
+
+        return {
+            "df": apply_label_mappings(
+                ctx=ctx,
+                df=inputs["df"],
+                mappings=mappings,
+                output_names=output_names,
+                in_place=cfg.in_place,
+                case_insensitive=cfg.case_insensitive,
+                label="assay_labels",
+            )
+        }

reader_workbench/plugins/transform/blank.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import pandas as pd
+
+from reader_workbench.workbench.ports import dataframe_input, dataframe_output
+from reader_workbench.workbench.registry import Plugin, PluginConfig
+
+
+class BlankCfg(PluginConfig):
+    method: str = "disregard"  # disregard | subtract
+    capture_blanks: bool = True
+
+
+def _detect_blanks(df: pd.DataFrame) -> pd.DataFrame:
+    out = df.copy()
+    mask = False
+    for col in ["is_blank", "blank", "isBlank"]:
+        if col in out.columns:
+            try:
+                mask = mask | out[col].astype(bool)
+            except Exception:
+                mask = mask | out[col].astype(str).str.lower().isin({"true", "1", "t", "yes"})
+    for col in ["treatment", "genotype", "sample_type"]:
+        if col in out.columns:
+            mask = mask | out[col].astype(str).str.contains("blank", case=False, na=False)
+    return out[mask].copy() if isinstance(mask, pd.Series) else out.iloc[0:0].copy()
+
+
+class BlankCorrection(Plugin):
+    ConfigModel = BlankCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"df": dataframe_input("df", "tidy.v1")}
+
+    @classmethod
+    def output_ports(cls):
+        return cls.passthrough_output_ports(
+            outputs={
+                "df": dataframe_output("df", "tidy.v1"),
+                "blanks": dataframe_output("blanks", "tidy.v1"),
+            },
+            passthrough={"df": "df", "blanks": "df"},
+            promoted_examples={
+                "df": ("plate_reader.annotated.v1",),
+                "blanks": ("plate_reader.annotated.v1",),
+            },
+        )
+
+    def resolve_output_ports(self, *, inputs, outputs, cfg, where):
+        del cfg
+        return self.inherit_dataframe_output_ports(
+            inputs=inputs,
+            outputs=outputs,
+            passthrough={"df": "df", "blanks": "df"},
+            where=where,
+        )
+
+    def run(self, ctx, inputs, cfg: BlankCfg):
+        df: pd.DataFrame = inputs["df"].copy()
+        blanks = _detect_blanks(df)
+        if cfg.method == "disregard":
+            return {"df": df, "blanks": blanks}
+        if cfg.method == "subtract":
+            if blanks.empty:
+                return {"df": df, "blanks": blanks}
+            corr = (
+                blanks.assign(value=pd.to_numeric(blanks["value"], errors="coerce"))
+                .groupby("channel")["value"]
+                .median()
+                .rename("__blank__")
+            )
+            out = df.copy()
+            out["value"] = pd.to_numeric(out["value"], errors="coerce")
+            out = out.join(corr, on="channel")
+            out["value"] = out["value"] - out["__blank__"].fillna(0.0)
+            out = out.drop(columns="__blank__")
+            return {"df": out, "blanks": blanks}
+        raise ValueError(f"unknown method {cfg.method}")

reader_workbench/plugins/transform/crosstalk_pairs.py

@@ -0,0 +1,180 @@
+"""Crosstalk pairing transform over fold_change.v1 tables."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+import pandas as pd
+from pydantic import Field
+
+from reader_workbench.domains.logic.crosstalk import compute_crosstalk_pairs
+from reader_workbench.workbench.ports import dataframe_input, dataframe_output
+from reader_workbench.workbench.registry import Plugin, PluginConfig
+
+
+def _pick_alias(df: pd.DataFrame, base: str | None) -> str | None:
+    if not base:
+        return None
+    alias = f"{base}_alias"
+    if base in df.columns:
+        return base
+    if alias in df.columns:
+        return alias
+    return None
+
+
+class CrosstalkPairsCfg(PluginConfig):
+    value_column: str = "log2FC"
+    value_scale: Literal["log2", "linear"] = Field(..., description="Scale of value_column.")
+
+    target: str | None = None
+    time_mode: Literal["single", "exact", "nearest", "latest", "all"] = Field(
+        ..., description="How to select time(s) from the fold_change table."
+    )
+    time_policy: Literal["per_time", "all"] = Field(
+        "per_time", description="How to handle multiple times after selection."
+    )
+    time: float | None = None
+    times: list[float] | None = None
+    time_tolerance: float = 0.51
+    time_column: str = "time"
+
+    mapping_mode: Literal["explicit", "column", "top1"] = Field(
+        ..., description="How to map design_id -> cognate treatment."
+    )
+    design_column: str = "design_id"
+    treatment_column: str = "treatment"
+    design_treatment_column: str | None = None
+    design_treatment_map: dict[str, str] = Field(default_factory=dict)
+    design_treatment_overrides: dict[str, str] = Field(default_factory=dict)
+    top1_tie_policy: Literal["error", "alphabetical"] = "error"
+    top1_tie_tolerance: float = 0.0
+
+    agg: Literal["median", "mean"] = "median"
+
+    require_self_treatment: bool = True
+    require_self_is_top1: bool = False
+
+    min_self: float | None = None
+    max_cross: float | None = None
+    max_other: float | None = None
+    min_self_minus_best_other: float | None = None
+    min_self_ratio_best_other: float | None = None
+    min_selectivity_delta: float | None = None
+    min_selectivity_ratio: float | None = None
+
+    only_passing: bool = True
+    top_n: int = 10
+
+
+class CrosstalkPairs(Plugin):
+    """Compute crosstalk-safe design pairings from a fold_change.v1 table."""
+
+    ConfigModel = CrosstalkPairsCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"table": dataframe_input("table", "fold_change.v1")}
+
+    @classmethod
+    def output_ports(cls):
+        return {"table": dataframe_output("table", "crosstalk_pairs.v1")}
+
+    def run(self, ctx, inputs: dict[str, Any], cfg: CrosstalkPairsCfg) -> dict[str, Any]:
+        df = inputs["table"].copy()
+
+        dcol = _pick_alias(df, cfg.design_column)
+        tcol = _pick_alias(df, cfg.treatment_column)
+        if dcol is None:
+            raise ValueError(f"crosstalk_pairs: design column '{cfg.design_column}' (or its alias) is missing")
+        if tcol is None:
+            raise ValueError(f"crosstalk_pairs: treatment column '{cfg.treatment_column}' (or its alias) is missing")
+
+        map_col = _pick_alias(df, cfg.design_treatment_column) if cfg.design_treatment_column else None
+
+        result = compute_crosstalk_pairs(
+            df,
+            design_col=dcol,
+            treatment_col=tcol,
+            value_col=cfg.value_column,
+            value_scale=cfg.value_scale,
+            target=cfg.target,
+            time_mode=cfg.time_mode,
+            time_policy=cfg.time_policy,
+            time=cfg.time,
+            times=cfg.times,
+            time_column=cfg.time_column,
+            time_tolerance=cfg.time_tolerance,
+            mapping_mode=cfg.mapping_mode,
+            design_treatment_column=map_col,
+            design_treatment_map=cfg.design_treatment_map,
+            design_treatment_overrides=cfg.design_treatment_overrides,
+            top1_tie_policy=cfg.top1_tie_policy,
+            top1_tie_tolerance=cfg.top1_tie_tolerance,
+            require_self_treatment=cfg.require_self_treatment,
+            require_self_is_top1=cfg.require_self_is_top1,
+            agg=cfg.agg,
+            min_self=cfg.min_self,
+            max_cross=cfg.max_cross,
+            max_other=cfg.max_other,
+            min_self_minus_best_other=cfg.min_self_minus_best_other,
+            min_self_ratio_best_other=cfg.min_self_ratio_best_other,
+            min_selectivity_delta=cfg.min_selectivity_delta,
+            min_selectivity_ratio=cfg.min_selectivity_ratio,
+            only_passing=cfg.only_passing,
+            logger=ctx.logger,
+        )
+
+        pairs = result.pairs
+        designs = result.designs
+
+        try:
+            total_designs = int(designs["design_id"].nunique()) if "design_id" in designs.columns else 0
+            time_count = len(result.times_used)
+            total_pairs = total_designs * (total_designs - 1) // 2 * max(1, time_count)
+            passing = int(pairs.shape[0])
+            ctx.logger.info(
+                "crosstalk_pairs - designs=%d - times=%d - pairs=%d - passing=%d - metric=%s",
+                total_designs,
+                time_count,
+                total_pairs,
+                passing,
+                cfg.value_column,
+            )
+        except Exception:
+            pass
+
+        try:
+            if not pairs.empty:
+                preview = pairs.copy()
+                preview["pair_score"] = pd.to_numeric(preview["pair_score"], errors="coerce")
+                preview = preview[preview["pair_score"].notna()].sort_values("pair_score", ascending=False)
+                if not preview.empty:
+                    n_show = max(1, int(cfg.top_n))
+                    ctx.logger.info("crosstalk_pairs - top %d pairs by pair_score:", n_show)
+                    for _, row in preview.head(n_show).iterrows():
+                        ctx.logger.info(
+                            "   - t=%s | %s <-> %s | self=%s/%s | cross=%s/%s | score=%.3g",
+                            _fmt(row.get("time")),
+                            row.get("design_a"),
+                            row.get("design_b"),
+                            _fmt(row.get("a_self_value")),
+                            _fmt(row.get("b_self_value")),
+                            _fmt(row.get("a_cross_to_b")),
+                            _fmt(row.get("b_cross_to_a")),
+                            float(row.get("pair_score")) if pd.notna(row.get("pair_score")) else float("nan"),
+                        )
+        except Exception:
+            pass
+
+        return {"table": pairs}
+
+
+def _fmt(val: object) -> str:
+    try:
+        f = float(val)
+        if pd.isna(f):
+            return "nan"
+        return f"{f:.3g}"
+    except Exception:
+        return str(val)

reader_workbench/plugins/transform/cytometry_gating.py

@@ -0,0 +1,120 @@
+"""Explicit cytometry gating transform."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field, model_validator
+
+from reader_workbench.domains.cytometry.analysis import GateSpec, ThresholdSpec
+from reader_workbench.domains.cytometry.analysis.workflow import (
+    CytometryGatingRequest,
+    CytometryQCSpec,
+    run_cytometry_gating,
+)
+from reader_workbench.workbench.ports import dataframe_input, dataframe_output
+from reader_workbench.workbench.registry import Plugin, PluginConfig
+
+
+class CytometryGatingCfg(PluginConfig):
+    cells_x_channel: str = Field(min_length=1)
+    cells_y_channel: str = Field(min_length=1)
+    cells_x_range: tuple[float, float]
+    cells_y_range: tuple[float, float]
+    singlet_x_channel: str = Field(min_length=1)
+    singlet_y_channel: str = Field(min_length=1)
+    singlet_ratio_range: tuple[float, float]
+    cells_enabled: bool
+    singlets_enabled: bool
+    fluorescence_channel: str = Field(min_length=1)
+    threshold_mode: Literal["manual", "from_control_quantile"]
+    threshold_value: float | None
+    threshold_group_column: str | None
+    threshold_control_value: str | None
+    threshold_quantile: float | None
+    group_column: str | None
+    minimum_final_events: int = Field(ge=0)
+    minimum_final_percent: float = Field(ge=0.0, le=100.0)
+    maximum_nonpositive_percent: float = Field(ge=0.0, le=100.0)
+    nonpositive_scope: Literal["all_events", "gated_events"]
+
+    @model_validator(mode="after")
+    def _validate_threshold_policy(self):
+        if self.threshold_mode == "manual":
+            if self.threshold_value is None:
+                raise ValueError("threshold_value is required for manual thresholding")
+            if any(
+                value is not None
+                for value in (self.threshold_group_column, self.threshold_control_value, self.threshold_quantile)
+            ):
+                raise ValueError("manual thresholding may not declare control threshold fields")
+            return self
+        if self.threshold_value is not None:
+            raise ValueError("threshold_value must be null for control-quantile thresholding")
+        if not self.threshold_group_column:
+            raise ValueError("threshold_group_column is required for control-quantile thresholding")
+        if not self.threshold_control_value:
+            raise ValueError("threshold_control_value is required for control-quantile thresholding")
+        if self.threshold_quantile is None or not 0.0 <= self.threshold_quantile <= 1.0:
+            raise ValueError("threshold_quantile must be between 0 and 1 for control-quantile thresholding")
+        return self
+
+
+class CytometryGatingTransform(Plugin):
+    ConfigModel = CytometryGatingCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"events": dataframe_input("events", "tidy.v1")}
+
+    @classmethod
+    def output_ports(cls):
+        return {
+            "gate_definition": dataframe_output("gate_definition", "cytometry.gate_definition.v1"),
+            "gated_events": dataframe_output("gated_events", "cytometry.gated_events.v1"),
+            "sample_stats": dataframe_output("sample_stats", "cytometry.sample_stats.v1"),
+            "group_stats": dataframe_output("group_stats", "cytometry.group_stats.v1"),
+            "qc": dataframe_output("qc", "cytometry.qc.v1"),
+        }
+
+    def run(self, ctx, inputs, cfg: CytometryGatingCfg):
+        del ctx
+        threshold = ThresholdSpec(
+            channel=cfg.fluorescence_channel,
+            value=float(cfg.threshold_value or 0.0),
+            mode=cfg.threshold_mode,
+            group_column=cfg.threshold_group_column,
+            control_value=cfg.threshold_control_value,
+            quantile=float(cfg.threshold_quantile or 0.0),
+        )
+        result = run_cytometry_gating(
+            inputs["events"],
+            CytometryGatingRequest(
+                gate=GateSpec(
+                    cells_x_channel=cfg.cells_x_channel,
+                    cells_y_channel=cfg.cells_y_channel,
+                    cells_x_range=cfg.cells_x_range,
+                    cells_y_range=cfg.cells_y_range,
+                    singlet_x_channel=cfg.singlet_x_channel,
+                    singlet_y_channel=cfg.singlet_y_channel,
+                    singlet_ratio_range=cfg.singlet_ratio_range,
+                    cells_enabled=cfg.cells_enabled,
+                    singlets_enabled=cfg.singlets_enabled,
+                ),
+                threshold=threshold,
+                group_column=cfg.group_column,
+                qc=CytometryQCSpec(
+                    minimum_final_events=cfg.minimum_final_events,
+                    minimum_final_percent=cfg.minimum_final_percent,
+                    maximum_nonpositive_percent=cfg.maximum_nonpositive_percent,
+                    nonpositive_scope=cfg.nonpositive_scope,
+                ),
+            ),
+        )
+        return {
+            "gate_definition": result.gate_definition.to_pandas(),
+            "gated_events": result.gated_events.to_pandas(),
+            "sample_stats": result.sample_stats.to_pandas(),
+            "group_stats": result.group_stats.to_pandas(),
+            "qc": result.qc.to_pandas(),
+        }

reader_workbench/plugins/transform/fold_change.py

@@ -0,0 +1,79 @@
+"""Fold-change report:
+• Selects the nearest snapshot time(s) per group
+• Computes FC against explicit baselines (global or per-group overrides)
+• Emits a validated artifact (fold_change.v1) — no mutation of the main tidy df
+• Prints a concise, rich stdout summary (via logger) for quick inspection"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import Field
+
+from reader_workbench.domains.plate_reader.analysis import FoldChangeAnalysisSpec, compute_fold_change_table
+from reader_workbench.workbench.ports import dataframe_input, dataframe_output
+from reader_workbench.workbench.registry import Plugin, PluginConfig
+
+# ----------------------------- config model -----------------------------
+
+
+class FoldChangeCfg(PluginConfig):
+    # What to compute
+    target: str  # e.g., "YFP/CFP" or "YFP/OD600"
+    report_times: list[float]  # e.g., [8.0, 14.0]
+    time_tolerance: float = 0.51  # nearest-time selection tolerance (h)
+    observation_stat: Literal["median", "mean"] = "median"
+
+    # Grouping and labels
+    treatment_column: str = "treatment"  # we will prefer '<col>_alias' when present
+    group_by: list[str] = Field(default_factory=lambda: ["design_id"])
+    expected_treatments: list[str] = Field(default_factory=list)
+
+    # Baseline policy
+    use_global_baseline: bool = False
+    global_baseline_value: str | None = None  # used when use_global_baseline==True
+    # overrides: list of maps; any keys matching group_by columns define a match; each must
+    # include 'baseline_value'. Example:
+    #   - { design_id: "araBADp", baseline_value: "0 uM arabinose" }
+    overrides: list[dict[str, Any]] = Field(default_factory=list)
+
+    # Output columns (names)
+    fc_column: str = "FC"
+    log2fc_column: str = "log2FC"
+
+    # Attach extra metadata columns if present (won't be required by contract, just carried through)
+    attach_metadata: list[str] = Field(default_factory=lambda: ["batch"])
+
+
+class FoldChange(Plugin):
+    """Contract-driven transform that emits a fold_change.v1 table."""
+
+    ConfigModel = FoldChangeCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"df": dataframe_input("df", "tidy.v1")}
+
+    @classmethod
+    def output_ports(cls):
+        return {"table": dataframe_output("table", "fold_change.v1")}
+
+    # ------------------------------- run --------------------------------
+
+    def run(self, ctx, inputs, cfg: FoldChangeCfg):
+        spec = FoldChangeAnalysisSpec(
+            target=cfg.target,
+            report_times=tuple(cfg.report_times),
+            time_tolerance=cfg.time_tolerance,
+            observation_stat=cfg.observation_stat,
+            treatment_column=cfg.treatment_column,
+            group_by=tuple(cfg.group_by),
+            expected_treatments=tuple(cfg.expected_treatments),
+            use_global_baseline=cfg.use_global_baseline,
+            global_baseline_value=cfg.global_baseline_value,
+            overrides=tuple(dict(rule) for rule in cfg.overrides),
+            fc_column=cfg.fc_column,
+            log2fc_column=cfg.log2fc_column,
+            attach_metadata=tuple(cfg.attach_metadata),
+        )
+        return {"table": compute_fold_change_table(inputs["df"], spec=spec, logger=ctx.logger)}

reader_workbench/plugins/transform/four_state_event_window.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from reader_workbench.domains.plate_reader.analysis.four_state_event_window.contracts import (
+    FourStateEventWindowAnalysisSpec,
+)
+from reader_workbench.domains.plate_reader.analysis.four_state_event_window.materialize import materialize_experiment
+from reader_workbench.domains.plate_reader.analysis.four_state_event_window.sources import build_experiment_source
+from reader_workbench.workbench.ports import dataframe_output, record_collection_input
+from reader_workbench.workbench.records import SourceRecordCollection
+from reader_workbench.workbench.registry import Plugin, PluginConfig
+
+
+class FourStateEventWindowCfg(PluginConfig):
+    source: dict[str, Any]
+    event: dict[str, Any]
+    reductions: list[dict[str, Any]]
+    aggregation: dict[str, Any]
+    quality: dict[str, Any]
+
+
+class FourStateEventWindowTransform(Plugin):
+    """Materialize event-relative summaries from aligned source record collections."""
+
+    ConfigModel = FourStateEventWindowCfg
+
+    @classmethod
+    def input_ports(cls):
+        source = "plate_reader.annotated.v1"
+        return {
+            "response_records": record_collection_input("response_records", source),
+            "magnitude_records": record_collection_input("magnitude_records", source),
+            "trajectory_records": record_collection_input("trajectory_records", source),
+        }
+
+    @classmethod
+    def output_ports(cls):
+        return {
+            "wells": dataframe_output("wells", "plate_reader.four_state_event_window.wells.v3"),
+            "designs": dataframe_output("designs", "plate_reader.four_state_event_window.designs.v4"),
+            "descriptive_resampling_draws": dataframe_output(
+                "descriptive_resampling_draws",
+                "plate_reader.four_state_event_window.descriptive_resampling_draws.v3",
+            ),
+            "traces": dataframe_output("traces", "plate_reader.four_state_event_window.traces.v3"),
+            "events": dataframe_output("events", "plate_reader.four_state_event_window.events.v2"),
+            "dispositions": dataframe_output(
+                "dispositions",
+                "plate_reader.four_state_event_window.dispositions.v1",
+            ),
+        }
+
+    def run(self, ctx, inputs, cfg):
+        spec = FourStateEventWindowAnalysisSpec.from_mapping(cfg.model_dump())
+        response: SourceRecordCollection = inputs["response_records"]
+        magnitude: SourceRecordCollection = inputs["magnitude_records"]
+        trajectory: SourceRecordCollection = inputs["trajectory_records"]
+        experiment_ids = tuple(item.ref.experiment_id for item in response)
+        if len(set(experiment_ids)) != len(experiment_ids):
+            raise ValueError("four-state event-window source experiments must be unique")
+        spec.source.require_known_experiment_ids(experiment_ids)
+        for label, collection in (("magnitude", magnitude), ("trajectory", trajectory)):
+            observed = tuple(item.ref.experiment_id for item in collection)
+            if observed != experiment_ids:
+                raise ValueError(
+                    f"four-state event-window {label} source order must match response source experiments: "
+                    f"expected {experiment_ids}, got {observed}"
+                )
+
+        materialized = []
+        for response_item, magnitude_item, trajectory_item in zip(
+            response,
+            magnitude,
+            trajectory,
+            strict=True,
+        ):
+            source = build_experiment_source(
+                experiment_id=response_item.ref.experiment_id,
+                response_frame=response_item.load_dataframe(),
+                magnitude_frame=magnitude_item.load_dataframe(),
+                trajectory_frame=trajectory_item.load_dataframe(),
+                source_spec=spec.source,
+                event_spec=spec.event,
+            )
+            materialized.append(materialize_experiment(source, request=spec))
+        names = ("wells", "designs", "descriptive_resampling_draws", "traces", "events", "dispositions")
+        return {
+            name: pd.concat([frames[index] for frames in materialized], ignore_index=True)
+            for index, name in enumerate(names)
+        }