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

figrecipe/_api/__init__.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""API helper modules for figrecipe.
+
+This package contains helper functions extracted from the main __init__.py
+to reduce file size and improve maintainability.
+"""
+
+from ._extract import DECORATION_FUNCS, extract_call_data, to_array
+from ._panel import calculate_panel_position, get_panel_label_fontsize
+from ._save import (
+    IMAGE_EXTENSIONS,
+    YAML_EXTENSIONS,
+    get_save_dpi,
+    get_save_transparency,
+    resolve_save_paths,
+)
+from ._subplots import (
+    _apply_mm_layout_to_figure,
+    _apply_style_to_axes,
+    _calculate_mm_layout,
+    _check_mm_layout,
+    _get_mm_value,
+)
+
+__all__ = [
+    # Subplots helpers
+    "_get_mm_value",
+    "_check_mm_layout",
+    "_calculate_mm_layout",
+    "_apply_mm_layout_to_figure",
+    "_apply_style_to_axes",
+    # Save helpers
+    "IMAGE_EXTENSIONS",
+    "YAML_EXTENSIONS",
+    "resolve_save_paths",
+    "get_save_dpi",
+    "get_save_transparency",
+    # Extract helpers
+    "DECORATION_FUNCS",
+    "to_array",
+    "extract_call_data",
+    # Panel helpers
+    "get_panel_label_fontsize",
+    "calculate_panel_position",
+]
+
+# EOF

figrecipe/_api/_extract.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Data extraction helpers for the public API."""
+
+from typing import Any, Dict, Set
+
+import numpy as np
+
+# Decoration functions to skip when extracting data
+DECORATION_FUNCS: Set[str] = {
+    "set_xlabel",
+    "set_ylabel",
+    "set_title",
+    "set_xlim",
+    "set_ylim",
+    "legend",
+    "grid",
+    "axhline",
+    "axvline",
+    "text",
+    "annotate",
+}
+
+
+def to_array(data: Any) -> np.ndarray:
+    """Convert data to numpy array, handling YAML types.
+
+    Parameters
+    ----------
+    data : any
+        Data to convert.
+
+    Returns
+    -------
+    np.ndarray
+        Converted numpy array.
+    """
+    # Handle dict with 'data' key (serialized array format)
+    if isinstance(data, dict) or (hasattr(data, "keys") and "data" in data):
+        return np.array(data["data"])
+    if hasattr(data, "tolist"):  # Already array-like
+        return np.array(data)
+    return np.array(
+        list(data) if hasattr(data, "__iter__") and not isinstance(data, str) else data
+    )
+
+
+def extract_call_data(call) -> Dict[str, Any]:
+    """Extract data arrays from a single call record.
+
+    Parameters
+    ----------
+    call : CallRecord
+        The call to extract data from.
+
+    Returns
+    -------
+    dict
+        Dictionary with extracted data arrays.
+    """
+    call_data = {}
+
+    # Extract positional arguments based on function type
+    if call.function in ("plot", "scatter", "fill_between"):
+        if len(call.args) >= 1:
+            call_data["x"] = to_array(call.args[0])
+        if len(call.args) >= 2:
+            call_data["y"] = to_array(call.args[1])
+
+    elif call.function == "bar":
+        if len(call.args) >= 1:
+            call_data["x"] = to_array(call.args[0])
+        if len(call.args) >= 2:
+            call_data["height"] = to_array(call.args[1])
+
+    elif call.function == "hist":
+        if len(call.args) >= 1:
+            call_data["x"] = to_array(call.args[0])
+
+    elif call.function == "errorbar":
+        if len(call.args) >= 1:
+            call_data["x"] = to_array(call.args[0])
+        if len(call.args) >= 2:
+            call_data["y"] = to_array(call.args[1])
+
+    # Extract relevant kwargs
+    for key in ("c", "s", "yerr", "xerr", "weights", "bins"):
+        if key in call.kwargs:
+            val = call.kwargs[key]
+            if (
+                isinstance(val, (list, tuple))
+                or hasattr(val, "__iter__")
+                and not isinstance(val, str)
+            ):
+                call_data[key] = to_array(val)
+            else:
+                call_data[key] = val
+
+    return call_data
+
+
+__all__ = [
+    "DECORATION_FUNCS",
+    "to_array",
+    "extract_call_data",
+]
+
+# EOF

figrecipe/_api/_notebook.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Notebook utilities for figrecipe.
+
+Provides SVG rendering for Jupyter notebooks.
+"""
+
+__all__ = [
+    "enable_svg",
+]
+
+# Notebook display format flag (set once per session)
+_notebook_format_set = False
+
+
+def _enable_notebook_svg():
+    """Enable SVG format for Jupyter notebook display.
+
+    This provides crisp vector graphics at any zoom level.
+    Called automatically when load_style() or subplots() is used.
+    """
+    global _notebook_format_set
+    if _notebook_format_set:
+        return
+
+    try:
+        # Method 1: matplotlib_inline (IPython 7.0+, JupyterLab)
+        from matplotlib_inline.backend_inline import set_matplotlib_formats
+
+        set_matplotlib_formats("svg")
+        _notebook_format_set = True
+    except (ImportError, Exception):
+        try:
+            # Method 2: IPython config (older IPython)
+            from IPython import get_ipython
+
+            ipython = get_ipython()
+            if ipython is not None and hasattr(ipython, "kernel"):
+                # Only run in actual Jupyter kernel, not IPython console
+                ipython.run_line_magic(
+                    "config", "InlineBackend.figure_formats = ['svg']"
+                )
+                _notebook_format_set = True
+        except Exception:
+            pass  # Not in Jupyter environment or method not available
+
+
+def enable_svg():
+    """Manually enable SVG format for Jupyter notebook display.
+
+    Call this if figures appear pixelated in notebooks.
+
+    Examples
+    --------
+    >>> import figrecipe as fr
+    >>> fr.enable_svg()  # Enable SVG rendering
+    >>> fig, ax = fr.subplots()  # Now renders as crisp SVG
+    """
+    global _notebook_format_set
+    _notebook_format_set = False  # Force re-application
+    _enable_notebook_svg()

figrecipe/_api/_panel.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Panel label helper for the public API."""
+
+from typing import Optional, Tuple
+
+
+def get_panel_label_fontsize(explicit_fontsize: Optional[float] = None) -> float:
+    """Get fontsize for panel labels from style or default."""
+    if explicit_fontsize is not None:
+        return explicit_fontsize
+
+    try:
+        from ..styles._style_loader import _STYLE_CACHE
+
+        if _STYLE_CACHE is not None:
+            return getattr(getattr(_STYLE_CACHE, "fonts", None), "panel_label_pt", 10)
+    except Exception:
+        pass
+    return 10
+
+
+def calculate_panel_position(
+    loc: str,
+    offset: Tuple[float, float],
+) -> Tuple[float, float]:
+    """Calculate x, y position based on location and offset."""
+    if loc == "upper left":
+        x, y = offset
+    elif loc == "upper right":
+        x, y = 1.0 + abs(offset[0]), offset[1]
+    elif loc == "lower left":
+        x, y = offset[0], -abs(offset[1]) + 1.0
+    elif loc == "lower right":
+        x, y = 1.0 + abs(offset[0]), -abs(offset[1]) + 1.0
+    else:
+        x, y = offset
+    return x, y
+
+
+__all__ = [
+    "get_panel_label_fontsize",
+    "calculate_panel_position",
+]
+
+# EOF

figrecipe/_api/_save.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Save function helpers for the public API."""
+
+from pathlib import Path
+from typing import Optional, Tuple
+
+# Image extensions supported for saving
+IMAGE_EXTENSIONS = {
+    ".png",
+    ".pdf",
+    ".svg",
+    ".jpg",
+    ".jpeg",
+    ".eps",
+    ".tiff",
+    ".tif",
+}
+YAML_EXTENSIONS = {".yaml", ".yml"}
+
+
+def resolve_save_paths(
+    path: Path,
+    image_format: Optional[str] = None,
+) -> Tuple[Path, Path, str]:
+    """Resolve image and YAML paths from the provided path.
+
+    Parameters
+    ----------
+    path : Path
+        User-provided output path.
+    image_format : str, optional
+        Explicit image format when path is YAML.
+
+    Returns
+    -------
+    tuple
+        (image_path, yaml_path, img_format)
+    """
+    suffix_lower = path.suffix.lower()
+
+    if suffix_lower in IMAGE_EXTENSIONS:
+        # User provided image path
+        image_path = path
+        yaml_path = path.with_suffix(".yaml")
+        img_format = suffix_lower[1:]  # Remove leading dot
+    elif suffix_lower in YAML_EXTENSIONS:
+        # User provided YAML path
+        yaml_path = path
+        img_format = _get_default_image_format(image_format)
+        image_path = path.with_suffix(f".{img_format}")
+    else:
+        # Unknown extension - treat as base name, add both extensions
+        yaml_path = path.with_suffix(".yaml")
+        img_format = _get_default_image_format(image_format)
+        image_path = path.with_suffix(f".{img_format}")
+
+    return image_path, yaml_path, img_format
+
+
+def _get_default_image_format(explicit_format: Optional[str] = None) -> str:
+    """Get default image format from style or fallback to png."""
+    if explicit_format is not None:
+        return explicit_format.lower().lstrip(".")
+
+    # Check global style for preferred format
+    from ..styles._style_loader import _STYLE_CACHE
+
+    if _STYLE_CACHE is not None:
+        try:
+            return _STYLE_CACHE.output.format.lower()
+        except (KeyError, AttributeError):
+            pass
+    return "png"
+
+
+def get_save_dpi(explicit_dpi: Optional[int] = None) -> int:
+    """Get DPI for saving, using style default if not specified."""
+    if explicit_dpi is not None:
+        return explicit_dpi
+
+    from ..styles._style_loader import _STYLE_CACHE
+
+    if _STYLE_CACHE is not None:
+        try:
+            return _STYLE_CACHE.output.dpi
+        except (KeyError, AttributeError):
+            pass
+    return 300
+
+
+def get_save_transparency() -> bool:
+    """Get transparency setting from style."""
+    from ..styles._style_loader import _STYLE_CACHE
+
+    if _STYLE_CACHE is not None:
+        try:
+            return _STYLE_CACHE.output.transparent
+        except (KeyError, AttributeError):
+            pass
+    return False
+
+
+def save_figure(
+    fig,
+    path,
+    include_data: bool = True,
+    data_format: str = "csv",
+    validate: bool = True,
+    validate_mse_threshold: float = 100.0,
+    validate_error_level: str = "error",
+    verbose: bool = True,
+    dpi: Optional[int] = None,
+    image_format: Optional[str] = None,
+):
+    """Core save implementation."""
+    from .._wrappers import RecordingFigure
+
+    path = Path(path)
+
+    if not isinstance(fig, RecordingFigure):
+        raise TypeError(
+            "Expected RecordingFigure. Use fr.subplots() to create "
+            "a recording-enabled figure."
+        )
+
+    # Resolve paths
+    image_path, yaml_path, _ = resolve_save_paths(path, image_format)
+
+    # Get DPI and transparency from style if not specified
+    dpi = get_save_dpi(dpi)
+    transparent = get_save_transparency()
+
+    # Finalize tick configuration and special plot types for all axes
+    from ..styles._style_applier import finalize_special_plots, finalize_ticks
+
+    # Get style for special plot finalization
+    style_dict = {}
+    if hasattr(fig, "style") and fig.style:
+        from ..styles import get_style
+
+        style_dict = get_style(fig.style)
+
+    for ax in fig.fig.get_axes():
+        finalize_ticks(ax)
+        finalize_special_plots(ax, style_dict)
+
+    # Save the image
+    fig.fig.savefig(image_path, dpi=dpi, bbox_inches="tight", transparent=transparent)
+
+    # Save the recipe
+    saved_yaml = fig.save_recipe(
+        yaml_path, include_data=include_data, data_format=data_format
+    )
+
+    # Validate if requested
+    if validate:
+        from .._validator import validate_on_save
+
+        result = validate_on_save(fig, saved_yaml, mse_threshold=validate_mse_threshold)
+        status = "PASSED" if result.valid else "FAILED"
+        if verbose:
+            print(
+                f"Saved: {image_path} + {yaml_path} (Reproducible Validation: {status})"
+            )
+        if not result.valid:
+            msg = f"Reproducibility validation failed (MSE={result.mse:.1f}): {result.message}"
+            if validate_error_level == "error":
+                raise ValueError(msg)
+            elif validate_error_level == "warning":
+                import warnings
+
+                warnings.warn(msg, UserWarning)
+            # "debug" level: silent, just return the result
+        return image_path, yaml_path, result
+
+    if verbose:
+        print(f"Saved: {image_path} + {yaml_path}")
+    return image_path, yaml_path, None
+
+
+__all__ = [
+    "IMAGE_EXTENSIONS",
+    "YAML_EXTENSIONS",
+    "resolve_save_paths",
+    "get_save_dpi",
+    "get_save_transparency",
+    "save_figure",
+]
+
+# EOF

figrecipe/_api/_seaborn_proxy.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Seaborn proxy for figrecipe.
+
+Provides lazy seaborn integration via ps.sns.
+"""
+
+__all__ = [
+    "sns",
+]
+
+# Lazy import for seaborn to avoid hard dependency
+_sns_recorder = None
+
+
+def _get_sns():
+    """Get the seaborn recorder (lazy initialization)."""
+    global _sns_recorder
+    if _sns_recorder is None:
+        from .._seaborn import get_seaborn_recorder
+
+        _sns_recorder = get_seaborn_recorder()
+    return _sns_recorder
+
+
+class _SeabornProxy:
+    """Proxy object for seaborn access via ps.sns."""
+
+    def __getattr__(self, name: str):
+        return getattr(_get_sns(), name)
+
+
+# Create seaborn proxy
+sns = _SeabornProxy()

figrecipe/_api/_style_manager.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Style management API for figrecipe.
+
+Provides style loading, unloading, and application functions.
+"""
+
+__all__ = [
+    "load_style",
+    "unload_style",
+    "list_presets",
+    "apply_style",
+    "STYLE",
+]
+
+
+def load_style(style="SCITEX", dark=False):
+    """Load style configuration and apply it globally.
+
+    After calling this function, subsequent `subplots()` calls will
+    automatically use the loaded style (fonts, colors, theme, etc.).
+
+    Parameters
+    ----------
+    style : str, Path, bool, or None
+        One of:
+        - "SCITEX" / "FIGRECIPE": Scientific publication style (default)
+        - "MATPLOTLIB": Vanilla matplotlib defaults
+        - Path to custom YAML file: "/path/to/my_style.yaml"
+        - None or False: Unload style (reset to matplotlib defaults)
+    dark : bool, optional
+        If True, apply dark theme transformation (default: False).
+        Equivalent to appending "_DARK" to preset name.
+
+    Returns
+    -------
+    DotDict or None
+        Style configuration with dot-notation access.
+        Returns None if style is unloaded.
+
+    Examples
+    --------
+    >>> import figrecipe as fr
+
+    >>> # Load scientific style (default)
+    >>> fr.load_style()
+    >>> fr.load_style("SCITEX")  # explicit
+
+    >>> # Load dark theme
+    >>> fr.load_style("SCITEX_DARK")
+    >>> fr.load_style("SCITEX", dark=True)  # equivalent
+
+    >>> # Reset to vanilla matplotlib
+    >>> fr.load_style(None)    # unload
+    >>> fr.load_style(False)   # unload
+    >>> fr.load_style("MATPLOTLIB")  # explicit vanilla
+
+    >>> # Access style values
+    >>> style = fr.load_style("SCITEX")
+    >>> style.axes.width_mm
+    40
+    """
+    from ..styles import load_style as _load_style
+
+    return _load_style(style, dark=dark)
+
+
+def unload_style():
+    """Unload the current style and reset to matplotlib defaults.
+
+    After calling this, subsequent `subplots()` calls will use vanilla
+    matplotlib behavior without FigRecipe styling.
+
+    Examples
+    --------
+    >>> import figrecipe as fr
+    >>> fr.load_style("SCITEX")  # Apply scientific style
+    >>> fig, ax = fr.subplots()  # Styled
+    >>> fr.unload_style()        # Reset to matplotlib defaults
+    >>> fig, ax = fr.subplots()  # Vanilla matplotlib
+    """
+    from ..styles import unload_style as _unload_style
+
+    _unload_style()
+
+
+def list_presets():
+    """List available style presets.
+
+    Returns
+    -------
+    list of str
+        Names of available presets.
+
+    Examples
+    --------
+    >>> import figrecipe as ps
+    >>> ps.list_presets()
+    ['MINIMAL', 'PRESENTATION', 'SCIENTIFIC']
+    """
+    from ..styles import list_presets as _list_presets
+
+    return _list_presets()
+
+
+def apply_style(ax, style=None):
+    """Apply mm-based styling to an axes.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        Target axes to apply styling to.
+    style : dict or DotDict, optional
+        Style configuration. If None, uses default FIGRECIPE_STYLE.
+
+    Returns
+    -------
+    float
+        Trace line width in points.
+
+    Examples
+    --------
+    >>> import figrecipe as ps
+    >>> import matplotlib.pyplot as plt
+    >>> fig, ax = plt.subplots()
+    >>> trace_lw = ps.apply_style(ax)
+    >>> ax.plot(x, y, lw=trace_lw)
+    """
+    from ..styles import apply_style_mm, get_style, to_subplots_kwargs
+
+    if style is None:
+        style = to_subplots_kwargs(get_style())
+    elif hasattr(style, "to_subplots_kwargs"):
+        style = style.to_subplots_kwargs()
+    return apply_style_mm(ax, style)
+
+
+class _StyleProxy:
+    """Proxy object for lazy style loading."""
+
+    def __getattr__(self, name):
+        from ..styles import STYLE
+
+        return getattr(STYLE, name)
+
+    def to_subplots_kwargs(self):
+        from ..styles import to_subplots_kwargs
+
+        return to_subplots_kwargs()
+
+
+# Create style proxy
+STYLE = _StyleProxy()