dataeval-plots 0.0.15__tar.gz → 0.0.17__tar.gz

{dataeval_plots-0.0.15 → dataeval_plots-0.0.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dataeval-plots
-Version: 0.0.15
+Version: 0.0.17
 Summary: DataEval companion package for plotting utilities
 Project-URL: Homepage, https://dataeval.ai/
 Project-URL: Repository, https://github.com/aria-ml/dataeval/

{dataeval_plots-0.0.15 → dataeval_plots-0.0.17}/src/dataeval_plots/__init__.py

@@ -19,6 +19,7 @@ from dataeval_plots.protocols import (
     Dataset,
     PlottableBalance,
     PlottableDiversity,
+    PlottableDrift,
     PlottableDriftMVDC,
     PlottableFeasibility,
     PlottableStats,
@@ -98,6 +99,15 @@ def plot(
 ) -> Any: ...
 
 
+@overload
+def plot(
+    output: PlottableDrift,
+    /,
+    figsize: tuple[float, float] | None = None,
+    backend: str | None = None,
+) -> Any: ...
+
+
 @overload
 def plot(
     output: PlottableFeasibility,

{dataeval_plots-0.0.15 → dataeval_plots-0.0.17}/src/dataeval_plots/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.0.15'
-__version_tuple__ = version_tuple = (0, 0, 15)
+__version__ = version = '0.0.17'
+__version_tuple__ = version_tuple = (0, 0, 17)
 
 __commit_id__ = commit_id = None

{dataeval_plots-0.0.15 → dataeval_plots-0.0.17}/src/dataeval_plots/backends/_altair.py

@@ -29,6 +29,7 @@ from dataeval_plots.backends._shared import (
     normalize_reference_outputs,
     parse_dataset_item,
     prepare_balance_data,
+    prepare_chunked_drift,
     prepare_diversity_data,
     prepare_drift_data,
     prepare_feasibility_data,
@@ -39,6 +40,7 @@ from dataeval_plots.protocols import (
     Dataset,
     PlottableBalance,
     PlottableDiversity,
+    PlottableDrift,
     PlottableDriftMVDC,
     PlottableFeasibility,
     PlottableStats,
@@ -819,6 +821,82 @@ class AltairBackend(BasePlottingBackend):
             width=width, height=height, title="Domain Classifier, Drift Detection"
         )
 
+    def _plot_drift(
+        self,
+        output: PlottableDrift,
+        figsize: tuple[float, float] | None = None,
+    ) -> Any:  # alt.LayerChart
+        """
+        Render the metric of each chunk in relation to the thresholds of the detector.
+
+        When the output carries the metric of the reference chunks, they are drawn in gray to the left of the
+        analysis chunks. The chunks are numbered from -n for the reference and from 0 for the analysis.
+
+        Parameters
+        ----------
+        output : PlottableDrift
+            The chunked drift output object to plot
+        figsize : tuple[float, float] or None, default None
+            Figure size in inches (width, height), drawn at 100 pixels per inch. If None, defaults to (6, 3).
+
+        Returns
+        -------
+        alt.LayerChart
+        """
+        import altair as alt
+        import pandas as pd
+
+        data = prepare_chunked_drift(output)
+        width_inches, height_inches = figsize or (6, 3)
+
+        # Convert via dict to avoid pyarrow dependency
+        plot_df = pd.DataFrame(
+            data.frame.with_columns(
+                pl.when(pl.col("period") == "reference")
+                .then(pl.lit("Reference chunks"))
+                .otherwise(pl.lit("Analysis chunks"))
+                .alias("period")
+            ).to_dict(as_series=False)
+        )
+
+        x = alt.X("index:Q", title=data.chunk_label, axis=alt.Axis(tickMinStep=1))
+        scale = alt.Scale(zero=False)
+        y = alt.Y("value:Q", title=data.metric_name, scale=scale)
+        tooltip = ["index:Q", alt.Tooltip("value:Q", title=data.metric_name, format=".4f")]
+
+        # The no-drift range is the band between the two thresholds
+        layers = [
+            alt.Chart(plot_df)
+            .mark_area(color="green", opacity=0.15, interpolate="step")
+            .encode(x=x, y=alt.Y("lower_threshold:Q", title=data.metric_name, scale=scale), y2="upper_threshold:Q")
+        ]
+
+        # The metric of each chunk, with the reference chunks in gray
+        has_reference = bool((plot_df["period"] == "Reference chunks").any())
+        color = alt.Color(
+            "period:N",
+            scale=alt.Scale(domain=["Reference chunks", "Analysis chunks"], range=["gray", "royalblue"]),
+            legend=alt.Legend(title=None),
+        )
+        layers.append(alt.Chart(plot_df).mark_line(point=True).encode(x=x, y=y, color=color, tooltip=tooltip))
+        if has_reference:
+            layers.append(
+                alt.Chart(pd.DataFrame({"index": [-0.5]}))
+                .mark_rule(color="gray", strokeDash=[2, 2])
+                .encode(x="index:Q")
+            )
+
+        # The chunks that the detector flagged
+        layers.append(
+            alt.Chart(plot_df[plot_df["drifted"]])  # type: ignore[arg-type]
+            .mark_point(shape="diamond", size=120, color="crimson", filled=True)
+            .encode(x=x, y=y, tooltip=tooltip)
+        )
+
+        return alt.layer(*layers).properties(
+            width=int(width_inches * 100), height=int(height_inches * 100), title="Drift by chunk"
+        )
+
     def _plot_image_grid(
         self,
         dataset: Dataset,

{dataeval_plots-0.0.15 → dataeval_plots-0.0.17}/src/dataeval_plots/backends/_base.py

@@ -14,6 +14,7 @@ from dataeval_plots.protocols import (
     Dataset,
     PlottableBalance,
     PlottableDiversity,
+    PlottableDrift,
     PlottableDriftMVDC,
     PlottableFeasibility,
     PlottableStats,
@@ -81,6 +82,14 @@ class PlottingBackend(Protocol):
         figsize: tuple[float, float] | None = None,
     ) -> Any: ...
 
+    @overload
+    def plot(
+        self,
+        output: PlottableDrift,
+        *,
+        figsize: tuple[float, float] | None = None,
+    ) -> Any: ...
+
     @overload
     def plot(
         self,
@@ -245,6 +254,8 @@ class BasePlottingBackend(PlottingBackend, ABC):
             return self._plot_sufficiency(cast(PlottableSufficiency, output), figsize=figsize, **kwargs)
         if plot_type == "drift_mvdc":
             return self._plot_drift_mvdc(cast(PlottableDriftMVDC, output), figsize=figsize, **kwargs)
+        if plot_type == "drift":
+            return self._plot_drift(cast(PlottableDrift, output), figsize=figsize, **kwargs)
         if plot_type == "stats":
             return self._plot_stats(cast(PlottableStats, output), figsize=figsize, **kwargs)
         if plot_type == "feasibility":
@@ -310,6 +321,15 @@ class BasePlottingBackend(PlottingBackend, ABC):
         """Plot drift MVDC output."""
         ...
 
+    @abstractmethod
+    def _plot_drift(
+        self,
+        output: PlottableDrift,
+        figsize: tuple[float, float] | None = None,
+    ) -> Any:
+        """Plot the per-chunk results of a chunked drift detector."""
+        ...
+
     @abstractmethod
     def _plot_feasibility(
         self,

{dataeval_plots-0.0.15 → dataeval_plots-0.0.17}/src/dataeval_plots/backends/_matplotlib.py

@@ -21,8 +21,10 @@ from dataeval_plots.backends._shared import (
     calculate_subplot_grid,
     feasibility_zones,
     normalize_reference_outputs,
+    plot_chunked_drift_on_axis,
     plot_drift_on_axis,
     prepare_balance_data,
+    prepare_chunked_drift,
     prepare_diversity_data,
     prepare_drift_data,
     prepare_feasibility_data,
@@ -32,6 +34,7 @@ from dataeval_plots.backends._shared import (
 from dataeval_plots.protocols import (
     PlottableBalance,
     PlottableDiversity,
+    PlottableDrift,
     PlottableDriftMVDC,
     PlottableFeasibility,
     PlottableStats,
@@ -833,6 +836,35 @@ class MatplotlibBackend(BasePlottingBackend):
             )
         return fig
 
+    def _plot_drift(
+        self,
+        output: PlottableDrift,
+        figsize: tuple[float, float] | None = None,
+    ) -> Figure:
+        """
+        Render the metric of each chunk in relation to the thresholds of the detector.
+
+        Parameters
+        ----------
+        output : PlottableDrift
+            The chunked drift output object to plot
+        figsize : tuple[float, float] or None, default None
+            Figure size in inches (width, height). If None, defaults to (8, 3.5).
+
+        Returns
+        -------
+        matplotlib.figure.Figure
+        """
+        import matplotlib.pyplot as plt
+
+        data = prepare_chunked_drift(output)
+
+        fig, ax = plt.subplots(figsize=figsize or (8, 3.5))
+        plot_chunked_drift_on_axis(ax, data)
+        ax.set_title("Drift by chunk")
+        fig.tight_layout()
+        return fig
+
     def _plot_feasibility(
         self,
         output: PlottableFeasibility,

{dataeval_plots-0.0.15 → dataeval_plots-0.0.17}/src/dataeval_plots/backends/_plotly.py

@@ -22,6 +22,7 @@ from dataeval_plots.backends._shared import (
     feasibility_zones,
     format_label_from_target,
     prepare_balance_data,
+    prepare_chunked_drift,
     prepare_diversity_data,
     prepare_drift_data,
     prepare_feasibility_data,
@@ -33,6 +34,7 @@ from dataeval_plots.protocols import (
     Dataset,
     PlottableBalance,
     PlottableDiversity,
+    PlottableDrift,
     PlottableDriftMVDC,
     PlottableFeasibility,
     PlottableStats,
@@ -849,6 +851,113 @@ class PlotlyBackend(BasePlottingBackend):
 
         return fig
 
+    def _plot_drift(
+        self,
+        output: PlottableDrift,
+        figsize: tuple[float, float] | None = None,
+    ) -> Any:  # go.Figure
+        """
+        Render the metric of each chunk in relation to the thresholds of the detector.
+
+        When the output carries the metric of the reference chunks, they are drawn in gray to the left of the
+        analysis chunks. The chunks are numbered from -n for the reference and from 0 for the analysis.
+
+        Parameters
+        ----------
+        output : PlottableDrift
+            The chunked drift output object to plot
+        figsize : tuple[float, float] or None, default None
+            Figure size in inches (width, height), drawn at 100 pixels per inch. If None, defaults to (8, 3.5).
+
+        Returns
+        -------
+        plotly.graph_objects.Figure
+        """
+        import plotly.graph_objects as go
+
+        data = prepare_chunked_drift(output)
+        frame, reference, analysis = data.frame, data.reference, data.analysis
+        drifted = analysis.filter(pl.col("drifted"))
+        hover = f"Chunk: %{{x}}<br>{data.metric_name}: %{{y:.4f}}<extra></extra>"
+
+        fig = go.Figure()
+
+        # The no-drift range is the band between the two thresholds
+        fig.add_trace(
+            go.Scatter(
+                x=frame["index"].to_numpy(),
+                y=frame["upper_threshold"].to_numpy(),
+                mode="lines",
+                line={"width": 0, "shape": "hvh"},
+                showlegend=False,
+                hoverinfo="skip",
+            )
+        )
+        fig.add_trace(
+            go.Scatter(
+                x=frame["index"].to_numpy(),
+                y=frame["lower_threshold"].to_numpy(),
+                mode="lines",
+                line={"width": 0, "shape": "hvh"},
+                fill="tonexty",
+                fillcolor="rgba(44, 160, 44, 0.15)",
+                name="No-drift range",
+                hoverinfo="skip",
+            )
+        )
+
+        # The reference chunks, which the thresholds derive from
+        if len(reference):
+            fig.add_trace(
+                go.Scatter(
+                    x=reference["index"].to_numpy(),
+                    y=reference["value"].to_numpy(),
+                    mode="lines+markers",
+                    name="Reference chunks",
+                    line={"color": "gray", "width": 2},
+                    hovertemplate=hover,
+                )
+            )
+            fig.add_vline(x=-0.5, line_dash="dot", line_color="gray", line_width=1)
+
+        # The metric of each analysis chunk
+        fig.add_trace(
+            go.Scatter(
+                x=analysis["index"].to_numpy(),
+                y=analysis["value"].to_numpy(),
+                mode="lines+markers",
+                name="Analysis chunks",
+                line={"color": "royalblue", "width": 2},
+                hovertemplate=hover,
+            )
+        )
+
+        # The chunks that the detector flagged
+        if len(drifted):
+            fig.add_trace(
+                go.Scatter(
+                    x=drifted["index"].to_numpy(),
+                    y=drifted["value"].to_numpy(),
+                    mode="markers",
+                    name="Drift",
+                    marker={"symbol": "diamond", "size": 11, "color": "crimson"},
+                    hovertemplate=hover,
+                )
+            )
+
+        width_inches, height_inches = figsize or (8, 3.5)
+        fig.update_layout(
+            title="Drift by chunk",
+            xaxis_title=data.chunk_label,
+            yaxis_title=data.metric_name,
+            xaxis={"dtick": 1} if len(frame) <= 20 else {},
+            width=int(width_inches * 100),
+            height=int(height_inches * 100),
+            hovermode="closest",
+        )
+
+        return fig
+
     def _plot_image_grid(
         self,
         dataset: Dataset,

{dataeval_plots-0.0.15 → dataeval_plots-0.0.17}/src/dataeval_plots/backends/_seaborn.py

@@ -10,14 +10,17 @@ from numpy.typing import NDArray
 from dataeval_plots.backends._base import BasePlottingBackend
 from dataeval_plots.backends._shared import (
     CHANNELWISE_METRICS,
+    plot_chunked_drift_on_axis,
     plot_drift_on_axis,
     prepare_balance_data,
+    prepare_chunked_drift,
     prepare_diversity_data,
     prepare_drift_data,
 )
 from dataeval_plots.protocols import (
     PlottableBalance,
     PlottableDiversity,
+    PlottableDrift,
     PlottableDriftMVDC,
     PlottableFeasibility,
     PlottableStats,
@@ -493,6 +496,47 @@ class SeabornBackend(BasePlottingBackend):
         fig.tight_layout()
         return fig
 
+    def _plot_drift(
+        self,
+        output: PlottableDrift,
+        figsize: tuple[float, float] | None = None,
+    ) -> Figure:
+        """
+        Render the metric of each chunk in relation to the thresholds of the detector.
+
+        Parameters
+        ----------
+        output : PlottableDrift
+            The chunked drift output object to plot
+        figsize : tuple[float, float] or None, default None
+            Figure size in inches (width, height). If None, defaults to (10, 4).
+
+        Returns
+        -------
+        matplotlib.figure.Figure
+        """
+        import matplotlib.pyplot as plt
+        import seaborn as sns
+
+        sns.set_style("whitegrid")
+        palette = sns.color_palette("deep")  # not the global palette, which a user can shorten
+
+        data = prepare_chunked_drift(output)
+
+        fig, ax = plt.subplots(figsize=figsize or (10, 4))
+        plot_chunked_drift_on_axis(
+            ax,
+            data,
+            line_color=palette[0],
+            band_color=palette[2],
+            drift_color=palette[3],
+            reference_color=palette[7],
+        )
+        ax.set_title("Drift by chunk")
+        sns.despine(ax=ax)
+        fig.tight_layout()
+        return fig
+
     def _plot_feasibility(
         self,
         output: PlottableFeasibility,

{dataeval_plots-0.0.15 → dataeval_plots-0.0.17}/src/dataeval_plots/backends/_shared.py

@@ -15,12 +15,16 @@ import numpy as np
 import polars as pl
 from numpy.typing import NDArray
 
+from dataeval_plots.protocols import PlottableFeasibilityDecisions
+
 if TYPE_CHECKING:
     from dataeval_plots.protocols import (
         PlottableBalance,
         PlottableDiversity,
+        PlottableDrift,
         PlottableDriftMVDC,
         PlottableFeasibility,
+        PlottableFeasibilityDeterminations,
     )
 
 MethodType = Literal[
@@ -46,6 +50,10 @@ __all__ = [
     "prepare_diversity_data",
     "prepare_drift_data",
     "plot_drift_on_axis",
+    "CHUNKED_DRIFT_COLUMNS",
+    "ChunkedDriftData",
+    "prepare_chunked_drift",
+    "plot_chunked_drift_on_axis",
     "FEASIBILITY_COLORS",
     "FEASIBILITY_CONFLICT_TEXT",
     "FeasibilityBand",
@@ -498,6 +506,200 @@ def prepare_drift_data(
     return resdf, trndf, tstdf, driftx, True
 
 
+CHUNKED_DRIFT_COLUMNS = ("index", "value", "lower_threshold", "upper_threshold", "drifted")
+
+
+@dataclass(frozen=True)
+class ChunkedDriftData:
+    """
+    The per-chunk results of a chunked drift detector, ready for plotting.
+
+    Attributes
+    ----------
+    frame : pl.DataFrame
+        One row per chunk with the columns ``index``, ``value``, ``lower_threshold``, ``upper_threshold``,
+        ``drifted`` and ``period``. The rows of the reference chunks come first, numbered from ``-n`` to ``-1``
+        so that the analysis chunks keep their own indexes, and have ``period`` set to ``"reference"``. The
+        analysis chunks have ``period`` set to ``"analysis"``.
+    metric_name : str
+        Name of the metric that ``value`` reports
+    chunk_label : str
+        Label for the axis of chunks, which includes the size of a chunk when every analysis chunk has the same size
+    """
+
+    frame: pl.DataFrame
+    metric_name: str
+    chunk_label: str
+
+    @property
+    def reference(self) -> pl.DataFrame:
+        """The rows of the reference chunks, which is empty when the output carries no baseline."""
+        return self.frame.filter(pl.col("period") == "reference")
+
+    @property
+    def analysis(self) -> pl.DataFrame:
+        """The rows of the analysis chunks."""
+        return self.frame.filter(pl.col("period") == "analysis")
+
+
+def prepare_chunked_drift(output: PlottableDrift) -> ChunkedDriftData:
+    """
+    Read the per-chunk table, the reference chunks and the metric name from a chunked drift output.
+
+    The reference chunks are the optional ``baseline`` attribute of the output, which holds the metric of each
+    reference chunk. An output without it, such as one from an earlier version of DataEval, has no reference rows
+    and the plot leaves them out.
+
+    Parameters
+    ----------
+    output : PlottableDrift
+        The drift output object to plot
+
+    Returns
+    -------
+    ChunkedDriftData
+        The per-chunk results. A threshold that is missing, as for a one-sided detector, is replaced by a bound just
+        beyond the data, so that the range of no drift has no limit on that side.
+
+    Raises
+    ------
+    ValueError
+        If the output holds the statistics of a single test and not a per-chunk table, or if the table lacks a column
+        that the plot needs
+    """
+    details = output.details
+    if not isinstance(details, pl.DataFrame):
+        raise ValueError("Plotting drift needs chunked results. Call .chunked() on the detector before predict().")
+    missing = [name for name in CHUNKED_DRIFT_COLUMNS if name not in details.columns]
+    if missing:
+        raise ValueError(f"The per-chunk drift results lack the columns {missing}.")
+
+    analysis = details.select(
+        pl.col("index").cast(pl.Int64),
+        pl.col("value", "lower_threshold", "upper_threshold").cast(pl.Float64),
+        pl.col("drifted").cast(pl.Boolean),
+        pl.lit("analysis").alias("period"),
+    )
+
+    # The thresholds come from the reference chunks, so the band spans them too
+    baseline = np.asarray(getattr(output, "baseline", None) or (), dtype=np.float64)
+    if len(baseline) and len(analysis):
+        reference = pl.DataFrame(
+            {
+                "index": np.arange(-len(baseline), 0, dtype=np.int64),
+                "value": baseline,
+                "lower_threshold": [analysis["lower_threshold"][0]] * len(baseline),
+                "upper_threshold": [analysis["upper_threshold"][0]] * len(baseline),
+                "drifted": [False] * len(baseline),
+                "period": ["reference"] * len(baseline),
+            },
+            schema=analysis.schema,
+        )
+        frame = pl.concat([reference, analysis])
+    else:
+        frame = analysis
+
+    if frame["lower_threshold"].null_count() or frame["upper_threshold"].null_count():
+        extent = pl.concat([frame["value"], frame["lower_threshold"], frame["upper_threshold"]]).drop_nulls()
+        low, high = extent.min(), extent.max()
+        pad = 0.1 * (high - low) if low != high else 1.0  # type: ignore[operator]
+        frame = frame.with_columns(
+            pl.col("lower_threshold").fill_null(low - pad),  # type: ignore[operator]
+            pl.col("upper_threshold").fill_null(high + pad),  # type: ignore[operator]
+        )
+
+    return ChunkedDriftData(frame, output.metric_name, _chunk_label(details))
+
+
+def _chunk_label(details: pl.DataFrame) -> str:
+    """Label the axis of chunks with the size of a chunk, when every chunk has the same size."""
+    if "start_index" in details.columns and "end_index" in details.columns and len(details):
+        sizes = (details["end_index"] - details["start_index"] + 1).unique()
+        if len(sizes) == 1 and (details["start_index"] >= 0).all():
+            return f"Chunk ({sizes[0]} samples each)"
+    return "Chunk"
+
+
+def plot_chunked_drift_on_axis(
+    ax: Any,
+    data: ChunkedDriftData,
+    line_color: Any = "tab:blue",
+    band_color: Any = "tab:green",
+    drift_color: Any = "tab:red",
+    reference_color: Any = "tab:gray",
+    linewidth: float = 1.5,
+) -> None:
+    """
+    Plot the metric of each chunk against the threshold range of the detector on a matplotlib axis.
+
+    This is a shared helper for the matplotlib and seaborn backends. The metric is a line with a marker per chunk,
+    the band is the range between the lower and upper thresholds in which a chunk counts as no drift, and a diamond
+    marks each chunk that the detector flagged. When the output carries the metric of the reference chunks, they are
+    drawn in a second color to the left of the analysis chunks, with a dotted line between them.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        Axis to plot on
+    data : ChunkedDriftData
+        Per-chunk results from :func:`prepare_chunked_drift`
+    line_color : Any, default "tab:blue"
+        Color of the metric line of the analysis chunks
+    band_color : Any, default "tab:green"
+        Color of the band between the thresholds
+    drift_color : Any, default "tab:red"
+        Color of the markers on the chunks with drift
+    reference_color : Any, default "tab:gray"
+        Color of the metric line of the reference chunks and of the line that separates them
+    linewidth : float, default 1.5
+        Width of the metric lines
+    """
+    from matplotlib.ticker import MaxNLocator
+
+    frame, reference, analysis = data.frame, data.reference, data.analysis
+    ax.fill_between(
+        frame["index"].to_numpy(),
+        frame["lower_threshold"].to_numpy(),
+        frame["upper_threshold"].to_numpy(),
+        step="mid",
+        color=band_color,
+        alpha=0.15,
+        label="No-drift range",
+    )
+    if len(reference):
+        ax.plot(
+            reference["index"].to_numpy(),
+            reference["value"].to_numpy(),
+            marker="o",
+            color=reference_color,
+            linewidth=linewidth,
+            label="Reference chunks",
+        )
+        ax.axvline(-0.5, color=reference_color, linestyle=":", linewidth=1)
+    ax.plot(
+        analysis["index"].to_numpy(),
+        analysis["value"].to_numpy(),
+        marker="o",
+        color=line_color,
+        linewidth=linewidth,
+        label="Analysis chunks",
+    )
+    drifted = analysis.filter(pl.col("drifted"))
+    if len(drifted):
+        ax.scatter(
+            drifted["index"].to_numpy(),
+            drifted["value"].to_numpy(),
+            marker="D",
+            color=drift_color,
+            zorder=3,
+            label="Drift",
+        )
+    ax.xaxis.set_major_locator(MaxNLocator(integer=True))
+    ax.set_xlabel(data.chunk_label)
+    ax.set_ylabel(data.metric_name)
+    ax.legend(loc="best")
+
+
 def plot_drift_on_axis(
     ax: Any,
     resdf: Any,
@@ -982,12 +1184,19 @@ def _feasibility_band(
     )
 
 
-# These mirror DataEval's performance/_feasibility.py: _SOURCES, _source_name, _unit_noun and FeasibilityOutput._bounds
+# The readable name of each source: by DataEval 1.2.0's evidence id (these mirror its performance/_feasibility.py:
+# _SOURCES, _source_name, _unit_noun and FeasibilityOutput._bounds), and by the `source` value of the decisions and
+# bounds shape. Any other value shows its own text.
 _SOURCE_NAMES = {
     "replica_ceiling/v1": "repeated labels",
     "builtin_witness/v1:knn": "built-in k-NN",
     "builtin_witness/v1:probe": "built-in linear probe",
     "user_witness/v1": "your model",
+    "local_panels": _GROUP_CEILING,
+    "replicas": "repeated labels",
+    "knn": "built-in k-NN",
+    "linear_probe": "built-in linear probe",
+    "user_model": "your model",
 }
 _EVIDENCE_SCHEMA = {
     "target_spec": pl.String,
@@ -1009,7 +1218,7 @@ _EVIDENCE_SCHEMA = {
 }
 
 
-def _evidence_rows(output: PlottableFeasibility) -> pl.DataFrame:
+def _evidence_rows(output: PlottableFeasibilityDeterminations) -> pl.DataFrame:
     """One row per endpoint on a target in ``determinations``, in their order, then the order of ``evidence``."""
     targets = {r["target_spec"]: r for r in output.determinations.iter_rows(named=True)}
     rows = []
@@ -1049,6 +1258,84 @@ def _evidence_rows(output: PlottableFeasibility) -> pl.DataFrame:
     return pl.DataFrame(rows, schema=_EVIDENCE_SCHEMA)
 
 
+def _decisions_inputs(output: PlottableFeasibilityDecisions) -> tuple[list[dict[str, Any]], pl.DataFrame]:
+    """
+    Read the decisions and bounds shape as the determination rows and evidence frame the bands are built from.
+
+    The rows use the determinations shape's vocabulary, so everything downstream reads either shape alike: an
+    unresolved decision with limitation ``conflict`` is an ``evidence_conflict``, and ``envelope`` is a ``ceiling``.
+    """
+    decisions = list(output.decisions.iter_rows(named=True))
+    bounds = list(output.bounds.iter_rows(named=True))
+    rows: list[dict[str, Any]] = []
+    evidence: list[dict[str, Any]] = []
+    for d in decisions:
+        # ponytail: a private join key in the old reader's vocabulary; typed keys replace it when that reader goes
+        spec = json.dumps(
+            {
+                "metric": d["metric"],
+                "scope": d["judged_scope"],
+                "class_name": d["class_name"],
+                "aggregation": d["aggregation"],
+                "ap_functional": d["ap_functional"],
+                "max_false_positive_rate": d["max_false_positive_rate"],
+                "threshold": d["threshold"],
+            },
+            sort_keys=True,
+        )
+        conflict = d["decision"] == "unresolved" and d["limitation"] == "conflict"
+        rows.append(
+            {
+                "target_spec": spec,
+                "metric": d["metric"],
+                "threshold": d["threshold"],
+                "judged_scope": d["judged_scope"],
+                "determination": "evidence_conflict" if conflict else d["decision"],
+                "ceiling": d["envelope"],
+                "ceiling_scope": d["envelope_scope"],
+                "witness": d["witness"],
+                "witness_source": d["witness_source"],
+            }
+        )
+        mine = [b for b in bounds if b["requirement"] == d["requirement"]]
+        f0 = d["max_false_positive_rate"]
+        for b in mine:
+            q = _FALSE_POSITIVE if b["quantity"] == _FALSE_POSITIVE else "metric"
+            fp = next(
+                (x["bound"] for x in mine if x["source"] == b["source"] and x["quantity"] == _FALSE_POSITIVE), None
+            )
+            # A recall witness counts only when its own false-positive upper bound is within the limit
+            uncertified = q == "metric" and b["bound_type"] == "lower" and f0 is not None and (fp is None or fp > f0)
+            evidence.append(
+                {
+                    "target_spec": spec,
+                    "metric": d["metric"],
+                    "threshold": d["threshold"],
+                    "source": _SOURCE_NAMES.get(b["source"], b["source"]),
+                    "evidence_id": b["source"],
+                    "information_scope": b["information_scope"],
+                    "unit": b["unit"],
+                    "bound_type": b["bound_type"],
+                    "observed": b["observed"],
+                    "bound": b["bound"],
+                    "n": b["n"],
+                    "state": b["state"],
+                    "quantity": q,
+                    "uncertified": uncertified,
+                    "false_positive_bound": fp,
+                    "false_positive_limit": f0,
+                }
+            )
+    return rows, pl.DataFrame(evidence, schema=_EVIDENCE_SCHEMA)
+
+
+def _feasibility_inputs(output: PlottableFeasibility) -> tuple[list[dict[str, Any]], pl.DataFrame]:
+    """The determination rows and evidence frame of a feasibility output in either shape."""
+    if isinstance(output, PlottableFeasibilityDecisions):
+        return _decisions_inputs(output)
+    return list(output.determinations.iter_rows(named=True)), _evidence_rows(output)
+
+
 def prepare_feasibility_data(output: PlottableFeasibility) -> list[FeasibilityBand]:
     """
     Prepare feasibility data for plotting across all backends.
@@ -1066,13 +1353,13 @@ def prepare_feasibility_data(output: PlottableFeasibility) -> list[FeasibilityBa
     list[FeasibilityBand]
         One band per quantity, in the order the determinations first name it
     """
-    rows = list(output.determinations.iter_rows(named=True))
+    rows, evidence_frame = _feasibility_inputs(output)
     groups: dict[str, list[dict[str, Any]]] = {}
     for row in rows:
         spec = json.loads(row["target_spec"])
         spec.pop("threshold", None)
         groups.setdefault(json.dumps(spec, sort_keys=True), []).append(row)
-    evidence = _evidence_rows(output).to_dicts()
+    evidence = evidence_frame.to_dicts()
     alpha = output.meta().state["alpha"]
     noun = _unit(rows, [e for e in evidence if e["quantity"] == "metric"]) or "image"  # the printout's footer noun
     bands = []

{dataeval_plots-0.0.15 → dataeval_plots-0.0.17}/src/dataeval_plots/protocols.py

@@ -12,7 +12,10 @@ The protocol hierarchy:
   - PlottableSufficiency
   - PlottableStats
   - PlottableDriftMVDC
-  - PlottableFeasibility
+  - PlottableDrift
+  - PlottableFeasibilityDeterminations
+  - PlottableFeasibilityDecisions
+  - PlottableFeasibility (either of the two feasibility shapes)
 """
 
 from __future__ import annotations
@@ -122,13 +125,15 @@ class Plottable(Protocol):
     """
 
     @property
-    def plot_type(self) -> Literal["balance", "diversity", "sufficiency", "stats", "drift_mvdc", "feasibility"]:
+    def plot_type(
+        self,
+    ) -> Literal["balance", "diversity", "sufficiency", "stats", "drift_mvdc", "drift", "feasibility"]:
         """Return the plot type identifier for routing to appropriate plot function.
 
         Returns
         -------
         str
-            One of: 'balance', 'diversity', 'sufficiency', 'stats', 'drift_mvdc', 'feasibility'
+            One of: 'balance', 'diversity', 'sufficiency', 'stats', 'drift_mvdc', 'drift', 'feasibility'
         """
         ...
 
@@ -289,6 +294,38 @@ class PlottableDriftMVDC(Plottable, Protocol):
     def plot_type(self) -> Literal["drift_mvdc"]: ...
 
 
+@runtime_checkable
+class PlottableDrift(Plottable, Protocol):
+    """Protocol for chunked drift detector outputs.
+
+    Required attributes:
+    - details: Per-chunk results as a polars DataFrame
+    - metric_name: Name of the drift metric that each chunk reports
+    - plot_type -> 'drift'
+    """
+
+    @property
+    def details(self) -> Any:
+        """Per-chunk drift results.
+
+        Returns
+        -------
+        pl.DataFrame
+            One row per chunk with the columns ``index``, ``value``, ``lower_threshold``, ``upper_threshold`` and
+            ``drifted``. A detector that was not chunked holds a mapping of statistics instead, which cannot be
+            plotted.
+        """
+        ...
+
+    @property
+    def metric_name(self) -> str:
+        """Name of the metric that ``value`` reports, such as ``auroc`` or ``mmd2``."""
+        ...
+
+    @property
+    def plot_type(self) -> Literal["drift"]: ...
+
+
 class FeasibilityEndpoint(Protocol):
     """
     One bound on one target, as DataEval's ``Endpoint`` records it; only the fields the plot reads.
@@ -323,8 +360,8 @@ class FeasibilityEvidence(Protocol):
 
 
 @runtime_checkable
-class PlottableFeasibility(Plottable, Protocol):
-    """Protocol for feasibility plot outputs.
+class PlottableFeasibilityDeterminations(Plottable, Protocol):
+    """Protocol for feasibility plot outputs in the ``determinations`` and ``evidence`` shape.
 
     Required attributes:
     - determinations: One row per target (DataFrame)
@@ -347,6 +384,45 @@ class PlottableFeasibility(Plottable, Protocol):
     def plot_type(self) -> Literal["feasibility"]: ...
 
 
+@runtime_checkable
+class PlottableFeasibilityDecisions(Plottable, Protocol):
+    """Protocol for feasibility plot outputs in the ``decisions`` and ``bounds`` shape.
+
+    Required attributes:
+    - decisions: One row per requirement (DataFrame)
+    - bounds: One row per source, requirement and quantity (DataFrame)
+    - meta().state["alpha"]: The call's error budget
+    - plot_type -> 'feasibility'
+
+    Structures:
+    - decisions columns: requirement, metric, threshold, judged_scope, class_name, aggregation, ap_functional,
+      max_false_positive_rate, decision, limitation, envelope, envelope_scope, witness, witness_source
+    - bounds columns: requirement, source, role, quantity, bound_type, information_scope, unit, state, bound,
+      observed, n; ``requirement`` joins a bound to its decisions row
+
+    Enum columns are read as strings, with these values:
+    - decision: demonstrated_feasible, infeasible_under_recorded_assumptions, not_ruled_out, unresolved
+    - limitation: only ``conflict`` is read; with decision ``unresolved`` it marks a conflict between a witness and an
+      envelope
+    - judged_scope, envelope_scope, information_scope: full_input, fixed_representation, partition_restricted
+    - source, witness_source: local_panels, replicas, knn, linear_probe, user_model (any other value shows its text)
+    - role: envelope, witness. bound_type: lower, upper
+    - quantity: a metric name (accuracy, ap, recall, recall_at_fp, mota) or false_positive_rate
+    - state: unavailable, uninformative, informative. unit: image, sequence
+    - aggregation: frame_pooled, sequence_mean. ap_functional: population_ap_integral, population_ap_101
+    """
+
+    @property
+    def decisions(self) -> pl.DataFrame: ...
+    @property
+    def bounds(self) -> pl.DataFrame: ...
+    @property
+    def plot_type(self) -> Literal["feasibility"]: ...
+
+
+PlottableFeasibility = PlottableFeasibilityDeterminations | PlottableFeasibilityDecisions
+"""A feasibility output in either shape; DataEval 1.2.0 gives the first, later releases the second."""
+
 # Type alias for all plottable types
 PlottableType = (
     Dataset
@@ -355,5 +431,6 @@ PlottableType = (
     | PlottableSufficiency
     | PlottableStats
     | PlottableDriftMVDC
+    | PlottableDrift
     | PlottableFeasibility
 )