reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/plugins/plot/four_state_vector_diagnostic.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from reader_workbench.errors import ExecutionError
+from reader_workbench.plotting.sinks import PlotFigure
+from reader_workbench.plotting.utils import slugify
+from reader_workbench.plugins.plot._shared import FigurePlotPlugin
+from reader_workbench.workbench.ports import dataframe_input
+from reader_workbench.workbench.registry import PluginConfig
+
+
+class FourStateVectorDiagnosticCfg(PluginConfig):
+    state_map_ref: str = Field(min_length=1)
+    time_column: str = Field(default="time", min_length=1)
+    growth_channel: str = Field(default="OD600", min_length=1)
+    response_channel: str = Field(default="YFP/CFP", min_length=1)
+    design_ids: list[str] | None = None
+    trajectory_interval_mass: float = Field(default=0.95, gt=0.0, lt=1.0)
+    trajectory_resamples: int = Field(default=300, ge=1)
+    time_atol: float = Field(default=1e-9, ge=0.0)
+    title: str | None = Field(default=None, min_length=1)
+    filename: str = Field(default="four_state_vector_diagnostic", min_length=1)
+    format: list[Literal["png", "pdf", "svg"]] = Field(default_factory=lambda: ["png"], min_length=1)
+    dpi: int = Field(default=300, ge=1)
+    figsize: tuple[float, float] = (15.0, 5.5)
+
+
+class FourStateVectorDiagnosticPlot(FigurePlotPlugin):
+    """Render a record-driven diagnostic without recomputing vector."""
+
+    ConfigModel = FourStateVectorDiagnosticCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {
+            "df": dataframe_input("df", "plate_reader.annotated.v1"),
+            "vector": dataframe_input("vector", "logic.four_state_vector.v1"),
+        }
+
+    def render(self, ctx, inputs, cfg: FourStateVectorDiagnosticCfg) -> list[PlotFigure]:
+        if ctx is None or getattr(ctx, "experiment", None) is None:
+            raise ExecutionError("plot/four_state_vector_diagnostic requires experiment annotation semantics")
+        state_space = ctx.experiment.annotations.resolve_ordered_state_space(ref=cfg.state_map_ref)
+        if tuple(state_space.state_ids) != ("00", "10", "01", "11"):
+            raise ExecutionError("plot/four_state_vector_diagnostic requires ordered states 00, 10, 01, 11")
+
+        from reader_workbench.domains.logic.four_state_vector.diagnostic import (  # noqa: PLC0415
+            prepare_four_state_vector_diagnostics,
+            render_four_state_vector_diagnostic,
+        )
+
+        prepared = prepare_four_state_vector_diagnostics(
+            inputs["df"],
+            inputs["vector"],
+            treatment_column=state_space.column,
+            treatment_map=state_space.source_values,
+            treatment_case_sensitive=state_space.case_sensitive,
+            time_column=cfg.time_column,
+            growth_channel=cfg.growth_channel,
+            response_channel=cfg.response_channel,
+            design_ids=cfg.design_ids,
+            time_atol=cfg.time_atol,
+            trajectory_interval_mass=cfg.trajectory_interval_mass,
+            trajectory_resamples=cfg.trajectory_resamples,
+        )
+        filenames = [_design_filename(cfg.filename, item.design_id) for item in prepared]
+        if len(set(filenames)) != len(filenames):
+            raise ExecutionError("plot/four_state_vector_diagnostic design ids resolve to duplicate artifact filenames")
+
+        figures: list[PlotFigure] = []
+        for item, filename in zip(prepared, filenames, strict=True):
+            figure = render_four_state_vector_diagnostic(
+                item,
+                title=cfg.title,
+                figsize=cfg.figsize,
+                dpi=cfg.dpi,
+            )
+            description = (
+                f"Growth and response trajectories with persisted vector components for design {item.design_id} "
+                f"at {item.selected_time_h:g} hours."
+            )
+            figures.extend(
+                PlotFigure(
+                    fig=figure,
+                    filename=filename,
+                    ext=extension,
+                    dpi=cfg.dpi,
+                    description=description,
+                )
+                for extension in cfg.format
+            )
+        return figures
+
+
+def _design_filename(base: str, design_id: str) -> str:
+    base_slug = slugify(base)
+    if not base_slug:
+        raise ExecutionError(f"plot/four_state_vector_diagnostic cannot derive a filename from base {base!r}")
+    design_slug = slugify(design_id)
+    if not design_slug:
+        raise ExecutionError(f"plot/four_state_vector_diagnostic cannot derive a filename from design id {design_id!r}")
+    return f"{base_slug}--{design_slug}"

reader_workbench/plugins/plot/four_state_vector_heatmap.py

@@ -0,0 +1,63 @@
+"""
+four-state vector heatmap plot plugin.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+from pydantic import Field
+
+from reader_workbench.errors import FourStateVectorError
+from reader_workbench.plotting.sinks import PlotFigure
+from reader_workbench.plugins.plot._shared import FigurePlotPlugin
+from reader_workbench.workbench.ports import dataframe_input
+from reader_workbench.workbench.registry import PluginConfig
+
+
+class FourStateVectorHeatmapCfg(PluginConfig):
+    experiment_id: str | None = None
+    title: str | None = None
+    max_y_tick_labels: int = 80
+    filename: str | None = None
+    format: list[str] = Field(default_factory=lambda: ["pdf"])
+    dpi: int = 300
+
+
+class FourStateVectorHeatmapPlot(FigurePlotPlugin):
+    ConfigModel = FourStateVectorHeatmapCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"vector": dataframe_input("vector", "logic.four_state_vector.v1")}
+
+    def render(self, ctx, inputs, cfg: FourStateVectorHeatmapCfg) -> list[PlotFigure]:
+        vector: pd.DataFrame = inputs["vector"]
+        from reader_workbench.domains.logic.four_state_vector.heatmap import (  # noqa: PLC0415
+            render_experiment_four_state_vector_heatmap,
+        )
+
+        experiment_id = cfg.experiment_id or _experiment_id_from_context(ctx)
+        title = cfg.title or f"{experiment_id} four-state vector heatmap"
+        fig = render_experiment_four_state_vector_heatmap(
+            vector,
+            experiment_id=experiment_id,
+            title=title,
+            max_y_tick_labels=cfg.max_y_tick_labels,
+        )
+        filename = cfg.filename or "four_state_vector_heatmap"
+        return [PlotFigure(fig=fig, filename=filename, ext=ext, dpi=cfg.dpi) for ext in cfg.format]
+
+
+def _experiment_id_from_context(ctx) -> str:
+    exp_dir = getattr(ctx, "exp_dir", None)
+    if isinstance(exp_dir, Path):
+        return exp_dir.name
+    if exp_dir is not None:
+        name = Path(str(exp_dir)).name
+        if name:
+            return name
+    raise FourStateVectorError(
+        "plot/four_state_vector_heatmap requires experiment_id when no experiment directory is available."
+    )

reader_workbench/plugins/plot/logic_symmetry.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import Field
+
+from reader_workbench.plotting.sinks import PlotFigure
+from reader_workbench.plugins.plot._shared import FigurePlotPlugin
+from reader_workbench.workbench.ports import dataframe_input
+from reader_workbench.workbench.registry import PluginConfig
+
+
+class LogicSymmetryPlotCfg(PluginConfig):
+    title: str = "Logic symmetry"
+    dispersion: Literal["none", "bars", "halo"] = "halo"
+    encodings: dict[str, Any] = Field(default_factory=dict)
+    ideals_overlay: dict[str, Any] = Field(default_factory=dict)
+    visuals: dict[str, Any] = Field(default_factory=dict)
+    filename: str = "logic_symmetry"
+    format: list[Literal["png", "pdf", "svg"]] = Field(default_factory=lambda: ["pdf"], min_length=1)
+    dpi: int = Field(300, gt=0)
+    figsize: tuple[float, float] = (7, 6)
+
+
+class LogicSymmetryPlot(FigurePlotPlugin):
+    """Render a persisted logic-symmetry table without owning its computation."""
+
+    ConfigModel = LogicSymmetryPlotCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"table": dataframe_input("table", "logic_symmetry.v1")}
+
+    def render(self, ctx, inputs, cfg: LogicSymmetryPlotCfg) -> list[PlotFigure]:
+        from reader_workbench.domains.logic.logic_symmetry import render_logic_symmetry  # noqa: PLC0415
+
+        figure = render_logic_symmetry(
+            inputs["table"],
+            title=cfg.title,
+            dispersion=cfg.dispersion,
+            encodings=cfg.encodings,
+            ideals_overlay=cfg.ideals_overlay,
+            visuals=cfg.visuals,
+            figsize=cfg.figsize,
+            dpi=cfg.dpi,
+        )
+        return [
+            PlotFigure(
+                fig=figure,
+                filename=cfg.filename,
+                ext=extension,
+                dpi=cfg.dpi,
+                description="Logic and asymmetry geometry over the configured four-state summary.",
+            )
+            for extension in cfg.format
+        ]

reader_workbench/plugins/plot/single_reporter_diagnostic.py

@@ -0,0 +1,279 @@
+"""Four-panel diagnostic over a persisted single-reporter ratio record."""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Literal
+
+import pandas as pd
+from pydantic import BaseModel, Field, model_validator
+
+from reader_workbench.domains.time_series import ObservationAggregationSpec, TemporalReductionSpec
+from reader_workbench.plotting.sinks import PlotFigure
+from reader_workbench.plotting.utils import slugify
+from reader_workbench.plugins.plot._shared import FigurePlotPlugin, PlotPartitionCfg, resolve_plot_partition_cfg
+from reader_workbench.workbench.ports import dataframe_input
+from reader_workbench.workbench.registry import PluginConfig
+
+_UNIT_DESCRIPTIONS = {
+    "declared_replicate": "temporally reduced declared-replicate values by condition",
+    "observation_only": "temporally reduced observation-only values by condition",
+}
+
+
+class SingleReporterDiagnosticFigureCfg(BaseModel):
+    figsize: tuple[float, float] = (14.0, 3.7)
+    axis_label_size: float = Field(default=9.5, gt=0.0)
+    tick_label_size: float = Field(default=8.5, gt=0.0)
+    legend_fontsize: float = Field(default=8.5, gt=0.0)
+    line_width: float = Field(default=1.7, gt=0.0)
+    point_size: float = Field(default=28.0, gt=0.0)
+    condition_tick_rotation: float = Field(default=20.0, ge=-90.0, le=90.0)
+
+    model_config = {"extra": "forbid"}
+
+    @model_validator(mode="after")
+    def validate_figure(self) -> SingleReporterDiagnosticFigureCfg:
+        if len(self.figsize) != 2 or any(
+            not math.isfinite(float(value)) or float(value) <= 0.0 for value in self.figsize
+        ):
+            raise ValueError("single_reporter_diagnostic: fig.figsize must contain two positive finite values")
+        return self
+
+
+class SingleReporterObservationUnitCfg(BaseModel):
+    """Identify descriptive source observations without declaring replication."""
+
+    role: Literal["observation_only"]
+    column: str = Field(min_length=1)
+
+    model_config = {"extra": "forbid"}
+
+    @model_validator(mode="after")
+    def validate_observation_unit(self) -> SingleReporterObservationUnitCfg:
+        column = self.column.strip()
+        if not column:
+            raise ValueError("single_reporter_diagnostic: observation_unit.column must be a non-empty string")
+        self.column = column
+        return self
+
+
+class SingleReporterIdentityScopeCfg(BaseModel):
+    """Bind unit identities to stable assay entities, independent of presentation."""
+
+    entity_columns: list[str] = Field(min_length=1)
+
+    model_config = {"extra": "forbid"}
+
+    @model_validator(mode="after")
+    def validate_identity_scope(self) -> SingleReporterIdentityScopeCfg:
+        columns = [str(column).strip() for column in self.entity_columns]
+        if not columns or any(not column for column in columns):
+            raise ValueError("single_reporter_diagnostic: identity_scope.entity_columns must be non-empty strings")
+        if len(set(columns)) != len(columns):
+            raise ValueError("single_reporter_diagnostic: identity_scope.entity_columns must not contain duplicates")
+        self.entity_columns = columns
+        return self
+
+
+class SingleReporterDiagnosticCfg(PluginConfig):
+    partition: PlotPartitionCfg = Field(default_factory=PlotPartitionCfg)
+    identity_scope: SingleReporterIdentityScopeCfg
+    condition_column: str = Field(default="treatment", min_length=1)
+    condition_order: list[str] | None = None
+    condition_order_ref: str | None = Field(default=None, min_length=1)
+    temporal_reduction: dict[str, Any]
+    observation_aggregation: dict[str, Any]
+    observation_unit: SingleReporterObservationUnitCfg | None = None
+    time_column: str = Field(default="time", min_length=1)
+    normalizer_channel: str = Field(min_length=1)
+    reporter_channel: str = Field(min_length=1)
+    ratio_channel: str = Field(min_length=1)
+    filename_prefix: str = Field(default="single_reporter_diagnostic", min_length=1)
+    format: list[Literal["png", "pdf", "svg"]] = Field(default_factory=lambda: ["png"], min_length=1)
+    dpi: int = Field(default=300, ge=1)
+    fig: SingleReporterDiagnosticFigureCfg = Field(default_factory=SingleReporterDiagnosticFigureCfg)
+
+    @model_validator(mode="after")
+    def validate_semantic_options(self) -> SingleReporterDiagnosticCfg:
+        for field_name in (
+            "condition_column",
+            "time_column",
+            "normalizer_channel",
+            "reporter_channel",
+            "ratio_channel",
+            "filename_prefix",
+        ):
+            value = str(getattr(self, field_name)).strip()
+            if not value:
+                raise ValueError(f"single_reporter_diagnostic: {field_name} must be a non-empty string")
+            setattr(self, field_name, value)
+        if len({self.normalizer_channel, self.reporter_channel, self.ratio_channel}) != 3:
+            raise ValueError("single_reporter_diagnostic: normalizer, reporter, and ratio channels must be distinct")
+        if self.condition_column in self.identity_scope.entity_columns:
+            raise ValueError(
+                "single_reporter_diagnostic: condition_column is already part of unit identity and must not be "
+                "repeated in identity_scope.entity_columns"
+            )
+        temporal = TemporalReductionSpec.from_mapping(self.temporal_reduction)
+        aggregation = ObservationAggregationSpec.from_mapping(self.observation_aggregation)
+        self.temporal_reduction = temporal.to_mapping()
+        self.observation_aggregation = aggregation.to_mapping()
+        if self.condition_order is not None and self.condition_order_ref is not None:
+            raise ValueError(
+                "single_reporter_diagnostic: condition_order and condition_order_ref are mutually exclusive"
+            )
+        if self.condition_order is not None:
+            values = [str(value).strip() for value in self.condition_order]
+            if not values or any(not value for value in values):
+                raise ValueError("single_reporter_diagnostic: condition_order must contain non-empty labels")
+            if len(set(values)) != len(values):
+                raise ValueError("single_reporter_diagnostic: condition_order contains duplicate labels")
+            self.condition_order = values
+        if len(set(self.format)) != len(self.format):
+            raise ValueError("single_reporter_diagnostic: format must not contain duplicates")
+        return self
+
+
+class SingleReporterDiagnosticPlot(FigurePlotPlugin):
+    ConfigModel = SingleReporterDiagnosticCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"df": dataframe_input("df", "plate_reader.annotated.v1")}
+
+    @classmethod
+    def _resolve_condition_order(cls, *, experiment, cfg: SingleReporterDiagnosticCfg):
+        return experiment.annotations.resolve_order_arg(
+            order=cfg.condition_order,
+            order_ref=cfg.condition_order_ref,
+            column=cfg.condition_column,
+            arg_name="condition_order",
+        )
+
+    @classmethod
+    def validate_semantic_references(cls, *, experiment, cfg: SingleReporterDiagnosticCfg) -> None:
+        experiment.annotations.resolve_plot_partition(partition=cfg.partition)
+        cls._resolve_condition_order(experiment=experiment, cfg=cfg)
+
+    def render(self, ctx, inputs, cfg: SingleReporterDiagnosticCfg) -> list[PlotFigure]:
+        from reader_workbench.domains.plate_reader.plots.single_reporter_diagnostic import (  # noqa: PLC0415
+            prepare_single_reporter_diagnostics,
+        )
+        from reader_workbench.domains.plate_reader.plots.single_reporter_diagnostic_render import (  # noqa: PLC0415
+            render_single_reporter_diagnostic,
+        )
+
+        if ctx.experiment is None:
+            raise ValueError("single_reporter_diagnostic requires experiment semantics in the run context")
+        frame: pd.DataFrame = inputs["df"]
+        partition = resolve_plot_partition_cfg(ctx=ctx, partition=cfg.partition)
+        condition_order = type(self)._resolve_condition_order(experiment=ctx.experiment, cfg=cfg)
+        unit_column, observation_column, unit_role = _reduction_columns(
+            ctx=ctx,
+            frame=frame,
+            observation_unit=cfg.observation_unit,
+        )
+        diagnostics = prepare_single_reporter_diagnostics(
+            frame,
+            group_on=partition.group_by,
+            collection_items=partition.collection_items,
+            group_match=partition.match,
+            condition_column=cfg.condition_column,
+            condition_order=condition_order,
+            entity_columns=cfg.identity_scope.entity_columns,
+            unit_column=unit_column,
+            observation_column=observation_column,
+            unit_role=unit_role,
+            time_column=cfg.time_column,
+            normalizer_channel=cfg.normalizer_channel,
+            reporter_channel=cfg.reporter_channel,
+            ratio_channel=cfg.ratio_channel,
+            temporal_reduction=TemporalReductionSpec.from_mapping(cfg.temporal_reduction),
+            observation_aggregation=ObservationAggregationSpec.from_mapping(cfg.observation_aggregation),
+        )
+        artifact_names = _artifact_names(diagnostics, filename_prefix=cfg.filename_prefix)
+        figures: list[PlotFigure] = []
+        palette_book = getattr(ctx, "palette_book", None)
+        for diagnostic in diagnostics:
+            colors = palette_book.colors(len(diagnostic.condition_order)) if palette_book is not None else None
+            figure = render_single_reporter_diagnostic(
+                diagnostic,
+                colors=colors,
+                **cfg.fig.model_dump(),
+            )
+            figures.extend(
+                PlotFigure(
+                    fig=figure,
+                    filename=artifact_names[diagnostic.group_label],
+                    ext=extension,
+                    dpi=cfg.dpi,
+                    description=(
+                        "Normalizer, reporter, and reporter-normalizer kinetics with an explicit endpoint or "
+                        f"interval reduction, {_UNIT_DESCRIPTIONS[diagnostic.unit_role]}, and visible normalizer QC."
+                    ),
+                )
+                for extension in cfg.format
+            )
+        return figures
+
+
+def _reduction_columns(
+    *,
+    ctx,
+    frame: pd.DataFrame,
+    observation_unit: SingleReporterObservationUnitCfg | None,
+) -> tuple[str, str, Literal["declared_replicate", "observation_only"]]:
+    evidence = getattr(ctx.experiment, "evidence", None)
+    declared = getattr(evidence, "replicate_identity_field", None)
+    if declared is not None:
+        unit_column = str(declared).strip()
+        if unit_column not in frame.columns:
+            raise ValueError(
+                "single_reporter_diagnostic: declared evidence.replicate_identity_field "
+                f"{unit_column!r} is absent from the persisted ratio record"
+            )
+        observation_column = observation_unit.column if observation_unit is not None else unit_column
+        _require_observation_column(frame=frame, column=observation_column)
+        return unit_column, observation_column, "declared_replicate"
+    if observation_unit is None:
+        raise ValueError(
+            "single_reporter_diagnostic: no replicate identity is declared; configure "
+            "observation_unit with role='observation_only' to plot descriptive record observations"
+        )
+    _require_observation_column(frame=frame, column=observation_unit.column)
+    return observation_unit.column, observation_unit.column, "observation_only"
+
+
+def _require_observation_column(*, frame: pd.DataFrame, column: str) -> None:
+    if column not in frame.columns:
+        raise ValueError(
+            f"single_reporter_diagnostic: observation_unit column {column!r} is absent from the persisted ratio record"
+        )
+
+
+def _artifact_names(diagnostics, *, filename_prefix: str) -> dict[str, str]:
+    names: dict[str, str] = {}
+    owner_by_slug: dict[str, str] = {}
+    for diagnostic in diagnostics:
+        label = str(diagnostic.group_label)
+        filename = filename_prefix if label == "all" else f"{filename_prefix}__{label}"
+        normalized = slugify(filename)
+        prior = owner_by_slug.get(normalized)
+        if prior is not None:
+            raise ValueError(
+                "single_reporter_diagnostic: "
+                f"partitions {prior!r} and {label!r} resolve to the same artifact name {normalized!r}"
+            )
+        names[label] = filename
+        owner_by_slug[normalized] = label
+    return names
+
+
+__all__ = [
+    "SingleReporterDiagnosticCfg",
+    "SingleReporterDiagnosticFigureCfg",
+    "SingleReporterIdentityScopeCfg",
+    "SingleReporterObservationUnitCfg",
+    "SingleReporterDiagnosticPlot",
+]

reader_workbench/plugins/plot/snapshot_barplot.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+import pandas as pd
+from pydantic import Field
+
+from reader_workbench.plotting.sinks import PlotFigure
+from reader_workbench.plugins.plot._shared import FigurePlotPlugin, PlotPartitionCfg, resolve_plot_partition_cfg
+from reader_workbench.workbench.ports import dataframe_input
+from reader_workbench.workbench.registry import PluginConfig
+
+
+class SnapshotBarCfg(PluginConfig):
+    x: str
+    y: list[str] | str
+    hue: str | None = None
+    partition: PlotPartitionCfg = Field(default_factory=PlotPartitionCfg)
+    time: float = Field(..., description="Snapshot time (hours); required for deterministic plotting.")
+    fig: dict[str, Any] = Field(default_factory=dict)
+    filename: str | None = None
+    agg: str = "mean"  # median|mean
+    dispersion: Literal["sd", "iqr", "none"] = "sd"
+    time_tolerance: float = 0.51
+    panel_by: Literal["channel", "x", "group"] = "channel"
+    channel_select: str | None = None
+    file_by: Literal["auto", "channel"] = "auto"
+    show_legend: bool = False
+    legend_loc: str = "upper right"
+
+
+class SnapshotBarplot(FigurePlotPlugin):
+    ConfigModel = SnapshotBarCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"df": dataframe_input("df", "tidy.v1")}
+
+    def render(self, ctx, inputs, cfg: SnapshotBarCfg) -> list[PlotFigure]:
+        df: pd.DataFrame = inputs["df"]
+        from reader_workbench.domains.plate_reader.plots.snapshot_barplot import plot_snapshot_barplot  # noqa: PLC0415
+
+        partition = resolve_plot_partition_cfg(ctx=ctx, partition=cfg.partition)
+
+        return plot_snapshot_barplot(
+            df=df,
+            x=cfg.x,
+            y=cfg.y,
+            hue=cfg.hue,
+            group_on=partition.group_by,
+            pool_sets=partition.collection_items,
+            time=cfg.time,
+            pool_match=partition.match,  # type: ignore
+            fig_kwargs=cfg.fig,
+            filename=cfg.filename,
+            palette_book=ctx.palette_book,
+            agg=cfg.agg,
+            dispersion=cfg.dispersion,
+            time_tolerance=cfg.time_tolerance,
+            panel_by=cfg.panel_by,
+            channel_select=cfg.channel_select,
+            file_by=cfg.file_by,
+            show_legend=cfg.show_legend,
+            legend_loc=cfg.legend_loc,
+        )

reader_workbench/plugins/plot/snapshot_heatmap.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+import pandas as pd
+from pydantic import Field, model_validator
+
+from reader_workbench.plotting.sinks import PlotFigure
+from reader_workbench.plugins.plot._shared import FigurePlotPlugin
+from reader_workbench.workbench.ports import dataframe_input
+from reader_workbench.workbench.registry import PluginConfig
+
+
+def _load_snapshot_heatmap_impl():
+    module = import_module("reader_workbench.domains.plate_reader.plots.snapshot_heatmap")
+    return module.plot_snapshot_heatmap, module.prepare_snapshot_heatmap_inputs
+
+
+class HeatmapCfg(PluginConfig):
+    channel: str
+    time: float
+    x: str = "treatment"
+    y: str = "design_id"
+    order_x: list[str] | None = None
+    order_y: list[str] | None = None
+    order_x_ref: str | None = None
+    order_y_ref: str | None = None
+    square: bool = True
+    vmin: float | None = None
+    vmax: float | None = None
+    value_transform: str | None = "none"  # "none" | "log2" | "log10"
+    time_tolerance: float = 0.51
+    fig: dict[str, Any] = Field(default_factory=dict)
+    filename: str | None = None
+
+    @model_validator(mode="after")
+    def validate_order_sources(self) -> HeatmapCfg:
+        if self.order_x is not None and self.order_x_ref is not None:
+            raise ValueError("snapshot_heatmap: order_x and order_x_ref are mutually exclusive")
+        if self.order_y is not None and self.order_y_ref is not None:
+            raise ValueError("snapshot_heatmap: order_y and order_y_ref are mutually exclusive")
+        return self
+
+
+class SnapshotHeatmapPlot(FigurePlotPlugin):
+    ConfigModel = HeatmapCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {
+            "df": dataframe_input("df", "tidy.v1", optional=True),
+            "fc": dataframe_input("fc", "fold_change.v1", optional=True),
+        }
+
+    def render(self, ctx, inputs, cfg: HeatmapCfg) -> list[PlotFigure]:
+        if ctx.experiment is None:
+            raise ValueError("snapshot_heatmap requires experiment semantics in the run context")
+        df_in: pd.DataFrame | None = inputs.get("df")
+        fc_in: pd.DataFrame | None = inputs.get("fc")
+        plot_snapshot_heatmap, prepare_snapshot_heatmap_inputs = _load_snapshot_heatmap_impl()
+
+        prepared = prepare_snapshot_heatmap_inputs(
+            df_in=df_in,
+            fc_in=fc_in,
+            channel=cfg.channel,
+            time=cfg.time,
+            time_tolerance=cfg.time_tolerance,
+            value_transform=cfg.value_transform,
+            fig=cfg.fig,
+            filename=cfg.filename,
+            logger=ctx.logger,
+        )
+        channel = str(cfg.channel)
+        df = prepared.frame
+        filename = prepared.filename
+        fig_kwargs = prepared.fig_kwargs
+        resolved_order_x = ctx.experiment.annotations.resolve_order_arg(
+            order=cfg.order_x,
+            order_ref=cfg.order_x_ref,
+            column=cfg.x,
+            arg_name="order_x",
+        )
+        resolved_order_y = ctx.experiment.annotations.resolve_order_arg(
+            order=cfg.order_y,
+            order_ref=cfg.order_y_ref,
+            column=cfg.y,
+            arg_name="order_y",
+        )
+        return plot_snapshot_heatmap(
+            df=df,
+            channel=channel,
+            time=cfg.time,
+            x=cfg.x,
+            y=cfg.y,
+            order_x=resolved_order_x,
+            order_y=resolved_order_y,
+            square=cfg.square,
+            vmin=cfg.vmin,
+            vmax=cfg.vmax,
+            fig_kwargs=fig_kwargs,
+            filename=filename,
+            logger=ctx.logger,
+        )