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

figrecipe/_wrappers/_caption_generator.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Caption generation utilities for scientific figures."""
+
+from typing import Any, Dict, List, Literal, Optional
+
+from ._stat_annotation import p_to_stars
+
+
+def format_stats_value(value: float, precision: int = 2) -> str:
+    """Format a statistical value for display."""
+    if abs(value) >= 1000 or (abs(value) < 0.01 and value != 0):
+        return f"{value:.{precision}e}"
+    return f"{value:.{precision}f}"
+
+
+def format_comparison(comp: Dict[str, Any], style: str = "publication") -> str:
+    """Format a single comparison result.
+
+    Parameters
+    ----------
+    comp : dict
+        Comparison dict with keys like: name, p_value, stars, effect_size, method.
+    style : str
+        "publication", "brief", or "detailed".
+
+    Returns
+    -------
+    str
+        Formatted comparison string.
+    """
+    name = comp.get("name", "comparison")
+    p_value = comp.get("p_value")
+    stars = comp.get("stars") or (p_to_stars(p_value) if p_value else "")
+    method = comp.get("method", "")
+    effect_size = comp.get("effect_size")
+
+    if style == "brief":
+        if p_value is not None:
+            return f"{name}: {stars}"
+        return name
+
+    elif style == "detailed":
+        parts = [name]
+        if method:
+            parts.append(f"({method})")
+        if p_value is not None:
+            if p_value < 0.001:
+                parts.append("p<0.001")
+            else:
+                parts.append(f"p={p_value:.3f}")
+        if effect_size:
+            if isinstance(effect_size, dict):
+                es_name = effect_size.get("name", "d")
+                es_val = effect_size.get("value", 0)
+                parts.append(f"{es_name}={es_val:.2f}")
+            else:
+                parts.append(f"d={effect_size:.2f}")
+        return " ".join(parts)
+
+    else:  # publication
+        if p_value is not None:
+            if p_value < 0.001:
+                p_str = "p<0.001"
+            else:
+                p_str = f"p={p_value:.3f}"
+            if effect_size:
+                if isinstance(effect_size, dict):
+                    es_val = effect_size.get("value", 0)
+                else:
+                    es_val = effect_size
+                return f"{name} ({p_str}, d={es_val:.2f})"
+            return f"{name} ({p_str})"
+        return name
+
+
+def format_panel_stats(stats: Dict[str, Any], style: str = "publication") -> str:
+    """Format panel-level statistics.
+
+    Parameters
+    ----------
+    stats : dict
+        Panel stats dict with keys like: n, mean, std, sem, group.
+    style : str
+        "publication", "brief", or "detailed".
+
+    Returns
+    -------
+    str
+        Formatted stats string.
+    """
+    parts = []
+
+    group = stats.get("group")
+    if group:
+        parts.append(group)
+
+    n = stats.get("n")
+    if n is not None:
+        parts.append(f"n={n}")
+
+    mean = stats.get("mean")
+    std = stats.get("std")
+    sem = stats.get("sem")
+
+    if mean is not None:
+        if std is not None:
+            parts.append(f"mean={format_stats_value(mean)}±{format_stats_value(std)}")
+        elif sem is not None:
+            parts.append(
+                f"mean={format_stats_value(mean)}±{format_stats_value(sem)} SEM"
+            )
+        else:
+            parts.append(f"mean={format_stats_value(mean)}")
+
+    return ", ".join(parts) if parts else ""
+
+
+def generate_figure_caption(
+    title: Optional[str] = None,
+    panel_captions: Optional[List[str]] = None,
+    stats: Optional[Dict[str, Any]] = None,
+    style: Literal["publication", "brief", "detailed"] = "publication",
+    template: Optional[str] = None,
+) -> str:
+    """Generate a figure caption from components.
+
+    Parameters
+    ----------
+    title : str, optional
+        Figure title.
+    panel_captions : list of str, optional
+        List of panel captions.
+    stats : dict, optional
+        Figure-level stats with comparisons.
+    style : str
+        Caption style.
+    template : str, optional
+        Custom template with placeholders: {title}, {panels}, {stats}.
+
+    Returns
+    -------
+    str
+        Generated caption.
+    """
+    # Build components
+    title_str = title or ""
+
+    # Panel descriptions
+    panels_str = ""
+    if panel_captions:
+        panels_str = " ".join(p for p in panel_captions if p)
+
+    # Stats summary
+    stats_str = ""
+    if stats:
+        comparisons = stats.get("comparisons", [])
+        if comparisons:
+            formatted = [format_comparison(c, style) for c in comparisons]
+            stats_str = "; ".join(formatted)
+
+    # Apply template
+    if template:
+        return template.format(
+            title=title_str,
+            panels=panels_str,
+            stats=stats_str,
+        ).strip()
+
+    # Default formatting based on style
+    parts = []
+    if title_str:
+        parts.append(title_str + ".")
+
+    if panels_str:
+        parts.append(panels_str)
+
+    if stats_str:
+        parts.append(stats_str + ".")
+
+    return " ".join(parts).strip()
+
+
+def generate_panel_caption(
+    label: Optional[str] = None,
+    stats: Optional[Dict[str, Any]] = None,
+    style: Literal["publication", "brief", "detailed"] = "publication",
+) -> str:
+    """Generate a panel caption from stats.
+
+    Parameters
+    ----------
+    label : str, optional
+        Panel label like "A" or "(A)".
+    stats : dict, optional
+        Panel-level stats.
+    style : str
+        Caption style.
+
+    Returns
+    -------
+    str
+        Generated panel caption.
+    """
+    parts = []
+
+    if label:
+        # Ensure label is in parentheses
+        if not label.startswith("("):
+            label = f"({label})"
+        parts.append(label)
+
+    if stats:
+        stats_str = format_panel_stats(stats, style)
+        if stats_str:
+            parts.append(stats_str)
+
+    return " ".join(parts)

figrecipe/_wrappers/_figure.py

@@ -3,7 +3,7 @@
 """Wrapped Figure that manages recording."""
 
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, List, Literal, Optional, Tuple, Union
+from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional, Tuple, Union
 
 import matplotlib.pyplot as plt
 import numpy as np
@@ -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,156 @@ 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 set_stats(self, stats: Dict[str, Any]) -> "RecordingFigure":
+        """Set figure-level statistics metadata (not rendered, stored in recipe).
+
+        Parameters
+        ----------
+        stats : dict
+            Statistics dictionary (comparisons, summary, correction_method, alpha).
+        """
+        self._recorder.figure_record.stats = stats
+        return self
+
+    @property
+    def stats(self) -> Optional[Dict[str, Any]]:
+        """Get the figure-level statistics metadata."""
+        return self._recorder.figure_record.stats
+
+    def generate_caption(self, style: str = "publication", template: str = None) -> str:
+        """Generate caption from stored stats. Styles: publication, brief, detailed."""
+        from ._caption_generator import generate_figure_caption
+
+        panels = [ax.caption for ax in self.flat if ax.caption]
+        return generate_figure_caption(
+            self.title_metadata, panels, self.stats, style, template
+        )
+
     def __getattr__(self, name: str) -> Any:
         """Delegate attribute access to underlying figure."""
         return getattr(self._fig, name)
@@ -203,6 +369,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 +430,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 +443,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 +455,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 +495,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