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

figrecipe/_composition/_compose.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Main composition logic for combining multiple figures."""
+
+from pathlib import Path
+from typing import Any, Dict, Tuple, Union
+
+from numpy.typing import NDArray
+
+from .._recorder import FigureRecord
+from .._serializer import load_recipe
+from .._wrappers import RecordingAxes, RecordingFigure
+
+
+def compose(
+    layout: Tuple[int, int],
+    sources: Dict[Tuple[int, int], Union[str, Path, FigureRecord, Tuple]],
+    **kwargs,
+) -> Tuple[RecordingFigure, Union[RecordingAxes, NDArray]]:
+    """Compose a new figure from multiple recipe sources.
+
+    Parameters
+    ----------
+    layout : tuple
+        (nrows, ncols) for the new composite figure.
+    sources : dict
+        Mapping of (row, col) -> source specification.
+        Source can be:
+        - str/Path: Recipe file path (uses first axes)
+        - FigureRecord: Direct record (uses first axes)
+        - Tuple[source, ax_key]: Specific axes from source
+
+    **kwargs
+        Additional arguments passed to subplots().
+
+    Returns
+    -------
+    fig : RecordingFigure
+        Composed figure.
+    axes : RecordingAxes or ndarray of RecordingAxes
+        Axes of the composed figure.
+
+    Examples
+    --------
+    >>> import figrecipe as fr
+    >>> fig, axes = fr.compose(
+    ...     layout=(1, 2),
+    ...     sources={
+    ...         (0, 0): "experiment_a.yaml",
+    ...         (0, 1): "experiment_b.yaml",
+    ...     }
+    ... )
+    """
+    from .. import subplots
+
+    nrows, ncols = layout
+    fig, axes = subplots(nrows=nrows, ncols=ncols, **kwargs)
+
+    for (row, col), source_spec in sources.items():
+        source_record, ax_key = _parse_source_spec(source_spec)
+        ax_record = source_record.axes.get(ax_key)
+
+        if ax_record is None:
+            available = list(source_record.axes.keys())
+            raise ValueError(
+                f"Axes '{ax_key}' not found in source. Available: {available}"
+            )
+
+        target_ax = _get_axes_at(axes, row, col, nrows, ncols)
+        _replay_axes_record(target_ax, ax_record, fig.record, row, col)
+
+    return fig, axes
+
+
+def _parse_source_spec(
+    spec: Union[str, Path, FigureRecord, Tuple],
+) -> Tuple[FigureRecord, str]:
+    """Parse source specification into (FigureRecord, ax_key).
+
+    Parameters
+    ----------
+    spec : various
+        Source specification.
+
+    Returns
+    -------
+    tuple
+        (FigureRecord, ax_key)
+    """
+    if isinstance(spec, (str, Path)):
+        return load_recipe(spec), "ax_0_0"
+    elif isinstance(spec, FigureRecord):
+        return spec, "ax_0_0"
+    elif isinstance(spec, tuple) and len(spec) == 2:
+        source, ax_key = spec
+        if isinstance(source, (str, Path)):
+            return load_recipe(source), ax_key
+        elif isinstance(source, FigureRecord):
+            return source, ax_key
+        raise TypeError(f"Invalid source in tuple: {type(source)}")
+    raise TypeError(f"Invalid source spec type: {type(spec)}")
+
+
+def _get_axes_at(
+    axes: Union[RecordingAxes, NDArray],
+    row: int,
+    col: int,
+    nrows: int,
+    ncols: int,
+) -> RecordingAxes:
+    """Get axes at position, handling different array shapes.
+
+    Parameters
+    ----------
+    axes : RecordingAxes or ndarray
+        Axes object(s) from subplots.
+    row, col : int
+        Target position.
+    nrows, ncols : int
+        Grid dimensions.
+
+    Returns
+    -------
+    RecordingAxes
+        Axes at the specified position.
+    """
+    if nrows == 1 and ncols == 1:
+        return axes
+    elif nrows == 1:
+        return axes[col]
+    elif ncols == 1:
+        return axes[row]
+    else:
+        return axes[row, col]
+
+
+def _replay_axes_record(
+    target_ax: RecordingAxes,
+    ax_record,
+    fig_record: FigureRecord,
+    row: int,
+    col: int,
+) -> None:
+    """Replay all calls from ax_record onto target axes.
+
+    Parameters
+    ----------
+    target_ax : RecordingAxes
+        Target axes to replay onto.
+    ax_record : AxesRecord
+        Source axes record with calls.
+    fig_record : FigureRecord
+        Figure record to update.
+    row, col : int
+        Target position for recording.
+    """
+    from .._reproducer._core import _replay_call
+
+    mpl_ax = target_ax._ax if hasattr(target_ax, "_ax") else target_ax
+    result_cache: Dict[str, Any] = {}
+
+    # Replay plotting calls
+    for call in ax_record.calls:
+        result = _replay_call(mpl_ax, call, result_cache)
+        if result is not None:
+            result_cache[call.id] = result
+
+    # Replay decoration calls
+    for call in ax_record.decorations:
+        result = _replay_call(mpl_ax, call, result_cache)
+        if result is not None:
+            result_cache[call.id] = result
+
+    # Update figure record with imported axes
+    ax_key = f"ax_{row}_{col}"
+    fig_record.axes[ax_key] = ax_record
+
+
+__all__ = ["compose"]

figrecipe/_composition/_import_axes.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Import axes from external recipes into existing figures."""
+
+from pathlib import Path
+from typing import Tuple, Union
+
+from .._recorder import FigureRecord
+from .._serializer import load_recipe
+from .._wrappers import RecordingAxes, RecordingFigure
+from ._compose import _replay_axes_record
+
+
+def import_axes(
+    fig: RecordingFigure,
+    target_position: Tuple[int, int],
+    source: Union[str, Path, FigureRecord],
+    source_axes: str = "ax_0_0",
+) -> RecordingAxes:
+    """Import axes from another recipe into an existing figure.
+
+    This function copies all plotting calls and decorations from a source
+    axes (in a recipe file or FigureRecord) to a target position in an
+    existing figure. The target axes is cleared before import.
+
+    Parameters
+    ----------
+    fig : RecordingFigure
+        Target figure to import into.
+    target_position : tuple
+        (row, col) position in target figure.
+    source : str, Path, or FigureRecord
+        Source recipe file path or FigureRecord object.
+    source_axes : str, optional
+        Key of axes to import from source (default: "ax_0_0").
+
+    Returns
+    -------
+    RecordingAxes
+        The target axes after import.
+
+    Raises
+    ------
+    ValueError
+        If source_axes key not found in source.
+    TypeError
+        If source is not a valid type.
+
+    Examples
+    --------
+    >>> import figrecipe as fr
+    >>> fig, axes = fr.subplots(1, 2)
+    >>> axes[0].plot([1, 2, 3], [1, 4, 9])
+    >>> fr.import_axes(fig, (0, 1), "analysis.yaml")
+    """
+    # Load source if path
+    if isinstance(source, (str, Path)):
+        source_record = load_recipe(source)
+    elif isinstance(source, FigureRecord):
+        source_record = source
+    else:
+        raise TypeError(f"Invalid source type: {type(source)}")
+
+    # Get source axes record
+    ax_record = source_record.axes.get(source_axes)
+    if ax_record is None:
+        available = list(source_record.axes.keys())
+        raise ValueError(
+            f"Axes '{source_axes}' not found in source. Available: {available}"
+        )
+
+    # Get target axes
+    row, col = target_position
+    target_ax = _get_target_axes(fig, row, col)
+
+    # Clear existing content
+    mpl_ax = target_ax._ax if hasattr(target_ax, "_ax") else target_ax
+    mpl_ax.clear()
+
+    # Replay source calls onto target
+    _replay_axes_record(target_ax, ax_record, fig.record, row, col)
+
+    return target_ax
+
+
+def _get_target_axes(
+    fig: RecordingFigure,
+    row: int,
+    col: int,
+) -> RecordingAxes:
+    """Get target axes from figure at position.
+
+    Parameters
+    ----------
+    fig : RecordingFigure
+        The figure.
+    row, col : int
+        Target position.
+
+    Returns
+    -------
+    RecordingAxes
+        Axes at position.
+
+    Raises
+    ------
+    IndexError
+        If position is out of range.
+    """
+    if not hasattr(fig, "_axes"):
+        raise ValueError("Figure must have _axes attribute")
+
+    axes = fig._axes
+    try:
+        # Handle different axes array structures
+        if isinstance(axes, list):
+            if isinstance(axes[0], list):
+                return axes[row][col]
+            else:
+                return axes[max(row, col)]
+        else:
+            return axes[row, col]
+    except (IndexError, KeyError) as e:
+        raise IndexError(f"Position ({row}, {col}) out of range for figure axes") from e
+
+
+__all__ = ["import_axes"]

figrecipe/_composition/_visibility.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Panel visibility management for composition feature."""
+
+from typing import Tuple
+
+from .._wrappers import RecordingFigure
+
+
+def hide_panel(fig: RecordingFigure, position: Tuple[int, int]) -> None:
+    """Hide a panel (visually drop it without deleting data).
+
+    The panel data is preserved in the recipe but not rendered.
+    Use show_panel() to restore visibility.
+
+    Parameters
+    ----------
+    fig : RecordingFigure
+        The figure containing the panel.
+    position : tuple
+        (row, col) position of the panel to hide.
+
+    Examples
+    --------
+    >>> import figrecipe as fr
+    >>> fig, axes = fr.subplots(1, 2)
+    >>> axes[0].plot([1, 2], [1, 2])
+    >>> fr.hide_panel(fig, (0, 1))  # Hide empty second panel
+    """
+    ax_key = f"ax_{position[0]}_{position[1]}"
+    if ax_key in fig.record.axes:
+        fig.record.axes[ax_key].visible = False
+        _set_axes_visible(fig, position, False)
+
+
+def show_panel(fig: RecordingFigure, position: Tuple[int, int]) -> None:
+    """Show a previously hidden panel.
+
+    Parameters
+    ----------
+    fig : RecordingFigure
+        The figure containing the panel.
+    position : tuple
+        (row, col) position of the panel to show.
+
+    Examples
+    --------
+    >>> import figrecipe as fr
+    >>> fig, axes = fr.subplots(1, 2)
+    >>> fr.hide_panel(fig, (0, 1))
+    >>> fr.show_panel(fig, (0, 1))  # Restore visibility
+    """
+    ax_key = f"ax_{position[0]}_{position[1]}"
+    if ax_key in fig.record.axes:
+        fig.record.axes[ax_key].visible = True
+        _set_axes_visible(fig, position, True)
+
+
+def toggle_panel(fig: RecordingFigure, position: Tuple[int, int]) -> bool:
+    """Toggle panel visibility.
+
+    Parameters
+    ----------
+    fig : RecordingFigure
+        The figure containing the panel.
+    position : tuple
+        (row, col) position of the panel.
+
+    Returns
+    -------
+    bool
+        New visibility state (True = visible, False = hidden).
+
+    Examples
+    --------
+    >>> import figrecipe as fr
+    >>> fig, ax = fr.subplots()
+    >>> fr.toggle_panel(fig, (0, 0))  # Returns False (now hidden)
+    >>> fr.toggle_panel(fig, (0, 0))  # Returns True (now visible)
+    """
+    ax_key = f"ax_{position[0]}_{position[1]}"
+    if ax_key in fig.record.axes:
+        current = fig.record.axes[ax_key].visible
+        if current:
+            hide_panel(fig, position)
+        else:
+            show_panel(fig, position)
+        return not current
+    return False
+
+
+def _set_axes_visible(
+    fig: RecordingFigure,
+    position: Tuple[int, int],
+    visible: bool,
+) -> None:
+    """Set matplotlib axes visibility.
+
+    Parameters
+    ----------
+    fig : RecordingFigure
+        The figure.
+    position : tuple
+        (row, col) position.
+    visible : bool
+        Whether to make visible or hidden.
+    """
+    row, col = position
+    try:
+        axes = fig._axes
+        if isinstance(axes, list):
+            if isinstance(axes[0], list):
+                ax = axes[row][col]
+            else:
+                ax = axes[max(row, col)]
+        else:
+            ax = axes[row, col]
+
+        mpl_ax = ax._ax if hasattr(ax, "_ax") else ax
+        mpl_ax.set_visible(visible)
+    except (IndexError, AttributeError, KeyError):
+        pass
+
+
+__all__ = ["hide_panel", "show_panel", "toggle_panel"]

figrecipe/_dev/__init__.py

@@ -16,105 +16,16 @@ Usage:
     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
-
+from . import browser
+from ._plotters import PLOTTERS, get_plotter, list_plotters
+from ._run_demos import run_all_demos
 
 __all__ = [
     "PLOTTERS",
     "list_plotters",
     "get_plotter",
     "run_all_demos",
+    "browser",
 ]
 
 # EOF

figrecipe/_dev/_plotters.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Plotter registry for demo plotters."""
+
+import importlib
+from pathlib import Path
+
+from .._params import PLOTTING_METHODS
+
+# Auto-import plotters from demo_plotters subdirectories
+_demo_dir = Path(__file__).parent / "demo_plotters"
+PLOTTERS = {}
+
+# Category subdirectories
+_category_dirs = [
+    "line_curve",
+    "scatter_points",
+    "bar_categorical",
+    "distribution",
+    "image_matrix",
+    "contour_surface",
+    "spectral_signal",
+    "vector_flow",
+    "special",
+]
+
+# Build mapping from method_name to category
+_method_to_category = {}
+for cat_dir in _category_dirs:
+    cat_path = _demo_dir / cat_dir
+    if cat_path.is_dir():
+        for plot_file in cat_path.glob("plot_*.py"):
+            method_name = plot_file.stem.replace("plot_", "")
+            _method_to_category[method_name] = cat_dir
+
+for method_name in sorted(PLOTTING_METHODS):
+    module_name = f"plot_{method_name}"
+    func_name = f"plot_{method_name}"
+
+    # Check if we have this plotter in a category subdirectory
+    if method_name in _method_to_category:
+        cat_dir = _method_to_category[method_name]
+        try:
+            module = importlib.import_module(
+                f".demo_plotters.{cat_dir}.{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())}")
+
+
+# EOF

figrecipe/_dev/_run_demos.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Demo runner for all plotters."""
+
+from pathlib import Path
+
+from ._plotters import PLOTTERS
+
+
+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
+
+
+# EOF