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

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/_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/_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",
 ]

figrecipe/styles/_dotdict.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""DotDict class for nested dictionary access with dot notation."""
+
+from typing import Any
+
+
+class DotDict(dict):
+    """Dictionary with dot-notation access to nested keys.
+
+    Examples
+    --------
+    >>> d = DotDict({"axes": {"width_mm": 40}})
+    >>> d.axes.width_mm
+    40
+    """
+
+    def __getattr__(self, key: str) -> Any:
+        # Handle special methods first
+        if key == "to_subplots_kwargs":
+            from ._style_loader import to_subplots_kwargs
+
+            return lambda: to_subplots_kwargs(self)
+        try:
+            value = self[key]
+            if isinstance(value, dict) and not isinstance(value, DotDict):
+                value = DotDict(value)
+                self[key] = value
+            return value
+        except KeyError:
+            raise AttributeError(f"'{type(self).__name__}' has no attribute '{key}'")
+
+    def __setattr__(self, key: str, value: Any) -> None:
+        self[key] = value
+
+    def __delattr__(self, key: str) -> None:
+        try:
+            del self[key]
+        except KeyError:
+            raise AttributeError(key)
+
+    def __repr__(self) -> str:
+        return f"DotDict({super().__repr__()})"
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get value with default, supporting nested keys with dots."""
+        if "." in key:
+            parts = key.split(".")
+            value = self
+            for part in parts:
+                if isinstance(value, dict) and part in value:
+                    value = value[part]
+                else:
+                    return default
+            return value
+        return super().get(key, default)
+
+    def flatten(self, prefix: str = "") -> dict:
+        """Flatten nested dict to single level with underscore-joined keys."""
+        result = {}
+        for k, v in self.items():
+            new_key = f"{prefix}_{k}" if prefix else k
+            if isinstance(v, dict):
+                result.update(DotDict(v).flatten(new_key))
+            else:
+                result[new_key] = v
+        return result
+
+
+__all__ = ["DotDict"]
+
+# EOF