trendify2 2.0.4__py3-none-any.whl

trendify/plotting/figure.py

@@ -0,0 +1,389 @@
+"""
+`SingleAxisFigure` (matplotlib) and `PlotlyFigure` (Plotly) wrap a figure/axes pair and know how
+to apply a `Format2D`/`Grid` to it and save it to disk. These are the two rendering targets
+every `PlottableData2D` subclass draws itself onto (`plot_to_ax` for matplotlib, `add_to_plotly`
+for Plotly).
+"""
+
+from __future__ import annotations
+
+import logging
+import warnings
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Self, cast
+
+import matplotlib
+import matplotlib.pyplot as plt
+import numpy as np
+import plotly.graph_objects as go
+from pydantic import ConfigDict
+
+from trendify.base.helpers import Tag
+from trendify.formats.format2d import AxisScale, PlottableData2D
+
+if TYPE_CHECKING:
+    from matplotlib.axes import Axes
+    from matplotlib.figure import Figure
+
+    from trendify.formats.format2d import Format2D
+    from trendify.styling.grid import Grid
+
+
+__all__ = ["PlotlyFigure", "SingleAxisFigure"]
+
+logger = logging.getLogger(__name__)
+
+# This pipeline only ever renders headlessly (batch CLI/worker processes, no interactive
+# window), so pin the backend explicitly before the first figure is ever created. Left
+# unset, pyplot's lazy backend auto-selection probes for a live GUI display on the very
+# first `plt.figure()` call (`matplotlib._c_internal_utils.display_is_valid`), which is a
+# multi-second stall on some systems for a check whose answer we don't care about anyway.
+matplotlib.use("Agg")
+
+
+@dataclass
+class SingleAxisFigure:
+    """
+    Data class storing a matlab figure and axis.  The stored tag data in this class is so-far unused.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    tag: Tag
+    """Figure tag. Not yet used."""
+
+    fig: Figure
+    """Matplotlib figure."""
+
+    ax: Axes
+    """Matplotlib axis to which data will be plotted."""
+
+    @classmethod
+    def new(cls, tag: Tag):
+        """
+        Creates new figure and axis.  Returns new instance of this class.
+
+        Args:
+            tag (Tag): tag (not yet used)
+
+        Returns:
+            (Type[Self]): New single axis figure
+
+        """
+        fig = plt.figure()
+        ax = fig.add_subplot(1, 1, 1)
+        return cls(
+            tag=tag,
+            fig=fig,
+            ax=ax,
+        )
+
+    def apply_format(self, format2d: Format2D) -> Self:
+        """
+        Applies format to figure and axes labels and limits
+
+        Args:
+            format2d (Format2D): format information to apply to the single axis figure
+
+        """
+        if format2d.title_ax is not None:
+            self.ax.set_title(format2d.title_ax)
+        if format2d.title_fig is not None:
+            self.fig.suptitle(format2d.title_fig)
+
+        leg = None
+        if format2d.legend is not None:
+            with warnings.catch_warnings(action="ignore", category=UserWarning):
+                handles, labels = self.ax.get_legend_handles_labels()
+                by_label = dict(zip(labels, handles))
+                if by_label:
+                    sorted_items = sorted(by_label.items(), key=lambda item: item[0])
+                    labels_sorted, handles_sorted = zip(*sorted_items)
+
+                    kwargs = format2d.legend.to_kwargs()
+
+                    leg = self.ax.legend(
+                        handles=handles_sorted,
+                        labels=labels_sorted,
+                        bbox_to_anchor=format2d.legend.bbox_to_anchor,
+                        **kwargs,
+                    )
+                    leg.set_zorder(level=format2d.legend.zorder)
+
+                    if leg is not None and format2d.legend.edgecolor:
+                        leg.get_frame().set_edgecolor(format2d.legend.edgecolor)
+
+        if format2d.label_x is not None:
+            self.ax.set_xlabel(xlabel=format2d.label_x)
+        if format2d.label_y is not None:
+            self.ax.set_ylabel(ylabel=format2d.label_y)
+
+        self.ax.set_xlim(left=format2d.lim_x[0], right=format2d.lim_x[1])
+        self.ax.set_ylim(bottom=format2d.lim_y[0], top=format2d.lim_y[1])
+
+        self.ax.set_xscale(format2d.scale_x.value)
+        self.ax.set_yscale(format2d.scale_y.value)
+
+        if format2d.grid is not None:
+            self.apply_grid(format2d.grid)
+
+        self.fig.set_size_inches(format2d.figure_width, format2d.figure_height)
+        self.fig.tight_layout(rect=(0, 0.03, 1, 0.95))
+        return self
+
+    def apply_grid(self, grid: Grid) -> None:
+        self.ax.set_axisbelow(True)
+
+        # Major grid
+        if grid.major.show:
+            self.ax.grid(
+                visible=True,
+                which="major",
+                color=grid.major.pen.color,
+                linestyle=grid.major.pen.linestyle,
+                linewidth=grid.major.pen.size,
+                alpha=grid.major.pen.alpha,
+                zorder=grid.zorder,
+            )
+        else:
+            self.ax.grid(visible=False, which="major")
+
+        # Minor ticks and grid
+        if grid.enable_minor_ticks:
+            self.ax.minorticks_on()
+        else:
+            self.ax.minorticks_off()
+
+        if grid.minor.show:
+            self.ax.grid(
+                visible=True,
+                which="minor",
+                color=grid.minor.pen.color,
+                linestyle=grid.minor.pen.linestyle,
+                linewidth=grid.minor.pen.size,
+                alpha=grid.minor.pen.alpha,
+                zorder=grid.zorder,
+            )
+        else:
+            self.ax.grid(visible=False, which="minor")
+
+    def savefig(self, path: Path, dpi: int | None = None) -> Self:
+        """
+        Wrapper on matplotlib savefig method. Saves figure to given path, at the given `dpi`
+        for raster output. `dpi` is meaningless for vector output (e.g. `.svg`), so `None`
+        leaves it unset and matplotlib infers the format from `path`'s suffix either way.
+
+        Returns:
+            (Self): Returns self
+
+        """
+        logger.debug(f"Saving matplotlib figure for {self.tag = } to {path} ({dpi = })")
+        if dpi is not None:
+            self.fig.savefig(path, dpi=dpi)
+        else:
+            self.fig.savefig(path)
+        return self
+
+    def __del__(self):
+        """
+        Closes stored matplotlib figure before deleting reference to object.
+        """
+        plt.close(self.fig)
+
+
+@dataclass
+class PlotlyFigure:
+    """
+    Data class storing a Plotly figure alongside the legend groups added to it so far.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    tag: Tag
+    """Figure tag. Not yet used."""
+
+    fig: go.Figure
+    """Plotly figure."""
+
+    legend_groups: set[str] = field(default_factory=set)
+    """Legend group keys already added to `fig`, used to avoid duplicate legend entries when
+    multiple records share a style."""
+
+    @classmethod
+    def new(cls, tag: Tag):
+        """
+        Creates new figure and axis.  Returns new instance of this class.
+
+        Args:
+            tag (Tag): tag (not yet used)
+
+        Returns:
+            (Type[Self]): New single axis figure
+
+        """
+        fig = go.Figure()
+        return cls(tag=tag, fig=fig)
+
+    def apply_format(self, format2d: Format2D) -> Self:
+        """
+        Applies format to Plotly figure layout including axes labels and limits
+
+        Args:
+            format2d (Format2D): format information to apply to the figure
+
+        """
+        layout_updates: dict[str, Any] = {}
+
+        # `title_fig` maps to Plotly's main `title.text` (matches matplotlib's
+        # `fig.suptitle`); `title_ax` maps to Plotly's `title.subtitle.text` (matches
+        # matplotlib's `ax.set_title` sitting just below it), rather than concatenating
+        # both into one string.
+        title: dict[str, Any] = {}
+        if format2d.title_fig is not None:
+            title["text"] = format2d.title_fig
+        if format2d.title_ax is not None:
+            title["subtitle"] = {"text": format2d.title_ax}
+        if title:
+            layout_updates["title"] = title
+
+        # Set axis labels
+        if format2d.label_x is not None:
+            layout_updates["xaxis"] = cast(dict[str, Any], {"title": format2d.label_x})
+        if format2d.label_y is not None:
+            layout_updates["yaxis"] = cast(dict[str, Any], {"title": format2d.label_y})
+
+        # Set axis ranges
+        def _log10(v: float | None) -> float | None:
+            return None if v is None else np.log10(v)
+
+        if format2d.lim_x[0] is not None or format2d.lim_x[1] is not None:
+            if "xaxis" not in layout_updates:
+                layout_updates["xaxis"] = cast(dict[str, Any], {})
+
+            if format2d.scale_x == AxisScale.LOG:
+                layout_updates["xaxis"]["range"] = [
+                    _log10(format2d.lim_x[0]),
+                    _log10(format2d.lim_x[1]),
+                ]
+            elif format2d.scale_x == AxisScale.LINEAR:
+                # Deliberately checks LINEAR explicitly rather than falling through an
+                # unconditional else, so a third AxisScale value can't silently reuse the
+                # log-scaled range below.
+                layout_updates["xaxis"]["range"] = [
+                    format2d.lim_x[0],
+                    format2d.lim_x[1],
+                ]
+
+        if format2d.lim_y[0] is not None or format2d.lim_y[1] is not None:
+            if "yaxis" not in layout_updates:
+                layout_updates["yaxis"] = cast(dict[str, Any], {})
+            if format2d.scale_y == AxisScale.LOG:
+                layout_updates["yaxis"]["range"] = [
+                    _log10(format2d.lim_y[0]),
+                    _log10(format2d.lim_y[1]),
+                ]
+            elif format2d.scale_y == AxisScale.LINEAR:
+                # Same reasoning as the x-axis branch above.
+                layout_updates["yaxis"]["range"] = [
+                    format2d.lim_y[0],
+                    format2d.lim_y[1],
+                ]
+
+        # Set axis scales
+        if format2d.scale_x is not None:
+            if "xaxis" not in layout_updates:
+                layout_updates["xaxis"] = cast(dict[str, Any], {})
+            layout_updates["xaxis"]["type"] = format2d.scale_x.value
+
+        if format2d.scale_y is not None:
+            if "yaxis" not in layout_updates:
+                layout_updates["yaxis"] = cast(dict[str, Any], {})
+            layout_updates["yaxis"]["type"] = format2d.scale_y.value
+
+        # Set legend
+        if format2d.legend is not None:
+            layout_updates["showlegend"] = format2d.legend.visible
+            layout_updates["legend"] = dict(
+                title=format2d.legend.title,
+                bordercolor=format2d.legend.edgecolor,
+                **format2d.legend.plotly_location,
+            )
+
+        # Apply grid if specified
+        if format2d.grid is not None:
+            self.apply_grid(format2d.grid)
+
+        # Update layout
+        self.fig.update_layout(**layout_updates)
+        return self
+
+    def apply_grid(self, grid: Grid) -> None:
+        """
+        Applies grid settings to the Plotly figure
+
+        Args:
+            grid (Grid): Grid configuration to apply
+
+        """
+        # Major grid
+
+        xaxis_updates = {
+            "showgrid": grid.major.show,
+            "gridcolor": grid.major.pen.rgba if grid.major.show else None,
+            "gridwidth": grid.major.pen.size if grid.major.show else None,
+            "griddash": "solid" if grid.major.pen.linestyle == "-" else "dash",
+        }
+
+        yaxis_updates = {
+            "showgrid": grid.major.show,
+            "gridcolor": grid.major.pen.rgba if grid.major.show else None,
+            "gridwidth": grid.major.pen.size if grid.major.show else None,
+            "griddash": "solid" if grid.major.pen.linestyle == "-" else "dash",
+        }
+
+        # Minor ticks and grid
+        if grid.enable_minor_ticks:
+            xaxis_updates["minor"] = {
+                "showgrid": grid.minor.show,
+                "gridcolor": grid.minor.pen.rgba if grid.minor.show else None,
+                "gridwidth": grid.minor.pen.size if grid.minor.show else None,
+                "griddash": "solid" if grid.minor.pen.linestyle == "-" else "dash",
+            }
+            yaxis_updates["minor"] = {
+                "showgrid": grid.minor.show,
+                "gridcolor": grid.minor.pen.rgba if grid.minor.show else None,
+                "gridwidth": grid.minor.pen.size if grid.minor.show else None,
+                "griddash": "solid" if grid.minor.pen.linestyle == "-" else "dash",
+            }
+
+        self.fig.update_xaxes(**xaxis_updates)
+        self.fig.update_yaxes(**yaxis_updates)
+
+    def add_record(self, record: PlottableData2D) -> PlotlyFigure:
+        """
+        Add a record to the figure. Every trace `record.add_to_plotly` adds (there's always at
+        most one -- `AxLine` adds none, since it renders as a layout shape instead) gets
+        `record.metadata` attached as its Plotly `meta` attribute: not rendered by Plotly
+        itself, but present verbatim in `to_plotly_json()`'s output, which is how the viewer's
+        `/api/plot` response lets the dashboard filter traces by metadata client-side without
+        a separate endpoint or a schema change (see `viewer/templates/.../metadata-filter.ts`).
+
+        Args:
+            record (PlottableData2D): Record to add to figure
+
+        Returns:
+            Self: Returns self for method chaining
+
+        """
+        # `fig.data`'s dynamically-generated attributes defeat pyright's static analysis here
+        # the same way `fig.layout`'s do in test_figure.py's `_layout` helper -- `Any` is a
+        # deliberate, narrow escape hatch at this one boundary, not a blanket opt-out. Read
+        # fresh (not cached across `add_to_plotly`): `fig.data` is an immutable tuple, so
+        # `add_trace` rebinds it to a new, longer one rather than mutating in place.
+        n_before = len(cast(Any, self.fig.data))
+        record.add_to_plotly(self)
+        if record.metadata:
+            for trace in cast(Any, self.fig.data)[n_before:]:
+                trace.meta = record.metadata
+        return self

trendify/plotting/histogram.py

@@ -0,0 +1,282 @@
+"""
+`HistogramEntry` (a single value to be binned into a matplotlib/Plotly histogram) and its
+`HistogramStyle` (bar color, opacity, bin count, and the derived RGBA/contrast-color helpers
+used by both renderers).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Literal, cast
+
+import numpy as np
+import plotly.graph_objects as go
+from matplotlib.colors import to_rgba
+from pydantic import ConfigDict, Field, field_validator, model_validator
+
+from trendify.base.helpers import HashableBase, Tags
+from trendify.formats.format2d import PlottableData2D
+from trendify.plotting.figure import PlotlyFigure
+from trendify.typing import VecN
+
+__all__ = ["HistogramEntry", "HistogramStyle"]
+
+logger = logging.getLogger(__name__)
+
+
+class HistogramStyle(HashableBase):
+    """
+    Label and style data for generating histogram bars
+    """
+
+    color: str = "k"
+    """Color of bars"""
+
+    label: str | None = None
+    """Legend entry"""
+
+    histtype: Literal["bar", "step", "stepfilled"] = "stepfilled"
+    """Histogram type corresponding to matplotlib argument of same name"""
+
+    alpha_edge: float = 1.0
+    """Opacity of bar edge"""
+
+    alpha_face: float = 0.3
+    """Opacity of bar face"""
+
+    linewidth: float = 2.0
+    """Line width of bar outline"""
+
+    zorder: int = 1
+    """Prioritization"""
+
+    bins: int | tuple[int, ...] | None = None
+    """Number of bins (see [matplotlib docs][matplotlib.pyplot.hist])"""
+
+    @field_validator("bins", mode="before")
+    @classmethod
+    def _coerce_bins_to_hashable(
+        cls, value: int | list[int] | tuple[int] | VecN | None
+    ):
+        # `HistogramStyle` is a `HashableBase` (its instances are deduplicated via `set()` in
+        # `Histogrammer.handle_histogram_entries`), so `bins` can't be stored as a `list` or
+        # `np.ndarray`: both are unhashable and would break `HashableBase.__hash__`.
+        if isinstance(value, (list, np.ndarray)):
+            return tuple(int(v) for v in value)
+        return value
+
+    @model_validator(mode="after")
+    def _visible_edge_for_step_histtype(self) -> HistogramStyle:
+        # `histtype="step"` draws an edge-only patch (`fill=False`), so `alpha_edge` is the
+        # only thing that can make it visible at all, unlike "bar"/"stepfilled" where the
+        # face fill carries the color and a zero-alpha edge is just borderless.
+        # `alpha_edge`'s class default of 0 is right for those other histtypes but leaves a
+        # "step" histogram completely invisible, so bump it to opaque if left at zero.
+        if self.histtype == "step" and self.alpha_edge == 0:
+            logger.warning(
+                "Histogram type was set to 'step' but alpha_edge was 0, coercing edge transparency to 1"
+            )
+            self.alpha_edge = 1
+        return self
+
+    def as_plot_kwargs(self) -> dict[str, Any]:
+        """
+        Returns:
+            (dict): kwargs for matplotlib `hist` method
+
+        """
+        return {
+            "facecolor": (self.color, self.alpha_face),
+            "edgecolor": (self.color, self.alpha_edge),
+            "linewidth": self.linewidth,
+            "label": self.label,
+            "histtype": self.histtype,
+            "bins": self.bins,
+            "zorder": self.zorder,
+        }
+
+    @property
+    def rgba_face(self) -> str:
+        """
+        Convert the pen's color to rgba string format.
+
+        Returns:
+            str: Color in 'rgba(r,g,b,a)' format where r,g,b are 0-255 and a is 0-1
+
+        """
+        # Handle different color input formats
+        if isinstance(self.color, tuple):
+            if len(self.color) == 3:  # RGB tuple
+                r, g, b = self.color
+                a = self.alpha_face
+            else:  # RGBA tuple
+                r, g, b, a = self.color
+            # Convert 0-1 range to 0-255 for RGB
+            r, g, b = int(r * 255), int(g * 255), int(b * 255)
+        else:  # String color (name or hex)
+            # Use matplotlib's color converter
+            rgba_vals = to_rgba(self.color, self.alpha_face)
+            # Convert 0-1 range to 0-255 for RGB
+            r, g, b = [int(x * 255) for x in rgba_vals[:3]]
+            a = rgba_vals[3]
+
+        return f"rgba({r}, {g}, {b}, {a})"
+
+    @property
+    def rgba_edge(self) -> str:
+        """
+        Convert the pen's color to rgba string format.
+
+        Returns:
+            str: Color in 'rgba(r,g,b,a)' format where r,g,b are 0-255 and a is 0-1
+
+        """
+        # Handle different color input formats
+        if isinstance(self.color, tuple):
+            if len(self.color) == 3:  # RGB tuple
+                r, g, b = self.color
+                a = self.alpha_edge
+            else:  # RGBA tuple
+                r, g, b, a = self.color
+            # Convert 0-1 range to 0-255 for RGB
+            r, g, b = int(r * 255), int(g * 255), int(b * 255)
+        else:  # String color (name or hex)
+            # Use matplotlib's color converter
+            rgba_vals = to_rgba(self.color, self.alpha_edge)
+            # Convert 0-1 range to 0-255 for RGB
+            r, g, b = [int(x * 255) for x in rgba_vals[:3]]
+            a = rgba_vals[3]
+
+        return f"rgba({r}, {g}, {b}, {a})"
+
+    @property
+    def rgb_face(self) -> str:
+        return ", ".join(self.rgba_face.split(",")[0:-1]) + ")"
+
+    @property
+    def rgb_edge(self) -> str:
+        return ", ".join(self.rgba_edge.split(",")[0:-1]) + ")"
+
+    def get_face_contrast_color(self, background_luminance: float = 1.0) -> str:
+        """
+        Returns 'white' or 'black' to provide the best contrast against the pen's color,
+        taking into account the alpha (transparency) value of the line.
+
+        Args:
+            background_luminance (float): The luminance of the background (default is 1.0 for white).
+
+        Returns:
+            str: 'white' or 'black'
+
+        """
+        # Convert the pen's color to RGB (0-255 range) and get alpha
+        if isinstance(self.color, tuple):
+            if len(self.color) == 3:  # RGB tuple
+                r, g, b = self.color
+                a = self.alpha_face
+            else:  # RGBA tuple
+                r, g, b, a = self.color
+            r, g, b = int(r * 255), int(g * 255), int(b * 255)
+        else:  # String color (name or hex)
+            rgba_vals = to_rgba(self.color, self.alpha_face)
+            r, g, b = [int(x * 255) for x in rgba_vals[:3]]
+            a = rgba_vals[3]
+
+        # Calculate relative luminance of the pen's color
+        def luminance(channel: float) -> float:
+            channel /= 255.0
+            return (
+                channel / 12.92
+                if channel <= 0.03928
+                else ((channel + 0.055) / 1.055) ** 2.4
+            )
+
+        color_luminance = (
+            0.2126 * luminance(r) + 0.7152 * luminance(g) + 0.0722 * luminance(b)
+        )
+
+        # Blend the color luminance with the background luminance based on alpha
+        blended_luminance = (1 - a) * background_luminance + a * color_luminance
+
+        # Return white for dark blended colors, black for light blended colors
+        return "white" if blended_luminance < 0.5 else "black"
+
+
+class HistogramEntry(PlottableData2D):
+    """
+    Use this class to specify a value to be collected into a matplotlib histogram.
+    """
+
+    value: float | str
+    """Value to be binned"""
+
+    tags: Tags
+    """Tags used to sort records"""
+
+    style: HistogramStyle = Field(default_factory=HistogramStyle)
+    """Style of histogram display"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    def add_to_plotly(self, plotly_figure: PlotlyFigure) -> PlotlyFigure:
+        """Add histogram entry to plotly figure, merging with existing traces if possible"""
+        # Create legend group key based on the label and color
+        legend_key = (
+            f"{self.style.label}_{self.style.rgba_face}" if self.style.label else None
+        )
+
+        # Check if a trace with the same legend group already exists
+        traces = cast("tuple[go.Histogram, ...]", plotly_figure.fig.data)
+        for trace in traces:
+            if trace.legendgroup == legend_key:
+                # Append the value to the existing trace's x data
+                trace.x = [*(trace.x or ()), self.value]
+                return plotly_figure
+
+        metadata_html = (
+            "<br>".join([f"{key}: {value}" for key, value in self.metadata.items()])
+            if self.metadata
+            else ""
+        )
+
+        hovertemplate = (
+            f"<b>{self.style.label if self.style.label else ''}</b><br>"
+            "x: %{x}<br>"
+            "y: %{y}<br>"
+            f"{metadata_html}<extra></extra>"
+        )
+
+        # If no existing trace, add a new one
+        plotly_figure.fig.add_trace(
+            go.Histogram(
+                x=[self.value],
+                name=self.style.label,  # Legend label
+                marker=dict(
+                    color=self.style.rgba_face,
+                    line=dict(
+                        color=self.style.rgba_edge,
+                        width=self.style.linewidth,
+                    ),
+                ),
+                zorder=self.style.zorder,
+                nbinsx=self.style.bins if isinstance(self.style.bins, int) else None,
+                legendgroup=legend_key,  # Group histograms with the same label and color
+                hovertemplate=hovertemplate,
+                hoverlabel=dict(
+                    bgcolor=self.style.rgba_face,
+                    bordercolor=self.style.rgba_edge,
+                    font=dict(
+                        color=self.style.get_face_contrast_color()  # Optionally, set the font color as well
+                    ),
+                ),
+                showlegend=(
+                    True if self.style.label is not None else False
+                ),  # Always show legend for the first trace
+            )
+        )
+
+        # Track the legend group to avoid duplicate legend entries
+        if legend_key and legend_key not in plotly_figure.legend_groups:
+            plotly_figure.legend_groups.add(legend_key)
+
+        return plotly_figure