figrecipe 0.5.0__py3-none-any.whl → 0.7.4__py3-none-any.whl

figrecipe/_wrappers/_figure.py

@@ -3,16 +3,17 @@
 """Wrapped Figure that manages recording."""
 
 from pathlib import Path
-from typing import Any, Dict, List, Literal, Optional, Tuple, Union, TYPE_CHECKING
+from typing import TYPE_CHECKING, Any, List, Literal, Optional, Tuple, Union
 
 import matplotlib.pyplot as plt
+import numpy as np
 from matplotlib.figure import Figure
+from numpy.typing import NDArray
 
 from ._axes import RecordingAxes
 
 if TYPE_CHECKING:
-    from .._recorder import Recorder, FigureRecord
-    from .._utils._numpy_io import DataFormat
+    from .._recorder import FigureRecord, Recorder
 
 
 class RecordingFigure:
@@ -79,6 +80,229 @@ class RecordingFigure:
         """Get the figure record."""
         return self._recorder.figure_record
 
+    def _get_style_fontsize(self, key: str, default: float) -> float:
+        """Get fontsize from loaded style."""
+        try:
+            from ..styles._style_loader import _STYLE_CACHE
+
+            if _STYLE_CACHE is not None:
+                fonts = getattr(_STYLE_CACHE, "fonts", None)
+                if fonts is not None:
+                    return getattr(fonts, key, default)
+        except Exception:
+            pass
+        return default
+
+    def _get_theme_text_color(self, default: str = "black") -> str:
+        """Get text color from loaded style's theme settings."""
+        try:
+            from ..styles._style_loader import _STYLE_CACHE
+
+            if _STYLE_CACHE is not None:
+                theme = getattr(_STYLE_CACHE, "theme", None)
+                if theme is not None:
+                    mode = getattr(theme, "mode", "light")
+                    theme_colors = getattr(theme, mode, None)
+                    if theme_colors is not None:
+                        return getattr(theme_colors, "text", default)
+        except Exception:
+            pass
+        return default
+
+    def suptitle(self, t: str, **kwargs) -> Any:
+        """Set super title for the figure and record it.
+
+        Parameters
+        ----------
+        t : str
+            The super title text.
+        **kwargs
+            Additional arguments passed to matplotlib's suptitle().
+
+        Returns
+        -------
+        Text
+            The matplotlib Text object.
+        """
+        # Auto-apply fontsize from style if not specified
+        if "fontsize" not in kwargs:
+            kwargs["fontsize"] = self._get_style_fontsize("suptitle_pt", 10)
+        # Record the suptitle call
+        self._recorder.figure_record.suptitle = {"text": t, "kwargs": kwargs}
+        # Call the underlying figure's suptitle
+        return self._fig.suptitle(t, **kwargs)
+
+    def supxlabel(self, t: str, **kwargs) -> Any:
+        """Set super x-label for the figure and record it.
+
+        Parameters
+        ----------
+        t : str
+            The super x-label text.
+        **kwargs
+            Additional arguments passed to matplotlib's supxlabel().
+
+        Returns
+        -------
+        Text
+            The matplotlib Text object.
+        """
+        # Auto-apply fontsize from style if not specified
+        if "fontsize" not in kwargs:
+            kwargs["fontsize"] = self._get_style_fontsize("supxlabel_pt", 8)
+        # Record the supxlabel call
+        self._recorder.figure_record.supxlabel = {"text": t, "kwargs": kwargs}
+        # Call the underlying figure's supxlabel
+        return self._fig.supxlabel(t, **kwargs)
+
+    def supylabel(self, t: str, **kwargs) -> Any:
+        """Set super y-label for the figure and record it.
+
+        Parameters
+        ----------
+        t : str
+            The super y-label text.
+        **kwargs
+            Additional arguments passed to matplotlib's supylabel().
+
+        Returns
+        -------
+        Text
+            The matplotlib Text object.
+        """
+        # Auto-apply fontsize from style if not specified
+        if "fontsize" not in kwargs:
+            kwargs["fontsize"] = self._get_style_fontsize("supylabel_pt", 8)
+        # Record the supylabel call
+        self._recorder.figure_record.supylabel = {"text": t, "kwargs": kwargs}
+        # Call the underlying figure's supylabel
+        return self._fig.supylabel(t, **kwargs)
+
+    def add_panel_labels(
+        self,
+        labels: Optional[List[str]] = None,
+        loc: str = "upper left",
+        offset: Tuple[float, float] = (-0.1, 1.05),
+        fontsize: Optional[float] = None,
+        fontweight: str = "bold",
+        **kwargs,
+    ) -> List[Any]:
+        """Add panel labels (A, B, C, D, etc.) to multi-panel figures.
+
+        Parameters
+        ----------
+        labels : list of str, optional
+            Custom labels. If None, uses uppercase letters (A, B, C, ...).
+        loc : str
+            Location hint: 'upper left' (default), 'upper right', 'lower left', 'lower right'.
+        offset : tuple of float
+            (x, y) offset in axes coordinates from the corner.
+            Default is (-0.1, 1.05) for upper left positioning.
+        fontsize : float, optional
+            Font size in points. If None, uses style's title_pt or 10.
+        fontweight : str
+            Font weight (default: 'bold').
+        **kwargs
+            Additional arguments passed to ax.text().
+
+        Returns
+        -------
+        list of Text
+            The matplotlib Text objects created.
+
+        Examples
+        --------
+        >>> fig, axes = fr.subplots(2, 2)
+        >>> fig.add_panel_labels()  # Adds A, B, C, D
+        >>> fig.add_panel_labels(['i', 'ii', 'iii', 'iv'])  # Custom labels
+        >>> fig.add_panel_labels(loc='upper right', offset=(1.05, 1.05))
+        """
+        from ._panel_labels import add_panel_labels as _add_panel_labels
+
+        # Get fontsize from style if not specified
+        if fontsize is None:
+            fontsize = self._get_style_fontsize("title_pt", 10)
+
+        # Get theme text color (unless user provided 'color' in kwargs)
+        if "color" not in kwargs:
+            text_color = self._get_theme_text_color()
+        else:
+            text_color = kwargs.pop("color")
+
+        def record_callback(info):
+            self._recorder.figure_record.panel_labels = info
+
+        return _add_panel_labels(
+            all_axes=self.flat,
+            labels=labels,
+            loc=loc,
+            offset=offset,
+            fontsize=fontsize,
+            fontweight=fontweight,
+            text_color=text_color,
+            record_callback=record_callback,
+            **kwargs,
+        )
+
+    def set_title_metadata(self, title: str) -> "RecordingFigure":
+        """Set figure title metadata (not rendered, stored in recipe).
+
+        This is for storing a publication/reference title for the figure,
+        separate from suptitle which is rendered on the figure.
+
+        Parameters
+        ----------
+        title : str
+            The figure title for publication/reference.
+
+        Returns
+        -------
+        RecordingFigure
+            Self for method chaining.
+
+        Examples
+        --------
+        >>> fig, ax = fr.subplots()
+        >>> fig.set_title_metadata("Effect of temperature on reaction rate")
+        >>> fig.set_caption("Figure 1. Reaction rates measured at various temperatures.")
+        """
+        self._recorder.figure_record.title_metadata = title
+        return self
+
+    def set_caption(self, caption: str) -> "RecordingFigure":
+        """Set figure caption metadata (not rendered, stored in recipe).
+
+        This is for storing a publication caption for the figure,
+        typically used in scientific papers (e.g., "Fig. 1. Description...").
+
+        Parameters
+        ----------
+        caption : str
+            The figure caption text.
+
+        Returns
+        -------
+        RecordingFigure
+            Self for method chaining.
+
+        Examples
+        --------
+        >>> fig, ax = fr.subplots()
+        >>> fig.set_caption("Figure 1. Temperature dependence of reaction rates.")
+        """
+        self._recorder.figure_record.caption = caption
+        return self
+
+    @property
+    def title_metadata(self) -> Optional[str]:
+        """Get the figure title metadata."""
+        return self._recorder.figure_record.title_metadata
+
+    @property
+    def caption(self) -> Optional[str]:
+        """Get the figure caption metadata."""
+        return self._recorder.figure_record.caption
+
     def __getattr__(self, name: str) -> Any:
         """Delegate attribute access to underlying figure."""
         return getattr(self._fig, name)
@@ -88,6 +312,7 @@ class RecordingFigure:
         fname,
         save_recipe: bool = True,
         recipe_format: Literal["csv", "npz", "inline"] = "csv",
+        verbose: bool = True,
         **kwargs,
     ):
         """Save the figure image and optionally the recipe.
@@ -101,6 +326,8 @@ class RecordingFigure:
             Recipe will be saved with same name but .yaml extension.
         recipe_format : str
             Format for data in recipe: 'csv' (default), 'npz', or 'inline'.
+        verbose : bool
+            If True (default), print save status.
         **kwargs
             Passed to matplotlib's savefig().
 
@@ -117,8 +344,17 @@ class RecordingFigure:
         >>> fig.savefig('figure.png')  # Saves both figure.png and figure.yaml
         >>> fig.savefig('figure.png', save_recipe=False)  # Image only
         """
+        # Finalize ticks and special plots before saving
+        from ..styles._style_applier import finalize_special_plots, finalize_ticks
+        from ..styles._style_loader import get_current_style_dict
+
+        style_dict = get_current_style_dict()
+        for ax in self._fig.get_axes():
+            finalize_ticks(ax)
+            finalize_special_plots(ax, style_dict)
+
         # Handle file-like objects (BytesIO, etc.) - just pass through
-        if hasattr(fname, 'write'):
+        if hasattr(fname, "write"):
             self._fig.savefig(fname, **kwargs)
             return fname
 
@@ -128,8 +364,12 @@ class RecordingFigure:
         if save_recipe:
             recipe_path = fname.with_suffix(".yaml")
             self.save_recipe(recipe_path, include_data=True, data_format=recipe_format)
+            if verbose:
+                print(f"Saved: {fname} + {recipe_path}")
             return fname, recipe_path
 
+        if verbose:
+            print(f"Saved: {fname}")
         return fname
 
     def save_recipe(
@@ -155,15 +395,19 @@ class RecordingFigure:
             Path to saved recipe file.
         """
         from .._serializer import save_recipe
-        return save_recipe(self._recorder.figure_record, path, include_data, data_format)
+
+        return save_recipe(
+            self._recorder.figure_record, path, include_data, data_format
+        )
 
 
 def create_recording_subplots(
     nrows: int = 1,
     ncols: int = 1,
     recorder: Optional["Recorder"] = None,
+    panel_labels: bool = False,
     **kwargs,
-) -> Tuple[RecordingFigure, Union[RecordingAxes, List[RecordingAxes]]]:
+) -> Tuple[RecordingFigure, Union[RecordingAxes, NDArray]]:
     """Create a figure with recording-enabled axes.
 
     Parameters
@@ -174,6 +418,9 @@ def create_recording_subplots(
         Number of columns.
     recorder : Recorder, optional
         Recorder instance. Created if not provided.
+    panel_labels : bool
+        If True and figure has multiple panels, automatically add
+        panel labels (A, B, C, D, ...). Default is False.
     **kwargs
         Passed to plt.subplots().
 
@@ -181,8 +428,12 @@ def create_recording_subplots(
     -------
     fig : RecordingFigure
         Wrapped figure.
-    axes : RecordingAxes or list
-        Wrapped axes (single if 1x1, otherwise 2D array).
+    axes : RecordingAxes or ndarray
+        Wrapped axes (single if 1x1, otherwise numpy array matching matplotlib).
+
+    Examples
+    --------
+    >>> fig, axes = fr.subplots(2, 2, panel_labels=True)  # Auto-adds A, B, C, D
     """
     from .._recorder import Recorder
 
@@ -205,23 +456,31 @@ def create_recording_subplots(
         wrapped_fig = RecordingFigure(fig, recorder, wrapped_ax)
         return wrapped_fig, wrapped_ax
 
-    # Handle 1D or 2D arrays
-    import numpy as np
-    mpl_axes = np.atleast_2d(mpl_axes)
+    # Handle 1D or 2D arrays - reshape to (nrows, ncols) for uniform processing
+    mpl_axes_arr = np.asarray(mpl_axes)
+    if mpl_axes_arr.ndim == 1:
+        mpl_axes_arr = mpl_axes_arr.reshape(nrows, ncols)
 
     wrapped_axes = []
-    for i in range(mpl_axes.shape[0]):
+    for i in range(nrows):
         row = []
-        for j in range(mpl_axes.shape[1]):
-            row.append(RecordingAxes(mpl_axes[i, j], recorder, position=(i, j)))
+        for j in range(ncols):
+            row.append(RecordingAxes(mpl_axes_arr[i, j], recorder, position=(i, j)))
         wrapped_axes.append(row)
 
     wrapped_fig = RecordingFigure(fig, recorder, wrapped_axes)
 
-    # Return in same shape as matplotlib
+    # Add panel labels if requested (multi-panel figures only)
+    if panel_labels:
+        wrapped_fig.add_panel_labels()
+
+    # Return in same shape as matplotlib (numpy arrays for consistency)
     if nrows == 1:
-        return wrapped_fig, wrapped_axes[0]
+        # 1xN -> 1D array of shape (N,)
+        return wrapped_fig, np.array(wrapped_axes[0], dtype=object)
     elif ncols == 1:
-        return wrapped_fig, [row[0] for row in wrapped_axes]
+        # Nx1 -> 1D array of shape (N,)
+        return wrapped_fig, np.array([row[0] for row in wrapped_axes], dtype=object)
     else:
-        return wrapped_fig, wrapped_axes
+        # NxM -> 2D array
+        return wrapped_fig, np.array(wrapped_axes, dtype=object)

figrecipe/_wrappers/_panel_labels.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Panel label utilities for multi-panel figures."""
+
+import string
+from typing import TYPE_CHECKING, Any, List, Optional, Tuple
+
+if TYPE_CHECKING:
+    from ._axes import RecordingAxes
+
+
+def add_panel_labels(
+    all_axes: List["RecordingAxes"],
+    labels: Optional[List[str]],
+    loc: str,
+    offset: Tuple[float, float],
+    fontsize: float,
+    fontweight: str,
+    text_color: str,
+    record_callback: Any,
+    **kwargs,
+) -> List[Any]:
+    """Add panel labels (A, B, C, D, etc.) to axes.
+
+    Parameters
+    ----------
+    all_axes : list of RecordingAxes
+        Flattened list of all axes.
+    labels : list of str or None
+        Custom labels. If None, uses uppercase letters.
+    loc : str
+        Location hint: 'upper left', 'upper right', 'lower left', 'lower right'.
+    offset : tuple of float
+        (x, y) offset in axes coordinates.
+    fontsize : float
+        Font size in points.
+    fontweight : str
+        Font weight.
+    text_color : str
+        Text color.
+    record_callback : callable
+        Callback to record panel labels info.
+    **kwargs
+        Additional arguments passed to ax.text().
+
+    Returns
+    -------
+    list of Text
+        The matplotlib Text objects created.
+    """
+    n_axes = len(all_axes)
+
+    # Generate default labels if not provided
+    if labels is None:
+        labels = list(string.ascii_uppercase[:n_axes])
+    elif len(labels) < n_axes:
+        # Extend with letters if not enough labels provided
+        labels = list(labels) + list(string.ascii_uppercase[len(labels) : n_axes])
+
+    # Calculate position based on loc
+    x, y, ha, va = _calculate_position(loc, offset)
+
+    # Record panel labels
+    record_callback(
+        {
+            "labels": labels[:n_axes],
+            "loc": loc,
+            "offset": offset,
+            "fontsize": fontsize,
+            "fontweight": fontweight,
+            "color": text_color,
+            "kwargs": kwargs,
+        }
+    )
+
+    # Add labels to each axes
+    text_objects = []
+    for ax, label in zip(all_axes, labels[:n_axes]):
+        text = ax.ax.text(
+            x,
+            y,
+            label,
+            transform=ax.ax.transAxes,
+            fontsize=fontsize,
+            fontweight=fontweight,
+            color=text_color,
+            ha=ha,
+            va=va,
+            **kwargs,
+        )
+        text_objects.append(text)
+
+    return text_objects
+
+
+def _calculate_position(
+    loc: str, offset: Tuple[float, float]
+) -> Tuple[float, float, str, str]:
+    """Calculate text position and alignment based on location.
+
+    Returns
+    -------
+    tuple
+        (x, y, ha, va) where ha/va are horizontal/vertical alignment.
+    """
+    if loc == "upper left":
+        x, y = offset
+        ha, va = "right", "bottom"
+    elif loc == "upper right":
+        x, y = offset
+        ha, va = "left", "bottom"
+    elif loc == "lower left":
+        x, y = offset[0], -offset[1] + 1.0
+        ha, va = "right", "top"
+    elif loc == "lower right":
+        x, y = offset
+        ha, va = "left", "top"
+    else:
+        x, y = offset
+        ha, va = "right", "bottom"
+
+    return x, y, ha, va
+
+
+__all__ = ["add_panel_labels"]
+
+# EOF

figrecipe/_wrappers/_plot_helpers.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Helper functions for custom plot methods in RecordingAxes."""
+
+from typing import List, Tuple
+
+import numpy as np
+
+
+def get_colors_from_style(n_colors: int, explicit_colors=None) -> List:
+    """Get colors from style or matplotlib defaults.
+
+    Parameters
+    ----------
+    n_colors : int
+        Number of colors needed.
+    explicit_colors : list or color, optional
+        Explicitly provided colors.
+
+    Returns
+    -------
+    list
+        List of colors.
+    """
+    if explicit_colors is not None:
+        if isinstance(explicit_colors, list):
+            return explicit_colors
+        return [explicit_colors] * n_colors
+
+    from ..styles import get_style
+
+    style = get_style()
+    if style and "colors" in style and "palette" in style.colors:
+        palette = list(style.colors.palette)
+        colors = []
+        for c in palette:
+            if isinstance(c, (list, tuple)) and len(c) >= 3:
+                if all(v <= 1.0 for v in c):
+                    colors.append(tuple(c))
+                else:
+                    colors.append(tuple(v / 255.0 for v in c))
+            else:
+                colors.append(c)
+        return colors
+
+    # Matplotlib default color cycle
+    import matplotlib.pyplot as plt
+
+    return [c["color"] for c in plt.rcParams["axes.prop_cycle"]]
+
+
+def beeswarm_positions(
+    data: np.ndarray,
+    width: float,
+    rng: np.random.Generator,
+) -> np.ndarray:
+    """Calculate beeswarm-style x positions to minimize overlap.
+
+    This is a simplified beeswarm that uses binning and jittering.
+
+    Parameters
+    ----------
+    data : array
+        Y values of points.
+    width : float
+        Maximum jitter width.
+    rng : Generator
+        Random number generator.
+
+    Returns
+    -------
+    array
+        X offsets for each point.
+    """
+    n = len(data)
+    if n == 0:
+        return np.array([])
+
+    # Sort data and get order
+    order = np.argsort(data)
+    sorted_data = data[order]
+
+    # Group nearby points and offset them
+    x_offsets = np.zeros(n)
+
+    # Simple approach: bin by quantiles and spread within each bin
+    n_bins = max(1, int(np.sqrt(n)))
+    bin_edges = np.percentile(sorted_data, np.linspace(0, 100, n_bins + 1))
+
+    for i in range(n_bins):
+        mask = (sorted_data >= bin_edges[i]) & (sorted_data <= bin_edges[i + 1])
+        n_in_bin = mask.sum()
+        if n_in_bin > 0:
+            # Spread points evenly within bin width
+            offsets = np.linspace(-width / 2, width / 2, n_in_bin)
+            # Add small random noise
+            offsets += rng.uniform(-width * 0.1, width * 0.1, n_in_bin)
+            x_offsets[mask] = offsets
+
+    # Restore original order
+    result = np.zeros(n)
+    result[order] = x_offsets
+    return result
+
+
+def compute_joyplot_kdes(arrays: List[np.ndarray], x: np.ndarray) -> Tuple[List, float]:
+    """Compute KDEs for joyplot ridges.
+
+    Parameters
+    ----------
+    arrays : list
+        List of data arrays.
+    x : array
+        X values for KDE evaluation.
+
+    Returns
+    -------
+    tuple
+        (kdes, max_density)
+    """
+    from scipy import stats
+
+    kdes = []
+    max_density = 0
+    for arr in arrays:
+        arr = np.asarray(arr)
+        if len(arr) > 1:
+            kde = stats.gaussian_kde(arr)
+            density = kde(x)
+            kdes.append(density)
+            max_density = max(max_density, np.max(density))
+        else:
+            kdes.append(np.zeros_like(x))
+    return kdes, max_density
+
+
+__all__ = [
+    "get_colors_from_style",
+    "beeswarm_positions",
+    "compute_joyplot_kdes",
+]
+
+# EOF