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

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/plt.py

@@ -9,4 +9,3 @@ Usage:
 """
 
 from .pyplot import *  # noqa: F401, F403
-from .pyplot import __all__

figrecipe/pyplot.py

@@ -34,9 +34,10 @@ Examples
 import matplotlib.pyplot as _plt
 from matplotlib.pyplot import *  # noqa: F401, F403
 
+from . import save as _ps_save
+
 # Import figrecipe functionality
 from . import subplots as _ps_subplots
-from . import save as _ps_save
 from ._wrappers import RecordingFigure
 
 # Override subplots with recording-enabled version

figrecipe/styles/__init__.py

@@ -18,24 +18,23 @@ Usage:
     fig, ax = ps.subplots(**style.to_subplots_kwargs())
 """
 
+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 (
-    load_style,
-    unload_style,
+    STYLE,
     get_style,
-    reload_style,
     list_presets,
-    STYLE,
+    load_style,
+    reload_style,
     to_subplots_kwargs,
+    unload_style,
 )
-
-from ._style_applier import (
-    apply_style_mm,
-    apply_theme_colors,
-    check_font,
-    list_available_fonts,
-)
+from ._themes import apply_theme_colors
 
 __all__ = [
+    "DotDict",
     "load_style",
     "unload_style",
     "get_style",
@@ -47,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

figrecipe/styles/_finalize.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Finalization utilities for figrecipe styles."""
+
+from typing import Any, Dict
+
+from matplotlib.axes import Axes
+
+from ._fonts import check_font
+
+
+def finalize_ticks(ax: Axes) -> None:
+    """
+    Apply deferred tick configuration after all plotting is done.
+
+    This function applies the n_ticks setting stored by apply_style_mm(),
+    but only to numeric axes (not categorical). Skips pie charts and other
+    plot types that should have hidden axes.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        The axes to finalize.
+    """
+    from matplotlib.patches import Wedge
+    from matplotlib.ticker import MaxNLocator
+
+    # Skip pie charts - they should have no ticks
+    has_pie = any(isinstance(p, Wedge) for p in ax.patches)
+    if has_pie:
+        return
+
+    # Get tick count preferences (new format: min/max)
+    n_ticks_min = getattr(ax, "_figrecipe_n_ticks_min", None)
+    n_ticks_max = getattr(ax, "_figrecipe_n_ticks_max", None)
+
+    if n_ticks_min is None and n_ticks_max is None:
+        return
+
+    # Default values - minimum 3 ticks required
+    n_ticks_min = max(3, n_ticks_min or 3)
+    n_ticks_max = max(n_ticks_min, n_ticks_max or 4)
+
+    nbins = n_ticks_max
+
+    def _is_numeric_label(lbl: str) -> bool:
+        """Check if a tick label represents a numeric value."""
+        if not lbl:
+            return True
+        stripped = lbl.replace(".", "").replace("-", "").replace("+", "")
+        stripped = stripped.replace("−", "")  # Unicode minus sign
+        stripped = stripped.replace("e", "").replace("E", "")
+        return stripped.isdigit() or stripped == ""
+
+    # Check if x-axis is categorical
+    x_labels = [t.get_text() for t in ax.get_xticklabels()]
+    x_is_categorical = any(not _is_numeric_label(lbl) for lbl in x_labels)
+    if not x_is_categorical:
+        ax.xaxis.set_major_locator(MaxNLocator(nbins=nbins, min_n_ticks=n_ticks_min))
+
+    # Check if y-axis is categorical
+    y_labels = [t.get_text() for t in ax.get_yticklabels()]
+    y_is_categorical = any(not _is_numeric_label(lbl) for lbl in y_labels)
+    if not y_is_categorical:
+        ax.yaxis.set_major_locator(MaxNLocator(nbins=nbins, min_n_ticks=n_ticks_min))
+
+
+def finalize_special_plots(ax: Axes, style: Dict[str, Any] = None) -> None:
+    """
+    Finalize axes visibility for special plot types (pie, imshow, etc.).
+
+    This should be called after all plotting is done, before saving.
+    It handles plot types that need axes/ticks hidden.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        The axes to finalize.
+    style : dict, optional
+        Style dictionary. If None, uses defaults.
+    """
+    from matplotlib.image import AxesImage
+    from matplotlib.patches import Wedge
+
+    if style is None:
+        style = {}
+
+    # Check for pie chart
+    has_pie = any(isinstance(p, Wedge) for p in ax.patches)
+    if has_pie:
+        show_axes = style.get("pie_show_axes", False)
+        text_pt = style.get("pie_text_pt", 6)
+        font_family = check_font(style.get("font_family", "Arial"))
+
+        for text in ax.texts:
+            transform = text.get_transform()
+            if transform == ax.transAxes:
+                x, y = text.get_position()
+                if y > 1.0 or y < 0.0:
+                    continue
+            text.set_fontsize(text_pt)
+            text.set_fontfamily(font_family)
+
+        if not show_axes:
+            ax.set_xticks([])
+            ax.set_yticks([])
+            ax.set_xticklabels([])
+            ax.set_yticklabels([])
+            ax.set_xlabel("")
+            ax.set_ylabel("")
+            for spine in ax.spines.values():
+                spine.set_visible(False)
+
+    # Check for imshow/matshow (has AxesImage)
+    has_image = any(isinstance(c, AxesImage) for c in ax.get_children())
+    if has_image:
+        xlabel = ax.get_xlabel()
+        ylabel = ax.get_ylabel()
+        is_specgram = xlabel or ylabel
+
+        if not is_specgram:
+            show_axes = style.get("imshow_show_axes", False)
+            if not show_axes:
+                ax.set_xticks([])
+                ax.set_yticks([])
+                ax.set_xticklabels([])
+                ax.set_yticklabels([])
+                for spine in ax.spines.values():
+                    spine.set_visible(False)
+
+
+__all__ = ["finalize_ticks", "finalize_special_plots"]
+
+# EOF

figrecipe/styles/_fonts.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Font utilities for figrecipe.
+
+Provides font availability checking and listing for publication-quality figures.
+"""
+
+__all__ = [
+    "list_available_fonts",
+    "check_font",
+]
+
+import warnings
+from typing import List
+
+
+def list_available_fonts() -> List[str]:
+    """List all available font families.
+
+    Returns
+    -------
+    list of str
+        Sorted list of available font family names.
+
+    Examples
+    --------
+    >>> fonts = ps.list_available_fonts()
+    >>> print(fonts[:5])
+    ['Arial', 'Courier New', 'DejaVu Sans', ...]
+    """
+    import matplotlib.font_manager as fm
+
+    fonts = set()
+    for font in fm.fontManager.ttflist:
+        fonts.add(font.name)
+    return sorted(fonts)
+
+
+def check_font(font_family: str, fallback: str = "DejaVu Sans") -> str:
+    """Check if font is available, with fallback and helpful error message.
+
+    Parameters
+    ----------
+    font_family : str
+        Requested font family name.
+    fallback : str
+        Fallback font if requested font is not available.
+
+    Returns
+    -------
+    str
+        The font to use (original if available, fallback otherwise).
+
+    Examples
+    --------
+    >>> font = check_font("Arial")  # Returns "Arial" if available
+    >>> font = check_font("NonExistentFont")  # Returns fallback with warning
+    """
+
+    available = list_available_fonts()
+
+    if font_family in available:
+        return font_family
+
+    # Font not found - show helpful message
+    similar = [f for f in available if font_family.lower() in f.lower()]
+
+    msg = f"Font '{font_family}' not found.\n"
+    if similar:
+        msg += f"  Similar fonts available: {similar[:5]}\n"
+    msg += f"  Using fallback: '{fallback}'\n"
+    msg += "  To see all available fonts: ps.list_available_fonts()\n"
+    msg += "  To install Arial on Linux: sudo apt install ttf-mscorefonts-installer"
+
+    warnings.warn(msg, UserWarning)
+
+    return fallback if fallback in available else "DejaVu Sans"