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

figrecipe/_wrappers/_figure.py

@@ -93,6 +93,22 @@ class RecordingFigure:
             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.
 
@@ -162,6 +178,131 @@ class RecordingFigure:
         # 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)
@@ -203,6 +344,15 @@ 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"):
             self._fig.savefig(fname, **kwargs)
@@ -255,6 +405,7 @@ def create_recording_subplots(
     nrows: int = 1,
     ncols: int = 1,
     recorder: Optional["Recorder"] = None,
+    panel_labels: bool = False,
     **kwargs,
 ) -> Tuple[RecordingFigure, Union[RecordingAxes, NDArray]]:
     """Create a figure with recording-enabled axes.
@@ -267,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().
 
@@ -276,6 +430,10 @@ def create_recording_subplots(
         Wrapped figure.
     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
 
@@ -312,6 +470,10 @@ def create_recording_subplots(
 
     wrapped_fig = RecordingFigure(fig, recorder, wrapped_axes)
 
+    # 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:
         # 1xN -> 1D array of shape (N,)

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

figrecipe/_wrappers/_violin_helpers.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Violin plot helper functions for RecordingAxes."""
+
+from typing import Any, Dict, List
+
+import numpy as np
+
+
+def add_violin_inner_box(
+    ax,
+    dataset: List,
+    positions: List,
+    style: Dict[str, Any],
+) -> None:
+    """Add box plot inside violin.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        The axes to draw on.
+    dataset : array-like
+        Data arrays for each violin.
+    positions : array-like
+        X positions of violins.
+    style : dict
+        Violin style configuration.
+    """
+    from ..styles._style_applier import mm_to_pt
+
+    whisker_lw = mm_to_pt(style.get("whisker_mm", 0.2))
+    median_size = mm_to_pt(style.get("median_mm", 0.8))
+
+    for data, pos in zip(dataset, positions):
+        data = np.asarray(data)
+        q1, median, q3 = np.percentile(data, [25, 50, 75])
+        iqr = q3 - q1
+        whisker_low = max(data.min(), q1 - 1.5 * iqr)
+        whisker_high = min(data.max(), q3 + 1.5 * iqr)
+
+        # Draw box (Q1 to Q3)
+        ax.vlines(pos, q1, q3, colors="black", linewidths=whisker_lw, zorder=3)
+        # Draw whiskers
+        ax.vlines(
+            pos,
+            whisker_low,
+            q1,
+            colors="black",
+            linewidths=whisker_lw * 0.5,
+            zorder=3,
+        )
+        ax.vlines(
+            pos,
+            q3,
+            whisker_high,
+            colors="black",
+            linewidths=whisker_lw * 0.5,
+            zorder=3,
+        )
+        # Draw median as a white dot with black edge
+        ax.scatter(
+            [pos],
+            [median],
+            s=median_size**2,
+            c="white",
+            edgecolors="black",
+            linewidths=whisker_lw,
+            zorder=4,
+        )
+
+
+def add_violin_inner_swarm(
+    ax,
+    dataset: List,
+    positions: List,
+    style: Dict[str, Any],
+) -> None:
+    """Add swarm points inside violin.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        The axes to draw on.
+    dataset : array-like
+        Data arrays for each violin.
+    positions : array-like
+        X positions of violins.
+    style : dict
+        Violin style configuration.
+    """
+    from ..styles._style_applier import mm_to_pt
+
+    point_size = mm_to_pt(style.get("median_mm", 0.8))
+
+    for data, pos in zip(dataset, positions):
+        data = np.asarray(data)
+        n = len(data)
+
+        # Simple swarm: jitter x positions
+        jitter = np.random.default_rng(42).uniform(-0.15, 0.15, n)
+        x_positions = pos + jitter
+
+        ax.scatter(x_positions, data, s=point_size**2, c="black", alpha=0.5, zorder=3)
+
+
+def add_violin_inner_stick(
+    ax,
+    dataset: List,
+    positions: List,
+    style: Dict[str, Any],
+) -> None:
+    """Add stick (line) markers inside violin for each data point.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        The axes to draw on.
+    dataset : array-like
+        Data arrays for each violin.
+    positions : array-like
+        X positions of violins.
+    style : dict
+        Violin style configuration.
+    """
+    from ..styles._style_applier import mm_to_pt
+
+    lw = mm_to_pt(style.get("whisker_mm", 0.2))
+
+    for data, pos in zip(dataset, positions):
+        data = np.asarray(data)
+        # Draw short horizontal lines at each data point
+        for val in data:
+            ax.hlines(
+                val,
+                pos - 0.05,
+                pos + 0.05,
+                colors="black",
+                linewidths=lw * 0.5,
+                alpha=0.3,
+                zorder=3,
+            )
+
+
+def add_violin_inner_point(
+    ax,
+    dataset: List,
+    positions: List,
+    style: Dict[str, Any],
+) -> None:
+    """Add point markers inside violin for each data point.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        The axes to draw on.
+    dataset : array-like
+        Data arrays for each violin.
+    positions : array-like
+        X positions of violins.
+    style : dict
+        Violin style configuration.
+    """
+    from ..styles._style_applier import mm_to_pt
+
+    point_size = mm_to_pt(style.get("median_mm", 0.8)) * 0.5
+
+    for data, pos in zip(dataset, positions):
+        data = np.asarray(data)
+        x_positions = np.full_like(data, pos)
+        ax.scatter(x_positions, data, s=point_size**2, c="black", alpha=0.3, zorder=3)
+
+
+__all__ = [
+    "add_violin_inner_box",
+    "add_violin_inner_swarm",
+    "add_violin_inner_stick",
+    "add_violin_inner_point",
+]
+
+# EOF

figrecipe/styles/__init__.py

@@ -18,12 +18,10 @@ Usage:
     fig, ax = ps.subplots(**style.to_subplots_kwargs())
 """
 
-from ._style_applier import (
-    apply_style_mm,
-    apply_theme_colors,
-    check_font,
-    list_available_fonts,
-)
+from ._dotdict import DotDict
+from ._finalize import finalize_special_plots, finalize_ticks
+from ._fonts import check_font, list_available_fonts
+from ._style_applier import apply_style_mm
 from ._style_loader import (
     STYLE,
     get_style,
@@ -33,8 +31,10 @@ from ._style_loader import (
     to_subplots_kwargs,
     unload_style,
 )
+from ._themes import apply_theme_colors
 
 __all__ = [
+    "DotDict",
     "load_style",
     "unload_style",
     "get_style",
@@ -46,4 +46,6 @@ __all__ = [
     "apply_theme_colors",
     "check_font",
     "list_available_fonts",
+    "finalize_ticks",
+    "finalize_special_plots",
 ]