reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/plugins/plot/_shared.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import Literal
+
+from pydantic import BaseModel
+
+from reader_workbench.errors import ExecutionError
+from reader_workbench.plotting.sinks import PlotFigure, normalize_plot_figures, save_plot_figures
+from reader_workbench.workbench.ports import file_bundle_output
+from reader_workbench.workbench.records import PathDescription
+from reader_workbench.workbench.registry import Plugin
+
+
+class PlotPartitionCfg(BaseModel):
+    by: str | None = None
+    collection_ref: str | None = None
+    match: Literal["exact", "contains", "startswith", "endswith", "regex"] = "exact"
+
+    model_config = {"extra": "forbid"}
+
+
+class FigurePlotPlugin(Plugin):
+    @classmethod
+    def output_ports(cls):
+        return {"artifacts": file_bundle_output("artifacts")}
+
+    @abstractmethod
+    def render(self, ctx, inputs, cfg) -> list[PlotFigure]:
+        raise NotImplementedError
+
+    def run(self, ctx, inputs, cfg):
+        return save_rendered_figures(ctx=ctx, figures=self.render(ctx, inputs, cfg), plot_key=self.plugin_key)
+
+
+def resolve_plot_partition_cfg(*, ctx, partition: PlotPartitionCfg):
+    if ctx.experiment is None:
+        raise ValueError("plot partition resolution requires experiment semantics in the run context")
+    return ctx.experiment.annotations.resolve_plot_partition(partition=partition)
+
+
+def save_rendered_figures(*, ctx, figures: list[PlotFigure], plot_key: str) -> dict[str, list[str | PathDescription]]:
+    normalized = normalize_plot_figures(figures, where=f"plot/{plot_key}")
+    if not normalized:
+        raise ExecutionError(
+            f"plot/{plot_key}: renderer produced no figures; check data filters, time windows, channels, and partitions"
+        )
+    saved = save_plot_figures(normalized, ctx.plots_dir)
+    artifacts: list[str | PathDescription] = []
+    for figure, path in zip(normalized, saved, strict=True):
+        if figure.description is None:
+            artifacts.append(str(path))
+        else:
+            artifacts.append(PathDescription(path=path, description=figure.description))
+    return {"artifacts": artifacts}

reader_workbench/plugins/plot/cytometry_diagnostic.py

@@ -0,0 +1,54 @@
+"""Static cytometry gating diagnostic plot plugin."""
+
+from __future__ import annotations
+
+from typing import 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 CytometryDiagnosticCfg(PluginConfig):
+    title: str | None = Field(default=None, min_length=1)
+    max_events: int = Field(default=50_000, gt=0)
+    filename: str = Field(default="cytometry_diagnostic", min_length=1)
+    format: list[Literal["png", "pdf", "svg"]] = Field(default_factory=lambda: ["png"], min_length=1)
+    dpi: int = Field(default=300, gt=0)
+
+
+class CytometryDiagnosticPlot(FigurePlotPlugin):
+    ConfigModel = CytometryDiagnosticCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {
+            "original_events": dataframe_input("original_events", "tidy.v1"),
+            "gate_definition": dataframe_input("gate_definition", "cytometry.gate_definition.v1"),
+            "gated_events": dataframe_input("gated_events", "cytometry.gated_events.v1"),
+        }
+
+    def render(self, ctx, inputs, cfg: CytometryDiagnosticCfg):
+        del ctx
+        from reader_workbench.domains.cytometry.plots import render_cytometry_diagnostic  # noqa: PLC0415
+
+        figure = render_cytometry_diagnostic(
+            inputs["original_events"],
+            inputs["gate_definition"],
+            inputs["gated_events"],
+            max_events=cfg.max_events,
+            title=cfg.title,
+        )
+        return [
+            PlotFigure(
+                fig=figure,
+                filename=cfg.filename,
+                ext=extension,
+                dpi=cfg.dpi,
+                description="Configured cells, singlets, fluorescence, and final-retention diagnostics.",
+            )
+            for extension in cfg.format
+        ]

reader_workbench/plugins/plot/distributions.py

@@ -0,0 +1,58 @@
+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 DistributionsCfg(PluginConfig):
+    # what to draw
+    channels: list[str]
+    # modern grouping
+    partition: PlotPartitionCfg = Field(default_factory=lambda: PlotPartitionCfg(by="design_id"))
+    # layout
+    panel_by: Literal["channel", "group"] = "channel"  # default: per-channel panels
+    hue: str | None = None
+    legend_loc: Literal["upper left", "upper right", "lower left", "lower right", "center", "best"] = "upper left"
+    # style/output
+    fig: dict[str, Any] = Field(default_factory=dict)
+    filename: str | None = None
+
+
+class DistributionsPlot(FigurePlotPlugin):
+    ConfigModel = DistributionsCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {
+            "df": dataframe_input("df", "tidy.v1"),
+            "blanks": dataframe_input("blanks", "tidy.v1", optional=True),
+        }
+
+    def render(self, ctx, inputs, cfg: DistributionsCfg) -> list[PlotFigure]:
+        df: pd.DataFrame = inputs["df"]
+        blanks: pd.DataFrame = inputs.get("blanks", df.iloc[0:0])
+        from reader_workbench.domains.plate_reader.plots.distributions import plot_distributions  # noqa: PLC0415
+
+        partition = resolve_plot_partition_cfg(ctx=ctx, partition=cfg.partition)
+
+        return plot_distributions(
+            df=df,
+            blanks=blanks,
+            channels=cfg.channels,
+            group_on=partition.group_by,
+            pool_sets=partition.collection_items,
+            pool_match=partition.match,  # type: ignore[arg-type]
+            panel_by=cfg.panel_by,
+            hue=cfg.hue,
+            legend_loc=cfg.legend_loc,
+            fig_kwargs=cfg.fig,
+            filename=cfg.filename,
+            palette_book=ctx.palette_book,
+        )

reader_workbench/plugins/plot/dual_reporter_triptych.py

@@ -0,0 +1,224 @@
+"""Persisted dual-reporter kinetics and endpoint triptych."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import pandas as pd
+from pydantic import Field, model_validator
+
+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
+
+_DESCRIPTION = (
+    "Growth and reporter-ratio kinetics with descriptive within-experiment resampling bands, "
+    "plus observed endpoint values and mean with sample standard deviation."
+)
+
+
+class DualReporterTriptychCfg(PluginConfig):
+    design_column: str = Field(default="design_id", min_length=1)
+    treatment_column: str = Field(default="treatment", min_length=1)
+    time_column: str = Field(default="time", min_length=1)
+    growth_channel: str = Field(default="OD600", min_length=1)
+    ratio_channel: str = Field(default="YFP/CFP", min_length=1)
+    snapshot_channel: str | None = Field(default=None, min_length=1)
+    snapshot_time_h: float
+    snapshot_time_mode: Literal["nearest", "last_before", "first_after", "exact"] = "nearest"
+    snapshot_time_tolerance_h: float | None = Field(default=0.51, ge=0.0)
+    treatment_order: list[str] | None = None
+    treatment_order_ref: str | None = Field(default=None, min_length=1)
+    trajectory_interval_mass: float = Field(default=0.95, gt=0.0, lt=1.0)
+    trajectory_resamples: int = Field(default=300, ge=1)
+    filename_prefix: str = Field(default="dual_reporter_triptych", 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] = (10.5, 3.5)
+
+    @model_validator(mode="after")
+    def validate_semantic_options(self) -> DualReporterTriptychCfg:
+        filename_prefix = self.filename_prefix.strip()
+        if not filename_prefix:
+            raise ValueError("dual_reporter_triptych: filename_prefix must be a non-empty string")
+        self.filename_prefix = filename_prefix
+        if self.treatment_order is not None and self.treatment_order_ref is not None:
+            raise ValueError("dual_reporter_triptych: treatment_order and treatment_order_ref are mutually exclusive")
+        if self.treatment_order is not None:
+            normalized = [str(value).strip() for value in self.treatment_order]
+            if not normalized or any(not value for value in normalized):
+                raise ValueError("dual_reporter_triptych: treatment_order must contain non-empty strings")
+            if len(set(normalized)) != len(normalized):
+                raise ValueError("dual_reporter_triptych: treatment_order contains duplicate labels")
+            self.treatment_order = normalized
+        if any(not value > 0.0 for value in self.figsize):
+            raise ValueError("dual_reporter_triptych: figsize values must be positive")
+        if len(set(self.format)) != len(self.format):
+            raise ValueError("dual_reporter_triptych: format must not contain duplicates")
+        return self
+
+
+class DualReporterTriptychPlot(FigurePlotPlugin):
+    ConfigModel = DualReporterTriptychCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"df": dataframe_input("df", "tidy.v1")}
+
+    @classmethod
+    def validate_semantic_references(cls, *, experiment, cfg: DualReporterTriptychCfg) -> None:
+        if cfg.treatment_order_ref is not None:
+            experiment.annotations.resolve_order_arg(
+                order=None,
+                order_ref=cfg.treatment_order_ref,
+                column=cfg.treatment_column,
+                arg_name="treatment_order",
+            )
+
+    def render(self, ctx, inputs, cfg: DualReporterTriptychCfg) -> list[PlotFigure]:
+        from reader_workbench.domains.plate_reader.analysis.timepoints import (  # noqa: PLC0415
+            infer_acquisition_transition_time_h,
+        )
+        from reader_workbench.domains.plate_reader.ordering import order_levels  # noqa: PLC0415
+        from reader_workbench.domains.plate_reader.plots.dual_reporter_triptych import (  # noqa: PLC0415
+            build_triptych_data,
+            choose_time,
+        )
+        from reader_workbench.domains.plate_reader.plots.dual_reporter_triptych_render import (  # noqa: PLC0415
+            render_dual_reporter_triptych,
+        )
+
+        frame: pd.DataFrame = inputs["df"]
+        _require_columns(
+            frame,
+            (
+                cfg.design_column,
+                cfg.treatment_column,
+                cfg.time_column,
+                "channel",
+                "value",
+                "position",
+            ),
+        )
+        design_values = order_levels(_nonempty_strings(frame[cfg.design_column]))
+        if not design_values:
+            raise ValueError(f"dual_reporter_triptych: no non-empty values in {cfg.design_column!r}")
+        design_series = frame[cfg.design_column].astype("string").str.strip()
+        filename_by_design = _artifact_names_by_design(
+            design_values,
+            filename_prefix=cfg.filename_prefix,
+        )
+        treatment_order = _resolve_treatment_order(ctx=ctx, cfg=cfg)
+
+        figures: list[PlotFigure] = []
+        for design_value in design_values:
+            selected = frame[design_series == design_value].copy()
+            time_values = pd.to_numeric(selected[cfg.time_column], errors="coerce").dropna().unique().tolist()
+            selected_time = choose_time(time_values, cfg.snapshot_time_h, cfg.snapshot_time_mode)
+            if selected_time is None:
+                raise ValueError(
+                    "dual_reporter_triptych: "
+                    f"design {design_value!r} has no time matching {cfg.snapshot_time_h:g} h "
+                    f"with mode {cfg.snapshot_time_mode!r}"
+                )
+            delta = abs(float(selected_time) - float(cfg.snapshot_time_h))
+            if cfg.snapshot_time_tolerance_h is not None and delta > cfg.snapshot_time_tolerance_h:
+                raise ValueError(
+                    "dual_reporter_triptych: "
+                    f"design {design_value!r} selected {selected_time:g} h for target "
+                    f"{cfg.snapshot_time_h:g} h, outside snapshot_time_tolerance_h="
+                    f"{cfg.snapshot_time_tolerance_h:g}"
+                )
+
+            data = build_triptych_data(
+                selected,
+                time_col=cfg.time_column,
+                treatment_col=cfg.treatment_column,
+                growth_channel=cfg.growth_channel,
+                ratio_channel=cfg.ratio_channel,
+                snapshot_channel=cfg.snapshot_channel,
+                snapshot_time=float(selected_time),
+                treatment_order=treatment_order,
+                trajectory_interval_mass=cfg.trajectory_interval_mass,
+                trajectory_resamples=cfg.trajectory_resamples,
+            )
+            palette_book = getattr(ctx, "palette_book", None)
+            colors = palette_book.colors(len(data.treatment_order)) if palette_book is not None else None
+            figure = render_dual_reporter_triptych(
+                data,
+                time_col=cfg.time_column,
+                treatment_col=cfg.treatment_column,
+                acquisition_transition_time_h=infer_acquisition_transition_time_h(
+                    selected,
+                    time_col=cfg.time_column,
+                ),
+                title=design_value,
+                colors=colors,
+                figsize=cfg.figsize,
+            )
+            filename = filename_by_design[design_value]
+            figures.extend(
+                PlotFigure(
+                    fig=figure,
+                    filename=filename,
+                    ext=extension,
+                    dpi=cfg.dpi,
+                    description=_DESCRIPTION,
+                )
+                for extension in cfg.format
+            )
+        return figures
+
+
+def _resolve_treatment_order(*, ctx, cfg: DualReporterTriptychCfg) -> list[str] | None:
+    if cfg.treatment_order_ref is None:
+        return cfg.treatment_order
+    experiment = getattr(ctx, "experiment", None)
+    if experiment is None:
+        raise ValueError("dual_reporter_triptych: treatment_order_ref requires experiment semantics")
+    return experiment.annotations.resolve_order_arg(
+        order=None,
+        order_ref=cfg.treatment_order_ref,
+        column=cfg.treatment_column,
+        arg_name="treatment_order",
+    )
+
+
+def _nonempty_strings(series: pd.Series) -> list[str]:
+    values: list[str] = []
+    seen: set[str] = set()
+    for value in series.dropna().tolist():
+        text = str(value).strip()
+        if not text or text.casefold() in {"nan", "none"} or text in seen:
+            continue
+        values.append(text)
+        seen.add(text)
+    return values
+
+
+def _artifact_names_by_design(design_values: list[str], *, filename_prefix: str) -> dict[str, str]:
+    by_design: dict[str, str] = {}
+    owner_by_name: dict[str, str] = {}
+    for design_value in design_values:
+        name = f"{filename_prefix}__{design_value}"
+        normalized_name = slugify(name)
+        prior = owner_by_name.get(normalized_name)
+        if prior is not None:
+            raise ValueError(
+                "dual_reporter_triptych: "
+                f"designs {prior!r} and {design_value!r} resolve to the same artifact name {normalized_name!r}"
+            )
+        by_design[design_value] = name
+        owner_by_name[normalized_name] = design_value
+    return by_design
+
+
+def _require_columns(frame: pd.DataFrame, columns: tuple[str, ...]) -> None:
+    missing = [column for column in dict.fromkeys(columns) if column not in frame.columns]
+    if missing:
+        raise ValueError("dual_reporter_triptych: missing column(s): " + ", ".join(missing))
+
+
+__all__ = ["DualReporterTriptychCfg", "DualReporterTriptychPlot"]

reader_workbench/plugins/plot/four_state_event_window_diagnostic.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+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 FourStateEventWindowDiagnosticSubject(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    source_experiment_id: str = Field(min_length=1)
+    design_id: str = Field(min_length=1)
+    filename: str = Field(min_length=1)
+    title: str | None = Field(default=None, min_length=1)
+
+    @model_validator(mode="after")
+    def _reject_blank_values(self) -> FourStateEventWindowDiagnosticSubject:
+        required = {
+            "source_experiment_id": self.source_experiment_id,
+            "design_id": self.design_id,
+            "filename": self.filename,
+        }
+        blank = [name for name, value in required.items() if not value.strip()]
+        if self.title is not None and not self.title.strip():
+            blank.append("title")
+        if blank:
+            raise ValueError(f"subject values must not be blank: {', '.join(blank)}")
+        normalized_filename = slugify(self.filename)
+        if not normalized_filename or not any(character.isalnum() for character in normalized_filename):
+            raise ValueError("subject filename must contain a filesystem-safe character")
+        if _is_windows_reserved_filename(normalized_filename):
+            raise ValueError("subject filename must not use a Windows reserved device name")
+        return self
+
+
+class FourStateEventWindowAxisLabels(BaseModel):
+    """Protocol-derived labels for the three source trace panels."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    growth: str = Field(min_length=1)
+    response: str = Field(min_length=1)
+    magnitude: str = Field(min_length=1)
+
+
+class FourStateEventWindowDiagnosticCfg(PluginConfig):
+    subjects: list[FourStateEventWindowDiagnosticSubject] = Field(min_length=1)
+    primary_reduction_id: str = Field(min_length=1)
+    pre_window_duration_h: float | None = Field(default=None, gt=0.0)
+    axis_labels: FourStateEventWindowAxisLabels = Field(
+        default_factory=lambda: FourStateEventWindowAxisLabels(
+            growth="Signal",
+            response="log$_2$(response signal)",
+            magnitude="log$_2$(magnitude signal)",
+        )
+    )
+    state_labels: dict[str, str] = Field(default_factory=lambda: {"00": "00", "10": "10", "01": "01", "11": "11"})
+    reference_label: str = Field(default="reference", min_length=1)
+    format: list[Literal["png", "pdf", "svg"]] = Field(default_factory=lambda: ["png"], min_length=1)
+    dpi: int = Field(default=300, ge=1)
+
+    @model_validator(mode="after")
+    def _validate_subject_selection(self) -> FourStateEventWindowDiagnosticCfg:
+        identities = [(subject.source_experiment_id.strip(), subject.design_id.strip()) for subject in self.subjects]
+        if len(identities) != len(set(identities)):
+            raise ValueError("subjects must contain unique source/design identities")
+        filenames = [slugify(subject.filename).casefold() for subject in self.subjects]
+        if len(filenames) != len(set(filenames)):
+            raise ValueError("subjects must contain unique filenames")
+        if set(self.state_labels) != {"00", "10", "01", "11"}:
+            raise ValueError("state_labels must define exactly 00, 10, 01, and 11")
+        if any(not isinstance(value, str) or not value.strip() for value in self.state_labels.values()):
+            raise ValueError("state_labels values must be non-empty strings")
+        return self
+
+
+class FourStateEventWindowDiagnosticPlot(FigurePlotPlugin):
+    ConfigModel = FourStateEventWindowDiagnosticCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {
+            "traces": dataframe_input("traces", "plate_reader.four_state_event_window.traces.v3"),
+            "designs": dataframe_input("designs", "plate_reader.four_state_event_window.designs.v4"),
+        }
+
+    def render(self, ctx, inputs, cfg: FourStateEventWindowDiagnosticCfg):
+        from reader_workbench.domains.plate_reader.plots.four_state_event_window.diagnostic_render import (  # noqa: PLC0415
+            render_four_state_event_window_diagnostic,
+        )
+
+        rendered: list[PlotFigure] = []
+        for subject in cfg.subjects:
+            figure = render_four_state_event_window_diagnostic(
+                inputs["traces"],
+                inputs["designs"],
+                source_experiment_id=subject.source_experiment_id,
+                design_id=subject.design_id,
+                reduction_id=cfg.primary_reduction_id,
+                pre_window_duration_h=cfg.pre_window_duration_h,
+                axis_labels=cfg.axis_labels.model_dump(),
+                state_labels=cfg.state_labels,
+                reference_label=cfg.reference_label,
+                title=subject.title,
+            )
+            rendered.extend(
+                PlotFigure(
+                    fig=figure,
+                    filename=subject.filename,
+                    ext=extension,
+                    dpi=cfg.dpi,
+                    description=(
+                        "Event-relative growth, response, magnitude, and reduced components "
+                        "for one source experiment and design."
+                    ),
+                )
+                for extension in cfg.format
+            )
+        return rendered
+
+
+def _is_windows_reserved_filename(filename: str) -> bool:
+    """Return whether a portable filename would address a Windows device."""
+
+    device_name = filename.split(".", maxsplit=1)[0]
+    return re.fullmatch(r"(?i:con|prn|aux|nul|com[1-9]|lpt[1-9])", device_name) is not None

reader_workbench/plugins/plot/four_state_event_window_summary.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import 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 FourStateEventWindowSummaryCfg(PluginConfig):
+    primary_reduction_id: str = Field(min_length=1)
+    experiment_ids: list[str] | None = Field(default=None, min_length=1)
+    design_ids: list[str] | None = Field(default=None, min_length=1)
+    maximum_rows: int = Field(default=64, ge=1)
+    title: str = Field(default="Four-state event-window summary", min_length=1)
+    filename: str = Field(default="four_state_event_window_summary", min_length=1)
+    format: list[Literal["png", "pdf", "svg"]] = Field(default_factory=lambda: ["png"], min_length=1)
+    dpi: int = Field(default=300, ge=1)
+
+
+class FourStateEventWindowSummaryPlot(FigurePlotPlugin):
+    ConfigModel = FourStateEventWindowSummaryCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"designs": dataframe_input("designs", "plate_reader.four_state_event_window.designs.v4")}
+
+    def render(self, ctx, inputs, cfg):
+        from reader_workbench.domains.plate_reader.plots.four_state_event_window.summary import (  # noqa: PLC0415
+            render_four_state_event_window_summary,
+        )
+
+        figure = render_four_state_event_window_summary(
+            inputs["designs"],
+            primary_reduction_id=cfg.primary_reduction_id,
+            experiment_ids=cfg.experiment_ids,
+            design_ids=cfg.design_ids,
+            maximum_rows=cfg.maximum_rows,
+            title=cfg.title,
+        )
+        return [
+            PlotFigure(
+                fig=figure,
+                filename=cfg.filename,
+                ext=extension,
+                dpi=cfg.dpi,
+                description="Primary event-relative response and anchored-magnitude components by source and design.",
+            )
+            for extension in cfg.format
+        ]

reader_workbench/plugins/plot/four_state_vector_collection.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+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 FourStateVectorCollectionHeatmapCfg(PluginConfig):
+    title: str = "Four-state vector collection"
+    max_y_tick_labels: int = 80
+    filename: str = "four_state_vector_collection"
+    format: list[str] = Field(default_factory=lambda: ["png"])
+    dpi: int = 300
+
+
+class FourStateVectorCollectionHeatmapPlot(FigurePlotPlugin):
+    ConfigModel = FourStateVectorCollectionHeatmapCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"vectors": dataframe_input("vectors", "logic.four_state_vector_collection.v1")}
+
+    def render(self, ctx, inputs, cfg):
+        from reader_workbench.domains.logic.four_state_vector.collection import (  # noqa: PLC0415
+            render_four_state_vector_collection_heatmap,
+        )
+
+        figure = render_four_state_vector_collection_heatmap(
+            inputs["vectors"],
+            title=cfg.title,
+            max_y_tick_labels=cfg.max_y_tick_labels,
+        )
+        return [
+            PlotFigure(
+                fig=figure,
+                filename=cfg.filename,
+                ext=extension,
+                dpi=cfg.dpi,
+                description="Cross-experiment four-state vector heatmap.",
+            )
+            for extension in cfg.format
+        ]