figrecipe 0.7.4__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
@@ -303,6 +303,31 @@ class RecordingFigure:
         """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)

figrecipe/_wrappers/_stat_annotation.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Statistical annotation drawing utilities for comparison brackets and stars."""
+
+from typing import Any, Dict, List, Literal, Optional
+
+from matplotlib.axes import Axes
+
+
+def get_theme_text_color(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 get_style_value(section: str, key: str, default: Any) -> Any:
+    """Get a value from loaded style settings.
+
+    Parameters
+    ----------
+    section : str
+        Style section (e.g., 'fonts', 'lines', 'stat_annotation')
+    key : str
+        Key within the section (e.g., 'annotation_pt', 'bracket_mm')
+    default : Any
+        Default value if not found
+    """
+    try:
+        from ..styles._style_loader import _STYLE_CACHE
+
+        if _STYLE_CACHE is not None:
+            section_obj = getattr(_STYLE_CACHE, section, None)
+            if section_obj is not None:
+                return getattr(section_obj, key, default)
+    except Exception:
+        pass
+    return default
+
+
+def p_to_stars(p_value: float, ns_symbol: bool = True) -> str:
+    """Convert p-value to significance stars.
+
+    Parameters
+    ----------
+    p_value : float
+        The p-value to convert.
+    ns_symbol : bool
+        If True, return "n.s." for non-significant. If False, return "".
+
+    Returns
+    -------
+    str
+        Stars representation: "***" (p<0.001), "**" (p<0.01),
+        "*" (p<0.05), "n.s." or "" (p>=0.05).
+    """
+    if p_value < 0.001:
+        return "***"
+    elif p_value < 0.01:
+        return "**"
+    elif p_value < 0.05:
+        return "*"
+    else:
+        return "n.s." if ns_symbol else ""
+
+
+def draw_stat_annotation(
+    ax: Axes,
+    x1: float,
+    x2: float,
+    y: Optional[float] = None,
+    text: Optional[str] = None,
+    p_value: Optional[float] = None,
+    style: Literal["stars", "p_value", "both", "bracket_only"] = "stars",
+    bracket_height: Optional[float] = None,
+    text_offset: Optional[float] = None,
+    color: Optional[str] = None,
+    linewidth: Optional[float] = None,
+    fontsize: Optional[float] = None,
+    fontweight: Optional[str] = None,
+    **kwargs,
+) -> List[Any]:
+    """Draw a statistical comparison bracket with annotation.
+
+    Parameters
+    ----------
+    ax : Axes
+        The matplotlib axes to draw on.
+    x1, x2 : float
+        X positions of the two groups being compared.
+    y : float, optional
+        Y position for the bracket. If None, auto-calculated from data.
+    text : str, optional
+        Custom text to display. Overrides p_value formatting.
+    p_value : float, optional
+        P-value for automatic star conversion.
+    style : str
+        Display style: "stars", "p_value", "both", "bracket_only".
+    bracket_height : float
+        Height of bracket tips as fraction of axes height.
+    text_offset : float
+        Offset of text above bracket as fraction of axes height.
+    color : str
+        Color for bracket and text.
+    linewidth : float
+        Line width for bracket.
+    fontsize : float
+        Font size for annotation text.
+    **kwargs
+        Additional kwargs passed to ax.text().
+
+    Returns
+    -------
+    list
+        List of matplotlib artists created (lines and text).
+    """
+    artists = []
+
+    from .._utils._units import mm_to_pt
+
+    # Resolve values from style if not explicitly provided
+    if color is None:
+        color = get_theme_text_color(default="black")
+    if bracket_height is None:
+        bracket_height = get_style_value("stat_annotation", "bracket_height", 0.03)
+    if text_offset is None:
+        text_offset = get_style_value("stat_annotation", "text_offset", 0.01)
+    if linewidth is None:
+        # Read mm value and convert to points
+        linewidth_mm = get_style_value("stat_annotation", "linewidth_mm", 0.2)
+        linewidth = mm_to_pt(linewidth_mm)
+
+    # Font settings from style: both stars and p-values use same fontsize_pt
+    # Stars are bold, p-values are normal weight
+    annotation_fontsize = get_style_value("stat_annotation", "fontsize_pt", 6)
+    stars_fontweight = get_style_value("stat_annotation", "stars_fontweight", "bold")
+
+    # Get axes limits for relative positioning
+    ylim = ax.get_ylim()
+    y_range = ylim[1] - ylim[0]
+
+    # Auto-calculate y position if not provided
+    if y is None:
+        # Find max y value in the x range and add padding
+        y = ylim[1] + y_range * 0.05
+
+    # Calculate bracket dimensions in data coordinates
+    tip_height = y_range * bracket_height
+    text_y_offset = y_range * text_offset
+
+    # Draw bracket: horizontal line with vertical tips
+    # Left tip
+    line1 = ax.plot(
+        [x1, x1], [y - tip_height, y], color=color, linewidth=linewidth, clip_on=False
+    )[0]
+    artists.append(line1)
+
+    # Horizontal bar
+    line2 = ax.plot([x1, x2], [y, y], color=color, linewidth=linewidth, clip_on=False)[
+        0
+    ]
+    artists.append(line2)
+
+    # Right tip
+    line3 = ax.plot(
+        [x2, x2], [y, y - tip_height], color=color, linewidth=linewidth, clip_on=False
+    )[0]
+    artists.append(line3)
+
+    # Determine annotation text and whether it's stars-only
+    is_stars_only = False
+    if text is None and style != "bracket_only":
+        if p_value is not None:
+            if style == "stars":
+                text = p_to_stars(p_value)
+                # Only bold for actual stars, not for n.s.
+                is_stars_only = text not in ("n.s.", "")
+            elif style == "p_value":
+                # Use italic p with spaces around operators
+                if p_value < 0.001:
+                    text = r"$\it{p}$ < 0.001"
+                else:
+                    text = rf"$\it{{p}}$ = {p_value:.3f}"
+            elif style == "both":
+                stars = p_to_stars(p_value)
+                # Use italic p with spaces around operators
+                if p_value < 0.001:
+                    text = rf"{stars} ($\it{{p}}$ < 0.001)"
+                else:
+                    text = rf"{stars} ($\it{{p}}$ = {p_value:.3f})"
+
+    # Draw text if available
+    if text and style != "bracket_only":
+        text_x = (x1 + x2) / 2
+        text_y = y + text_y_offset
+
+        # Use same fontsize for stars and p-values, but stars are bold
+        effective_fontsize = fontsize if fontsize is not None else annotation_fontsize
+        if is_stars_only:
+            effective_fontweight = (
+                fontweight if fontweight is not None else stars_fontweight
+            )
+        else:
+            effective_fontweight = fontweight if fontweight is not None else "normal"
+
+        text_kwargs = {
+            "ha": "center",
+            "va": "bottom",
+            "fontsize": effective_fontsize,
+            "fontweight": effective_fontweight,
+            "color": color,
+        }
+        text_kwargs.update(kwargs)
+        txt = ax.text(text_x, text_y, text, **text_kwargs)
+        artists.append(txt)
+
+    return artists
+
+
+def calculate_auto_y(
+    ax: Axes,
+    x1: float,
+    x2: float,
+    existing_annotations: List[Dict[str, Any]],
+    padding: float = 0.05,
+) -> float:
+    """Calculate automatic y position for a new annotation.
+
+    Avoids overlapping with existing annotations by stacking.
+
+    Parameters
+    ----------
+    ax : Axes
+        The matplotlib axes.
+    x1, x2 : float
+        X positions of the comparison.
+    existing_annotations : list
+        List of existing annotation info dicts with x1, x2, y keys.
+    padding : float
+        Padding as fraction of y range.
+
+    Returns
+    -------
+    float
+        Suggested y position for the new annotation.
+    """
+    ylim = ax.get_ylim()
+    y_range = ylim[1] - ylim[0]
+    pad = y_range * padding
+
+    # Start above the data
+    y = ylim[1] + pad
+
+    # Check for overlaps with existing annotations
+    for ann in existing_annotations:
+        ann_x1, ann_x2 = ann.get("x1", 0), ann.get("x2", 0)
+        ann_y = ann.get("y", 0)
+
+        # Check if x ranges overlap
+        if not (x2 < ann_x1 or x1 > ann_x2):
+            # Overlapping x range, need to stack
+            y = max(y, ann_y + pad * 2)
+
+    return y

figrecipe/styles/_style_applier.py

@@ -85,7 +85,11 @@ def apply_style_mm(ax: Axes, style: Dict[str, Any]) -> float:
     import matplotlib as mpl
 
     # Apply theme colors (dark/light mode)
-    theme = style.get("theme", "light")
+    theme_section = style.get("theme", {})
+    if isinstance(theme_section, dict):
+        theme = theme_section.get("mode", "light")
+    else:
+        theme = str(theme_section) if theme_section else "light"
     theme_colors = style.get("theme_colors", None)
     apply_theme_colors(ax, theme, theme_colors)
 
@@ -171,7 +175,11 @@ def apply_style_mm(ax: Axes, style: Dict[str, Any]) -> float:
     mpl.rcParams["legend.title_fontsize"] = legend_fs
 
     # Set legend colors from theme
-    theme = style.get("theme", "light")
+    theme_section = style.get("theme", {})
+    if isinstance(theme_section, dict):
+        theme = theme_section.get("mode", "light")
+    else:
+        theme = str(theme_section) if theme_section else "light"
     theme_colors = style.get("theme_colors", None)
     if theme_colors:
         legend_bg = theme_colors.get("legend_bg", theme_colors.get("axes_bg", "white"))

figrecipe/styles/presets/SCITEX.yaml

@@ -11,10 +11,10 @@ axes:
   thickness_mm: 0.2
 
 margins:
-  left_mm: 6      # Room for supylabel
+  left_mm: 1      # Minimal - constrained_layout handles labels
   right_mm: 1
-  bottom_mm: 5    # Room for supxlabel
-  top_mm: 5       # Room for suptitle
+  bottom_mm: 1    # Minimal - constrained_layout handles labels
+  top_mm: 1       # Minimal - constrained_layout handles labels
 
 spacing:
   horizontal_mm: 10   # Between columns
@@ -112,6 +112,13 @@ legend:
   alpha: 1.0             # Transparency
   loc: "best"
 
+stat_annotation:
+  bracket_height: 0.03   # Height of bracket tips as fraction of y-range
+  text_offset: 0.01      # Text offset above bracket as fraction of y-range
+  linewidth_mm: 0.2      # Bracket line width in mm
+  fontsize_pt: 6         # Font size for annotation text (stars and p-values)
+  stars_fontweight: "bold"  # Font weight for stars
+
 output:
   dpi: 300
   transparent: true
@@ -122,7 +129,7 @@ behavior:
   hide_top_spine: true
   hide_right_spine: true
   grid: false
-  constrained_layout: true  # Auto-spacing for suptitle/supxlabel/supylabel
+  constrained_layout: true  # Auto-fits content; spacing controls disabled
   panel_labels: true        # Auto-add A, B, C labels to multi-panel figures
 
 theme: