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

figrecipe/_dev/demo_plotters/_categories.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Plot categories for organized display."""
+
+from typing import Dict, List
+
+from ._registry import REGISTRY
+
+# Plot categories for organized display
+# Keys match directory names in demo_plotters/
+_CATEGORIES_RAW: Dict[str, List[str]] = {
+    "line_curve": [
+        "plot",
+        "step",
+        "fill",
+        "fill_between",
+        "fill_betweenx",
+        "errorbar",
+        "stackplot",
+        "stairs",
+    ],
+    "scatter_points": ["scatter"],
+    "bar_categorical": ["bar", "barh"],
+    "distribution": ["hist", "hist2d", "boxplot", "violinplot", "ecdf"],
+    "image_matrix": ["imshow", "matshow", "pcolor", "pcolormesh", "hexbin", "spy"],
+    "contour_surface": [
+        "contour",
+        "contourf",
+        "tricontour",
+        "tricontourf",
+        "tripcolor",
+        "triplot",
+    ],
+    "spectral_signal": [
+        "specgram",
+        "psd",
+        "csd",
+        "cohere",
+        "angle_spectrum",
+        "magnitude_spectrum",
+        "phase_spectrum",
+        "acorr",
+        "xcorr",
+    ],
+    "vector_flow": ["quiver", "barbs", "streamplot"],
+    "special": ["pie", "stem", "eventplot", "loglog", "semilogx", "semilogy"],
+}
+
+# Display names for categories (for UI/documentation)
+CATEGORY_DISPLAY_NAMES: Dict[str, str] = {
+    "line_curve": "Line & Curve",
+    "scatter_points": "Scatter & Points",
+    "bar_categorical": "Bar & Categorical",
+    "distribution": "Distribution",
+    "image_matrix": "2D Image & Matrix",
+    "contour_surface": "Contour & Surface",
+    "spectral_signal": "Spectral & Signal",
+    "vector_flow": "Vector & Flow",
+    "special": "Special",
+}
+
+# Filter categories to only include available plots
+CATEGORIES: Dict[str, List[str]] = {
+    cat: [p for p in plots if p in REGISTRY] for cat, plots in _CATEGORIES_RAW.items()
+}
+CATEGORIES = {cat: plots for cat, plots in CATEGORIES.items() if plots}
+
+# Representative plots (one per category)
+REPRESENTATIVES: Dict[str, str] = {
+    "line_curve": "plot",
+    "scatter_points": "scatter",
+    "bar_categorical": "bar",
+    "distribution": "hist",
+    "image_matrix": "imshow",
+    "contour_surface": "contourf",
+    "spectral_signal": "specgram",
+    "vector_flow": "quiver",
+    "special": "pie",
+}
+
+# EOF

figrecipe/_dev/demo_plotters/_figure_creators.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Figure creation functions for demo plotters."""
+
+import math
+from pathlib import Path
+from typing import Dict, Tuple
+
+import numpy as np
+
+from ._registry import REGISTRY
+
+
+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, results) where results maps name to success/error.
+    """
+    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
+    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) -> Dict:
+    """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"
+                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
+
+
+# Legacy alias
+run_all_demos = run_individual_demos
+
+# EOF

figrecipe/_dev/demo_plotters/_helpers.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Helper functions for demo plotters."""
+
+from typing import Callable, Dict, List, Optional
+
+from ._categories import CATEGORIES, REPRESENTATIVES
+from ._registry import REGISTRY
+
+
+def list_plots() -> List[str]:
+    """List all available plot types."""
+    return list(REGISTRY.keys())
+
+
+def list_plots_by_category() -> Dict[str, List[str]]:
+    """List all available plot types organized by category."""
+    return CATEGORIES.copy()
+
+
+def get_representative_plots() -> List[str]:
+    """Get one representative plot from each category for demos."""
+    return [p for p in REPRESENTATIVES.values() if p in REGISTRY]
+
+
+def get_plotter(name: str) -> Optional[Callable]:
+    """Get plotter function by name."""
+    return REGISTRY.get(name)
+
+
+# EOF

figrecipe/_dev/demo_plotters/_registry.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Registry for demo plotter functions."""
+
+import importlib
+from pathlib import Path
+from typing import Callable, Dict
+
+# Registry: plot_name -> plotter function
+REGISTRY: Dict[str, Callable] = {}
+
+# Get demo directory
+_demo_dir = Path(__file__).parent
+
+# Category subdirectories
+_category_dirs = [
+    "line_curve",
+    "scatter_points",
+    "bar_categorical",
+    "distribution",
+    "image_matrix",
+    "contour_surface",
+    "spectral_signal",
+    "vector_flow",
+    "special",
+]
+
+# Collect all plot_*.py files from subdirectories
+_demo_files = []
+for _cat_dir in _category_dirs:
+    _cat_path = _demo_dir / _cat_dir
+    if _cat_path.is_dir():
+        _demo_files.extend(sorted(_cat_path.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
+    _cat_dir = _file.parent.name  # e.g., scatter_points
+    try:
+        _module = importlib.import_module(
+            f".{_cat_dir}.{_module_name}", package=__name__.rsplit(".", 1)[0]
+        )
+        if hasattr(_module, _func_name):
+            REGISTRY[_plot_name] = getattr(_module, _func_name)
+    except ImportError as e:
+        print(f"Warning: Could not import {_cat_dir}.{_module_name}: {e}")
+
+# EOF

figrecipe/_dev/demo_plotters/bar_categorical/__init__.py

@@ -0,0 +1,4 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Demo plotters for bar_categorical category."""
+

figrecipe/_dev/demo_plotters/bar_categorical/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/bar_categorical/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/contour_surface/__init__.py

@@ -0,0 +1,4 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Demo plotters for contour_surface category."""
+

figrecipe/_dev/demo_plotters/contour_surface/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/contour_surface/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/contour_surface/plot_tricontour.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""tricontour: triangular contour demo."""
+
+import numpy as np
+
+
+def plot_tricontour(plt, rng, ax=None):
+    """Triangular contour demo.
+
+    Demonstrates: ax.tricontour()
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.get_figure() if hasattr(ax, "get_figure") else ax.fig
+
+    x = rng.uniform(0, 1, 50)
+    y = rng.uniform(0, 1, 50)
+    z = np.sin(x * 2 * np.pi) * np.cos(y * 2 * np.pi)
+    ax.tricontour(x, y, z, id="tricontour")
+    ax.set_xlabel("X")
+    ax.set_ylabel("Y")
+    ax.set_title("tricontour")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/contour_surface/plot_tricontourf.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""tricontourf: filled triangular contour demo."""
+
+import numpy as np
+
+
+def plot_tricontourf(plt, rng, ax=None):
+    """Filled triangular contour demo.
+
+    Demonstrates: ax.tricontourf()
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.get_figure() if hasattr(ax, "get_figure") else ax.fig
+
+    x = rng.uniform(0, 1, 50)
+    y = rng.uniform(0, 1, 50)
+    z = np.sin(x * 2 * np.pi) * np.cos(y * 2 * np.pi)
+    ax.tricontourf(x, y, z, id="tricontourf")
+    ax.set_xlabel("X")
+    ax.set_ylabel("Y")
+    ax.set_title("tricontourf")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/contour_surface/plot_tripcolor.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""tripcolor: unstructured triangular grid demo."""
+
+import numpy as np
+
+
+def plot_tripcolor(plt, rng, ax=None):
+    """Unstructured triangular grid demo.
+
+    Demonstrates: ax.tripcolor()
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.get_figure() if hasattr(ax, "get_figure") else ax.fig
+
+    # Create random triangulation
+    x = rng.uniform(0, 1, 30)
+    y = rng.uniform(0, 1, 30)
+    z = np.sin(x * 2 * np.pi) * np.cos(y * 2 * np.pi)
+    ax.tripcolor(x, y, z, id="tripcolor")
+    ax.set_xlabel("X")
+    ax.set_ylabel("Y")
+    ax.set_title("tripcolor")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/contour_surface/plot_triplot.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""triplot: triangular mesh plot demo."""
+
+
+def plot_triplot(plt, rng, ax=None):
+    """Triangular mesh plot demo.
+
+    Demonstrates: ax.triplot()
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.get_figure() if hasattr(ax, "get_figure") else ax.fig
+
+    x = rng.uniform(0, 1, 20)
+    y = rng.uniform(0, 1, 20)
+    ax.triplot(x, y, id="triplot")
+    ax.set_xlabel("X")
+    ax.set_ylabel("Y")
+    ax.set_title("triplot")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/distribution/__init__.py

@@ -0,0 +1,4 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Demo plotters for distribution category."""
+

figrecipe/_dev/demo_plotters/distribution/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/distribution/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/distribution/plot_hist.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""hist: histogram demo."""
+
+
+def plot_hist(plt, rng, ax=None):
+    """Histogram demo.
+
+    Demonstrates: ax.hist()
+    """
+    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, 500)
+    ax.hist(data, bins=30, id="hist")
+    ax.set_xlabel("Value")
+    ax.set_ylabel("Frequency")
+    ax.set_title("hist")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/distribution/plot_hist2d.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""hist2d: 2D histogram demo."""
+
+
+def plot_hist2d(plt, rng, ax=None):
+    """2D histogram demo.
+
+    Demonstrates: ax.hist2d()
+    """
+    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, 1000)
+    y = rng.normal(0, 1, 1000)
+    ax.hist2d(x, y, id="hist2d")
+    ax.set_xlabel("X")
+    ax.set_ylabel("Y")
+    ax.set_title("hist2d")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/distribution/plot_violinplot.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""violinplot: violin plot demo."""
+
+
+def plot_violinplot(plt, rng, ax=None):
+    """Violin plot demo.
+
+    Demonstrates: ax.violinplot()
+    """
+    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)]
+    # Modern style: show box inside (default from SCITEX style)
+    ax.violinplot(data, id="violinplot")
+    ax.set_xlabel("Group")
+    ax.set_ylabel("Value")
+    ax.set_title("violinplot")
+    return fig, ax
+
+
+# EOF

figrecipe/_dev/demo_plotters/image_matrix/__init__.py

@@ -0,0 +1,4 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Demo plotters for image_matrix category."""
+

figrecipe/_dev/demo_plotters/image_matrix/plot_hexbin.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""hexbin: hexagonal binning demo."""
+
+
+def plot_hexbin(plt, rng, ax=None):
+    """Hexagonal binning demo.
+
+    Demonstrates: ax.hexbin()
+    """
+    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, 1000)
+    y = rng.normal(0, 1, 1000)
+    ax.hexbin(x, y, id="hexbin")
+    ax.set_xlabel("X")
+    ax.set_ylabel("Y")
+    ax.set_title("hexbin")
+    return fig, ax
+
+
+# EOF