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

figrecipe/_dev/__init__.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Development utilities for figrecipe.
+
+Provides demo plotters for all supported matplotlib plotting methods.
+All plotters follow signature: (plt, rng, ax=None) -> (fig, ax)
+
+Usage:
+    import figrecipe as fr
+    from figrecipe._dev import PLOTTERS, run_all_demos
+
+    # Run a single demo
+    fig, ax = PLOTTERS["plot"](fr, np.random.default_rng(42))
+
+    # Run all demos
+    results = run_all_demos(fr, output_dir="./outputs")
+"""
+
+import importlib
+from pathlib import Path
+
+from .._params import PLOTTING_METHODS
+
+# Auto-import plotters from demo_plotters directory
+_demo_dir = Path(__file__).parent / "demo_plotters"
+PLOTTERS = {}
+
+for method_name in sorted(PLOTTING_METHODS):
+    module_name = f"plot_{method_name}"
+    func_name = f"plot_{method_name}"
+    module_path = _demo_dir / f"{module_name}.py"
+
+    if module_path.exists():
+        try:
+            module = importlib.import_module(
+                f".demo_plotters.{module_name}", package="figrecipe._dev"
+            )
+            if hasattr(module, func_name):
+                PLOTTERS[method_name] = getattr(module, func_name)
+        except ImportError:
+            pass
+
+
+def list_plotters():
+    """List all available plotter names."""
+    return list(PLOTTERS.keys())
+
+
+def get_plotter(name):
+    """Get a plotter function by name.
+
+    Parameters
+    ----------
+    name : str
+        Name of the plotting method (e.g., 'plot', 'scatter').
+
+    Returns
+    -------
+    callable
+        The plotter function with signature (plt, rng, ax=None) -> (fig, ax).
+    """
+    if name in PLOTTERS:
+        return PLOTTERS[name]
+    raise KeyError(f"Unknown plotter: {name}. Available: {list(PLOTTERS.keys())}")
+
+
+def run_all_demos(plt, output_dir=None, show=False):
+    """Run all demo plotters and optionally save outputs.
+
+    Parameters
+    ----------
+    plt : module
+        figrecipe module (e.g., `import figrecipe as fr`).
+    output_dir : Path or str, optional
+        Directory to save output images.
+    show : bool
+        Whether to show figures interactively.
+
+    Returns
+    -------
+    dict
+        Results for each demo: {name: {'success': bool, 'error': str or None}}
+    """
+    import matplotlib.pyplot as _plt
+    import numpy as np
+
+    rng = np.random.default_rng(42)
+    results = {}
+
+    if output_dir:
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+    for name, func in PLOTTERS.items():
+        try:
+            fig, ax = func(plt, rng)
+            if output_dir:
+                out_path = output_dir / f"plot_{name}.png"
+                mpl_fig = fig.fig if hasattr(fig, "fig") else fig
+                mpl_fig.savefig(out_path, dpi=100, bbox_inches="tight")
+            if show:
+                _plt.show()
+            else:
+                mpl_fig = fig.fig if hasattr(fig, "fig") else fig
+                _plt.close(mpl_fig)
+            results[name] = {"success": True, "error": None}
+        except Exception as e:
+            results[name] = {"success": False, "error": str(e)}
+
+    return results
+
+
+__all__ = [
+    "PLOTTERS",
+    "list_plotters",
+    "get_plotter",
+    "run_all_demos",
+]
+
+# EOF

figrecipe/_dev/demo_plotters/__init__.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Demo plotters registry for all supported figrecipe plotting methods.
+
+Usage
+-----
+>>> from figrecipe._dev.demo_plotters import REGISTRY, create_all_plots_figure
+>>>
+>>> # List all available plot types
+>>> print(list(REGISTRY.keys()))
+>>>
+>>> # Create a single figure with all plot types
+>>> fig, axes = create_all_plots_figure(fr)
+>>>
+>>> # Run individual plotter
+>>> fig, ax = REGISTRY['plot'](fr, rng, ax)
+"""
+
+import importlib
+import math
+from pathlib import Path
+from typing import Callable, Dict, Optional, Tuple
+
+import numpy as np
+
+# Registry: plot_name -> plotter function
+REGISTRY: Dict[str, Callable] = {}
+
+# Get all plot_*.py files in this directory
+_demo_dir = Path(__file__).parent
+_demo_files = sorted(_demo_dir.glob("plot_*.py"))
+
+# Import all demo functions into registry
+for _file in _demo_files:
+    _module_name = _file.stem  # e.g., plot_scatter
+    _plot_name = _module_name.replace("plot_", "")  # e.g., scatter
+    _func_name = _module_name  # e.g., plot_scatter
+    try:
+        _module = importlib.import_module(f".{_module_name}", package=__name__)
+        if hasattr(_module, _func_name):
+            REGISTRY[_plot_name] = getattr(_module, _func_name)
+    except ImportError as e:
+        print(f"Warning: Could not import {_module_name}: {e}")
+
+
+def list_plots():
+    """List all available plot types.
+
+    Returns
+    -------
+    list of str
+        Names of available plot types.
+    """
+    return list(REGISTRY.keys())
+
+
+def get_plotter(name: str) -> Optional[Callable]:
+    """Get plotter function by name.
+
+    Parameters
+    ----------
+    name : str
+        Plot type name (e.g., 'scatter', 'bar', 'hist').
+
+    Returns
+    -------
+    callable or None
+        Plotter function or None if not found.
+    """
+    return REGISTRY.get(name)
+
+
+def create_all_plots_figure(plt, seed: int = 42) -> Tuple:
+    """Create a single figure with all supported plot types.
+
+    Parameters
+    ----------
+    plt : module
+        figrecipe module (import figrecipe as fr).
+    seed : int
+        Random seed for reproducibility.
+
+    Returns
+    -------
+    tuple
+        (fig, axes) where fig is RecordingFigure and axes is array of RecordingAxes.
+    """
+    rng = np.random.default_rng(seed)
+
+    n_plots = len(REGISTRY)
+    ncols = 7
+    nrows = math.ceil(n_plots / ncols)
+
+    fig, axes = plt.subplots(nrows=nrows, ncols=ncols)
+    axes_flat = axes.flatten()
+
+    results = {}
+    for i, (name, plotter) in enumerate(REGISTRY.items()):
+        ax = axes_flat[i]
+        try:
+            plotter(plt, rng, ax=ax)
+            results[name] = {"success": True, "error": None}
+        except Exception as e:
+            ax.set_title(f"{name}\n(ERROR)")
+            ax.text(
+                0.5,
+                0.5,
+                str(e)[:50],
+                ha="center",
+                va="center",
+                transform=ax.transAxes,
+                fontsize=6,
+                wrap=True,
+            )
+            results[name] = {"success": False, "error": str(e)}
+
+    # Hide unused axes
+    for i in range(n_plots, len(axes_flat)):
+        axes_flat[i].set_visible(False)
+
+    # Add panel labels
+    panel_labels = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" * 2  # 52 labels
+    for i, ax in enumerate(axes_flat[:n_plots]):
+        if i < len(panel_labels):
+            plt.panel_label(ax, panel_labels[i])
+
+    fig.suptitle(f"All {n_plots} Supported Plot Types")
+
+    return fig, axes, results
+
+
+def run_individual_demos(plt, output_dir=None, show=False):
+    """Run all demo plotters individually and optionally save outputs.
+
+    Parameters
+    ----------
+    plt : module
+        figrecipe or matplotlib.pyplot module.
+    output_dir : Path, optional
+        Directory to save output images.
+    show : bool
+        Whether to show figures.
+
+    Returns
+    -------
+    dict
+        Results for each demo: {name: {'success': bool, 'error': str or None}}
+    """
+    rng = np.random.default_rng(42)
+    results = {}
+
+    if output_dir:
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+    for name, plotter in REGISTRY.items():
+        try:
+            fig, ax = plotter(plt, rng)
+            if output_dir:
+                out_path = output_dir / f"plot_{name}.png"
+                if hasattr(fig, "fig"):
+                    fig.fig.savefig(out_path, dpi=100, bbox_inches="tight")
+                else:
+                    fig.savefig(out_path, dpi=100, bbox_inches="tight")
+            if show:
+                plt.show()
+            else:
+                if hasattr(fig, "fig"):
+                    plt.close(fig.fig)
+                else:
+                    plt.close(fig)
+            results[name] = {"success": True, "error": None}
+        except Exception as e:
+            results[name] = {"success": False, "error": str(e)}
+
+    return results
+
+
+# Legacy exports for backwards compatibility
+__all__ = [f"plot_{name}" for name in REGISTRY.keys()]
+for _name, _func in REGISTRY.items():
+    globals()[f"plot_{_name}"] = _func
+
+
+def list_demos():
+    """Legacy: List all available demo functions."""
+    return __all__
+
+
+def run_all_demos(plt, output_dir=None, show=False):
+    """Legacy: Alias for run_individual_demos."""
+    return run_individual_demos(plt, output_dir, show)
+
+
+# EOF

figrecipe/_dev/demo_plotters/plot_acorr.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""acorr: autocorrelation demo."""
+
+
+def plot_acorr(plt, rng, ax=None):
+    """Autocorrelation demo.
+
+    Demonstrates: ax.acorr()
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.get_figure() if hasattr(ax, "get_figure") else ax.fig
+
+    x = rng.normal(0, 1, 100)
+    ax.acorr(x, maxlags=50, id="acorr")
+    ax.set_xlabel("Lag")
+    ax.set_ylabel("Autocorrelation")
+    ax.set_title("acorr")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/plot_angle_spectrum.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""angle_spectrum: phase angle spectrum demo."""
+
+import numpy as np
+
+
+def plot_angle_spectrum(plt, rng, ax=None):
+    """Phase angle spectrum demo.
+
+    Demonstrates: ax.angle_spectrum()
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.get_figure() if hasattr(ax, "get_figure") else ax.fig
+
+    fs = 1000
+    t = np.linspace(0, 1, fs)
+    signal = np.sin(2 * np.pi * 50 * t) + 0.5 * np.sin(2 * np.pi * 120 * t + np.pi / 3)
+    ax.angle_spectrum(signal, Fs=fs, id="angle_spectrum")
+    ax.set_xlabel("Frequency")
+    ax.set_ylabel("Phase (radians)")
+    ax.set_title("angle_spectrum")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/plot_bar.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""bar: bar chart demo."""
+
+
+def plot_bar(plt, rng, ax=None):
+    """Bar chart demo.
+
+    Demonstrates: ax.bar()
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.get_figure() if hasattr(ax, "get_figure") else ax.fig
+
+    categories = ["A", "B", "C", "D", "E"]
+    values = rng.integers(1, 10, 5)
+    ax.bar(categories, values, id="bar")
+    ax.set_xlabel("Category")
+    ax.set_ylabel("Value")
+    ax.set_title("bar")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/plot_barbs.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""barbs: wind barbs demo."""
+
+import numpy as np
+
+
+def plot_barbs(plt, rng, ax=None):
+    """Wind barbs demo.
+
+    Demonstrates: ax.barbs()
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.get_figure() if hasattr(ax, "get_figure") else ax.fig
+
+    x = np.arange(0, 5, 1)
+    y = np.arange(0, 5, 1)
+    X, Y = np.meshgrid(x, y)
+    U = rng.uniform(-10, 10, X.shape)
+    V = rng.uniform(-10, 10, Y.shape)
+    ax.barbs(X, Y, U, V, id="barbs")
+    ax.set_xlabel("X")
+    ax.set_ylabel("Y")
+    ax.set_title("barbs")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/plot_barh.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""barh: horizontal bar chart demo."""
+
+
+def plot_barh(plt, rng, ax=None):
+    """Horizontal bar chart demo.
+
+    Demonstrates: ax.barh()
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.get_figure() if hasattr(ax, "get_figure") else ax.fig
+
+    categories = ["A", "B", "C", "D", "E"]
+    values = rng.integers(1, 10, 5)
+    ax.barh(categories, values, id="barh")
+    ax.set_xlabel("Value")
+    ax.set_ylabel("Category")
+    ax.set_title("barh")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/plot_boxplot.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""boxplot: box plot demo."""
+
+
+def plot_boxplot(plt, rng, ax=None):
+    """Box plot demo.
+
+    Demonstrates: ax.boxplot()
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.get_figure() if hasattr(ax, "get_figure") else ax.fig
+
+    data = [rng.normal(i, 1, 100) for i in range(4)]
+    ax.boxplot(data, tick_labels=["A", "B", "C", "D"], id="boxplot")
+    ax.set_xlabel("Group")
+    ax.set_ylabel("Value")
+    ax.set_title("boxplot")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/plot_cohere.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""cohere: coherence demo."""
+
+import numpy as np
+
+
+def plot_cohere(plt, rng, ax=None):
+    """Coherence demo.
+
+    Demonstrates: ax.cohere()
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.get_figure() if hasattr(ax, "get_figure") else ax.fig
+
+    fs = 1000
+    t = np.linspace(0, 1, fs)
+    x = np.sin(2 * np.pi * 50 * t) + rng.normal(0, 0.3, len(t))
+    y = np.sin(2 * np.pi * 50 * t + np.pi / 4) + rng.normal(0, 0.3, len(t))
+    ax.cohere(x, y, Fs=fs, id="cohere")
+    ax.set_xlabel("Frequency")
+    ax.set_ylabel("Coherence")
+    ax.set_title("cohere")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/plot_contour.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""contour: contour plot demo."""
+
+import numpy as np
+
+
+def plot_contour(plt, rng, ax=None):
+    """Contour plot demo.
+
+    Demonstrates: ax.contour()
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.get_figure() if hasattr(ax, "get_figure") else ax.fig
+
+    x = np.linspace(-3, 3, 50)
+    y = np.linspace(-3, 3, 50)
+    X, Y = np.meshgrid(x, y)
+    Z = np.exp(-(X**2 + Y**2))
+    cs = ax.contour(X, Y, Z, id="contour")
+    ax.clabel(cs)
+    ax.set_xlabel("X")
+    ax.set_ylabel("Y")
+    ax.set_title("contour")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/plot_contourf.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""contourf: filled contour plot demo."""
+
+import numpy as np
+
+
+def plot_contourf(plt, rng, ax=None):
+    """Filled contour plot demo.
+
+    Demonstrates: ax.contourf()
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.get_figure() if hasattr(ax, "get_figure") else ax.fig
+
+    x = np.linspace(-3, 3, 50)
+    y = np.linspace(-3, 3, 50)
+    X, Y = np.meshgrid(x, y)
+    Z = np.exp(-(X**2 + Y**2))
+    ax.contourf(X, Y, Z, id="contourf")
+    ax.set_xlabel("X")
+    ax.set_ylabel("Y")
+    ax.set_title("contourf")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/plot_csd.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""csd: cross spectral density demo."""
+
+import numpy as np
+
+
+def plot_csd(plt, rng, ax=None):
+    """Cross spectral density demo.
+
+    Demonstrates: ax.csd()
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.get_figure() if hasattr(ax, "get_figure") else ax.fig
+
+    fs = 1000
+    t = np.linspace(0, 1, fs)
+    x = np.sin(2 * np.pi * 50 * t) + rng.normal(0, 0.3, len(t))
+    y = np.sin(2 * np.pi * 50 * t + np.pi / 4) + rng.normal(0, 0.3, len(t))
+    ax.csd(x, y, Fs=fs, id="csd")
+    ax.set_xlabel("Frequency")
+    ax.set_ylabel("CSD")
+    ax.set_title("csd")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/plot_ecdf.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""ecdf: empirical CDF demo."""
+
+
+def plot_ecdf(plt, rng, ax=None):
+    """Empirical CDF demo.
+
+    Demonstrates: ax.ecdf()
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.get_figure() if hasattr(ax, "get_figure") else ax.fig
+
+    data = rng.normal(0, 1, 100)
+    ax.ecdf(data, id="ecdf")
+    ax.set_xlabel("Value")
+    ax.set_ylabel("Cumulative Probability")
+    ax.set_title("ecdf")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/plot_errorbar.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""errorbar: error bar plot demo."""
+
+import numpy as np
+
+
+def plot_errorbar(plt, rng, ax=None):
+    """Error bar plot demo.
+
+    Demonstrates: ax.errorbar()
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.get_figure() if hasattr(ax, "get_figure") else ax.fig
+
+    x = np.arange(5)
+    y = rng.uniform(2, 8, 5)
+    yerr = rng.uniform(0.3, 0.8, 5)
+    ax.errorbar(x, y, yerr=yerr, id="errorbar")
+    ax.set_xlabel("X")
+    ax.set_ylabel("Y")
+    ax.set_title("errorbar")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/plot_eventplot.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""eventplot: event/spike raster demo."""
+
+
+def plot_eventplot(plt, rng, ax=None):
+    """Event/spike raster demo.
+
+    Demonstrates: ax.eventplot()
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.get_figure() if hasattr(ax, "get_figure") else ax.fig
+
+    # Multiple event sequences
+    events = [rng.uniform(0, 10, 20) for _ in range(5)]
+    ax.eventplot(events, id="eventplot")
+    ax.set_xlabel("Time")
+    ax.set_ylabel("Channel")
+    ax.set_title("eventplot")
+    return fig, ax
+
+
+# EOF