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

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"

figrecipe/styles/_kwargs_converter.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Convert style DotDict to subplots kwargs."""
+
+from typing import TYPE_CHECKING, Any, Dict, Optional
+
+if TYPE_CHECKING:
+    from ._dotdict import DotDict
+
+
+def to_subplots_kwargs(style: Optional["DotDict"] = None) -> Dict[str, Any]:
+    """Convert style DotDict to kwargs for ps.subplots().
+
+    Uses YAML-compatible flattened key names as the single source of truth.
+    For example, YAML `fonts.axis_label_pt` becomes `fonts_axis_label_pt`.
+
+    Parameters
+    ----------
+    style : DotDict, optional
+        Style configuration. If None, uses current loaded style.
+
+    Returns
+    -------
+    dict
+        Keyword arguments for ps.subplots() with YAML-compatible flattened keys.
+
+    Examples
+    --------
+    >>> style = load_style()
+    >>> kwargs = to_subplots_kwargs(style)
+    >>> fig, ax = ps.subplots(**kwargs)
+    """
+    if style is None:
+        from ._style_loader import get_style
+
+        style = get_style()
+
+    # YAML-compatible flattened keys (single source of truth)
+    result = {
+        # Axes (axes.* in YAML)
+        "axes_width_mm": style.axes.width_mm,
+        "axes_height_mm": style.axes.height_mm,
+        "axes_thickness_mm": style.axes.thickness_mm,
+        # Margins (margins.* in YAML)
+        "margins_left_mm": style.margins.left_mm,
+        "margins_right_mm": style.margins.right_mm,
+        "margins_bottom_mm": style.margins.bottom_mm,
+        "margins_top_mm": style.margins.top_mm,
+        # Spacing (spacing.* in YAML)
+        "spacing_horizontal_mm": style.spacing.horizontal_mm,
+        "spacing_vertical_mm": style.spacing.vertical_mm,
+        # Ticks (ticks.* in YAML)
+        "ticks_length_mm": style.ticks.length_mm,
+        "ticks_thickness_mm": style.ticks.thickness_mm,
+        "ticks_direction": style.ticks.get("direction", "out"),
+        "ticks_n_ticks_min": style.ticks.get("n_ticks_min", 3),
+        "ticks_n_ticks_max": style.ticks.get("n_ticks_max", 4),
+        # Lines (lines.* in YAML)
+        "lines_trace_mm": style.lines.trace_mm,
+        "lines_errorbar_mm": style.lines.get("errorbar_mm", 0.2),
+        "lines_errorbar_cap_mm": style.lines.get("errorbar_cap_mm", 0.8),
+        # Markers (markers.* in YAML)
+        "markers_size_mm": style.markers.size_mm,
+        "markers_scatter_mm": style.markers.get("scatter_mm", style.markers.size_mm),
+        "markers_flier_mm": style.markers.get("flier_mm", style.markers.size_mm),
+        "markers_edge_width_mm": style.markers.get("edge_width_mm"),
+        # Boxplot (boxplot.* in YAML)
+        "boxplot_line_mm": style.get("boxplot", {}).get("line_mm", 0.2),
+        "boxplot_whisker_mm": style.get("boxplot", {}).get("whisker_mm", 0.2),
+        "boxplot_cap_mm": style.get("boxplot", {}).get("cap_mm", 0.2),
+        "boxplot_median_mm": style.get("boxplot", {}).get("median_mm", 0.2),
+        "boxplot_median_color": style.get("boxplot", {}).get("median_color", "black"),
+        "boxplot_flier_edge_mm": style.get("boxplot", {}).get("flier_edge_mm", 0.2),
+        # Violinplot (violinplot.* in YAML)
+        "violinplot_line_mm": style.get("violinplot", {}).get("line_mm", 0.2),
+        "violinplot_inner": style.get("violinplot", {}).get("inner", "box"),
+        "violinplot_box_width_mm": style.get("violinplot", {}).get("box_width_mm", 1.5),
+        "violinplot_whisker_mm": style.get("violinplot", {}).get("whisker_mm", 0.2),
+        "violinplot_median_mm": style.get("violinplot", {}).get("median_mm", 0.8),
+        # Barplot (barplot.* in YAML)
+        "barplot_edge_mm": style.get("barplot", {}).get("edge_mm", 0.2),
+        # Histogram (histogram.* in YAML)
+        "histogram_edge_mm": style.get("histogram", {}).get("edge_mm", 0.2),
+        # Pie chart (pie.* in YAML)
+        "pie_text_pt": style.get("pie", {}).get("text_pt", 6),
+        "pie_show_axes": style.get("pie", {}).get("show_axes", False),
+        # Imshow (imshow.* in YAML)
+        "imshow_show_axes": style.get("imshow", {}).get("show_axes", False),
+        "imshow_show_labels": style.get("imshow", {}).get("show_labels", False),
+        # Fonts (fonts.* in YAML)
+        "fonts_family": style.fonts.family,
+        "fonts_axis_label_pt": style.fonts.axis_label_pt,
+        "fonts_tick_label_pt": style.fonts.tick_label_pt,
+        "fonts_title_pt": style.fonts.title_pt,
+        "fonts_suptitle_pt": style.fonts.suptitle_pt,
+        "fonts_legend_pt": style.fonts.legend_pt,
+        "fonts_annotation_pt": style.fonts.get("annotation_pt", 6),
+        # Padding (padding.* in YAML)
+        "padding_label_pt": style.padding.label_pt,
+        "padding_tick_pt": style.padding.tick_pt,
+        "padding_title_pt": style.padding.title_pt,
+        # Output (output.* in YAML)
+        "output_dpi": style.output.dpi,
+        "output_transparent": style.output.get("transparent", True),
+        "output_format": style.output.get("format", "pdf"),
+        # Theme (theme.* in YAML)
+        "theme_mode": style.theme.mode,
+    }
+
+    # Add theme colors from preset if available
+    theme_mode = style.theme.mode
+    if "theme" in style and theme_mode in style.theme:
+        result["theme_colors"] = dict(style.theme[theme_mode])
+
+    # Add color palette if available
+    if "colors" in style and "palette" in style.colors:
+        result["color_palette"] = list(style.colors.palette)
+
+    # Add behavior settings (behavior.* in YAML)
+    if "behavior" in style:
+        behavior = style.behavior
+        if hasattr(behavior, "hide_top_spine"):
+            result["behavior_hide_top_spine"] = behavior.hide_top_spine
+        if hasattr(behavior, "hide_right_spine"):
+            result["behavior_hide_right_spine"] = behavior.hide_right_spine
+        if hasattr(behavior, "grid"):
+            result["behavior_grid"] = behavior.grid
+        if hasattr(behavior, "auto_scale_axes"):
+            result["behavior_auto_scale_axes"] = behavior.auto_scale_axes
+        if hasattr(behavior, "constrained_layout"):
+            result["behavior_constrained_layout"] = behavior.constrained_layout
+
+    # Legacy key aliases for backwards compatibility
+    result.update(_get_legacy_aliases(result))
+
+    return result
+
+
+def _get_legacy_aliases(result: Dict[str, Any]) -> Dict[str, Any]:
+    """Get legacy key aliases for backwards compatibility.
+
+    These allow existing code using old keys to still work.
+    """
+    return {
+        "margin_left_mm": result["margins_left_mm"],
+        "margin_right_mm": result["margins_right_mm"],
+        "margin_bottom_mm": result["margins_bottom_mm"],
+        "margin_top_mm": result["margins_top_mm"],
+        "space_w_mm": result["spacing_horizontal_mm"],
+        "space_h_mm": result["spacing_vertical_mm"],
+        "tick_length_mm": result["ticks_length_mm"],
+        "tick_thickness_mm": result["ticks_thickness_mm"],
+        "n_ticks_min": result["ticks_n_ticks_min"],
+        "n_ticks_max": result["ticks_n_ticks_max"],
+        "trace_thickness_mm": result["lines_trace_mm"],
+        "marker_size_mm": result["markers_size_mm"],
+        "font_family": result["fonts_family"],
+        "axis_font_size_pt": result["fonts_axis_label_pt"],
+        "tick_font_size_pt": result["fonts_tick_label_pt"],
+        "title_font_size_pt": result["fonts_title_pt"],
+        "suptitle_font_size_pt": result["fonts_suptitle_pt"],
+        "legend_font_size_pt": result["fonts_legend_pt"],
+        "label_pad_pt": result["padding_label_pt"],
+        "tick_pad_pt": result["padding_tick_pt"],
+        "title_pad_pt": result["padding_title_pt"],
+        "dpi": result["output_dpi"],
+        "theme": result["theme_mode"],
+        "hide_top_spine": result.get("behavior_hide_top_spine", True),
+        "hide_right_spine": result.get("behavior_hide_right_spine", True),
+        "grid": result.get("behavior_grid", False),
+        "auto_scale_axes": result.get("behavior_auto_scale_axes", True),
+        "constrained_layout": result.get("behavior_constrained_layout", False),
+    }
+
+
+__all__ = ["to_subplots_kwargs"]
+
+# EOF

figrecipe/styles/_plot_styles.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Plot-specific style application for figrecipe."""
+
+from typing import Any, Dict
+
+from matplotlib.axes import Axes
+
+from .._utils._units import mm_to_pt
+from ._fonts import check_font
+
+
+def apply_boxplot_style(ax: Axes, style: Dict[str, Any]) -> None:
+    """Apply boxplot line width styling to existing boxplot elements.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        Target axes containing boxplot elements.
+    style : dict
+        Style dictionary with boxplot_* keys.
+    """
+    from matplotlib.lines import Line2D
+    from matplotlib.patches import PathPatch
+
+    box_lw = mm_to_pt(style.get("boxplot_line_mm", 0.2))
+    whisker_lw = mm_to_pt(style.get("boxplot_whisker_mm", 0.2))
+    cap_lw = mm_to_pt(style.get("boxplot_cap_mm", 0.2))
+    median_lw = mm_to_pt(style.get("boxplot_median_mm", 0.2))
+    median_color = style.get("boxplot_median_color", "black")
+    flier_edge_lw = mm_to_pt(style.get("boxplot_flier_edge_mm", 0.2))
+
+    for child in ax.get_children():
+        if isinstance(child, PathPatch):
+            if child.get_edgecolor() is not None:
+                child.set_linewidth(box_lw)
+
+        elif isinstance(child, Line2D):
+            xdata = child.get_xdata()
+            ydata = child.get_ydata()
+
+            marker = child.get_marker()
+            linestyle = child.get_linestyle()
+            if marker and marker != "None" and linestyle in ("None", "", " "):
+                child.set_markeredgewidth(flier_edge_lw)
+            elif len(xdata) == 2 and len(ydata) == 2:
+                if ydata[0] == ydata[1]:
+                    if linestyle == "-":
+                        child.set_linewidth(median_lw)
+                        if median_color:
+                            child.set_color(median_color)
+                    else:
+                        child.set_linewidth(cap_lw)
+                elif xdata[0] == xdata[1]:
+                    child.set_linewidth(whisker_lw)
+
+
+def apply_violinplot_style(ax: Axes, style: Dict[str, Any]) -> None:
+    """Apply violinplot line width styling to existing violinplot elements.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        Target axes containing violinplot elements.
+    style : dict
+        Style dictionary with violinplot_* keys.
+    """
+    from matplotlib.collections import LineCollection, PolyCollection
+
+    body_lw = mm_to_pt(style.get("violinplot_line_mm", 0.2))
+    whisker_lw = mm_to_pt(style.get("violinplot_whisker_mm", 0.2))
+
+    for child in ax.get_children():
+        if isinstance(child, PolyCollection):
+            child.set_linewidth(body_lw)
+        elif isinstance(child, LineCollection):
+            child.set_linewidth(whisker_lw)
+
+
+def apply_barplot_style(ax: Axes, style: Dict[str, Any]) -> None:
+    """Apply barplot edge styling to existing bar elements.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        Target axes containing bar elements.
+    style : dict
+        Style dictionary with barplot_* keys.
+    """
+    from matplotlib.patches import Rectangle
+
+    edge_lw = mm_to_pt(style.get("barplot_edge_mm", 0.2))
+
+    for patch in ax.patches:
+        if isinstance(patch, Rectangle):
+            patch.set_linewidth(edge_lw)
+            patch.set_edgecolor("black")
+
+
+def apply_histogram_style(ax: Axes, style: Dict[str, Any]) -> None:
+    """Apply histogram edge styling to existing histogram elements.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        Target axes containing histogram elements.
+    style : dict
+        Style dictionary with histogram_* keys.
+    """
+    from matplotlib.patches import Rectangle
+
+    edge_lw = mm_to_pt(style.get("histogram_edge_mm", 0.2))
+
+    for patch in ax.patches:
+        if isinstance(patch, Rectangle):
+            patch.set_linewidth(edge_lw)
+            patch.set_edgecolor("black")
+
+
+def apply_pie_style(ax: Axes, style: Dict[str, Any]) -> None:
+    """Apply pie chart styling to existing pie elements.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        Target axes containing pie chart elements.
+    style : dict
+        Style dictionary with pie_* keys.
+    """
+    from matplotlib.patches import Wedge
+
+    has_pie = any(isinstance(p, Wedge) for p in ax.patches)
+    if not has_pie:
+        return
+
+    text_pt = style.get("pie_text_pt", 6)
+    show_axes = style.get("pie_show_axes", False)
+    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([])
+        for spine in ax.spines.values():
+            spine.set_visible(False)
+
+
+def apply_matrix_style(ax: Axes, style: Dict[str, Any]) -> None:
+    """Apply imshow/matshow/spy styling (hide axes if configured).
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        Target axes containing matrix plot elements.
+    style : dict
+        Style dictionary with imshow_*, matshow_*, spy_* keys.
+    """
+    from matplotlib.image import AxesImage
+
+    has_image = any(isinstance(c, AxesImage) for c in ax.get_children())
+    if not has_image:
+        return
+
+    # Check if this is specgram (has xlabel or ylabel)
+    # Specgram typically has "Time" and "Frequency" labels
+    xlabel = ax.get_xlabel()
+    ylabel = ax.get_ylabel()
+    is_specgram = bool(xlabel or ylabel)
+
+    # Don't hide axes for specgram - it needs visible ticks
+    if is_specgram:
+        return
+
+    show_axes = style.get("imshow_show_axes", True)
+    show_labels = style.get("imshow_show_labels", True)
+
+    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)
+
+    if not show_labels:
+        ax.set_xlabel("")
+        ax.set_ylabel("")
+
+
+__all__ = [
+    "apply_boxplot_style",
+    "apply_violinplot_style",
+    "apply_barplot_style",
+    "apply_histogram_style",
+    "apply_pie_style",
+    "apply_matrix_style",
+]
+
+# EOF