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

figrecipe/_wrappers/_axes.py

@@ -2,10 +2,9 @@
 # -*- coding: utf-8 -*-
 """Wrapped Axes that records all plotting calls."""
 
-from typing import Any, Dict, List, Optional, Tuple, TYPE_CHECKING
+from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple
 
 import numpy as np
-import matplotlib.pyplot as plt
 from matplotlib.axes import Axes
 
 if TYPE_CHECKING:
@@ -35,6 +34,11 @@ class RecordingAxes:
     >>> # The call is recorded automatically
     """
 
+    # Methods whose results can be referenced by other methods (e.g., clabel needs ContourSet)
+    RESULT_REFERENCEABLE_METHODS = {"contour", "contourf"}
+    # Methods that take results from other methods as arguments
+    RESULT_REFERENCING_METHODS = {"clabel"}
+
     def __init__(
         self,
         ax: Axes,
@@ -45,6 +49,8 @@ class RecordingAxes:
         self._recorder = recorder
         self._position = position
         self._track = True
+        # Map matplotlib result objects (by id) to their source call_id
+        self._result_refs: Dict[int, str] = {}
 
     @property
     def ax(self) -> Axes:
@@ -73,95 +79,60 @@ class RecordingAxes:
         return attr
 
     def _create_recording_wrapper(self, method_name: str, method: callable):
-        """Create a wrapper function that records the call.
-
-        Parameters
-        ----------
-        method_name : str
-            Name of the method.
-        method : callable
-            The original method.
+        """Create a wrapper function that records the call."""
+        from ._axes_helpers import record_call_with_color_capture
 
-        Returns
-        -------
-        callable
-            Wrapped method that records calls.
-        """
         def wrapper(*args, id: Optional[str] = None, track: bool = True, **kwargs):
-            # Call the original method first (without our custom kwargs)
             result = method(*args, **kwargs)
-
-            # Record the call if tracking is enabled
             if self._track and track:
-                # Capture actual colors from result for plotting methods
-                # that use matplotlib's color cycle
-                recorded_kwargs = kwargs.copy()
-                if method_name in ('plot', 'scatter', 'bar', 'barh', 'step', 'fill_between'):
-                    if 'color' not in recorded_kwargs and 'c' not in recorded_kwargs:
-                        actual_color = self._extract_color_from_result(method_name, result)
-                        if actual_color is not None:
-                            recorded_kwargs['color'] = actual_color
-
-                self._recorder.record_call(
-                    ax_position=self._position,
-                    method_name=method_name,
-                    args=args,
-                    kwargs=recorded_kwargs,
-                    call_id=id,
+                record_call_with_color_capture(
+                    self._recorder,
+                    self._position,
+                    method_name,
+                    args,
+                    kwargs,
+                    result,
+                    id,
+                    self._result_refs,
+                    self.RESULT_REFERENCING_METHODS,
+                    self.RESULT_REFERENCEABLE_METHODS,
                 )
-
             return result
 
         return wrapper
 
-    def _extract_color_from_result(self, method_name: str, result) -> Optional[str]:
-        """Extract actual color used from plot result.
+    def set_caption(self, caption: str) -> "RecordingAxes":
+        """Set panel caption metadata (not rendered, stored in recipe).
+
+        This is for storing a description for this panel/axis,
+        typically used in multi-panel scientific figures
+        (e.g., "(A) Control group measurements").
 
         Parameters
         ----------
-        method_name : str
-            Name of the plotting method.
-        result : Any
-            Return value from the plotting method.
+        caption : str
+            The panel caption text.
 
         Returns
         -------
-        str or None
-            The color used, or None if not extractable.
+        RecordingAxes
+            Self for method chaining.
+
+        Examples
+        --------
+        >>> fig, axes = fr.subplots(1, 2)
+        >>> axes[0].set_caption("(A) Control group")
+        >>> axes[1].set_caption("(B) Treatment group")
         """
-        try:
-            if method_name == 'plot':
-                # plot() returns list of Line2D
-                if result and hasattr(result[0], 'get_color'):
-                    return result[0].get_color()
-            elif method_name == 'scatter':
-                # scatter() returns PathCollection
-                if hasattr(result, 'get_facecolor'):
-                    fc = result.get_facecolor()
-                    if len(fc) > 0:
-                        # Convert RGBA to hex
-                        import matplotlib.colors as mcolors
-                        return mcolors.to_hex(fc[0])
-            elif method_name in ('bar', 'barh'):
-                # bar() returns BarContainer
-                if hasattr(result, 'patches') and result.patches:
-                    fc = result.patches[0].get_facecolor()
-                    import matplotlib.colors as mcolors
-                    return mcolors.to_hex(fc)
-            elif method_name == 'step':
-                # step() returns list of Line2D
-                if result and hasattr(result[0], 'get_color'):
-                    return result[0].get_color()
-            elif method_name == 'fill_between':
-                # fill_between() returns PolyCollection
-                if hasattr(result, 'get_facecolor'):
-                    fc = result.get_facecolor()
-                    if len(fc) > 0:
-                        import matplotlib.colors as mcolors
-                        return mcolors.to_hex(fc[0])
-        except Exception:
-            pass
-        return None
+        ax_record = self._recorder.figure_record.get_or_create_axes(*self._position)
+        ax_record.caption = caption
+        return self
+
+    @property
+    def panel_caption(self) -> Optional[str]:
+        """Get the panel caption metadata."""
+        ax_record = self._recorder.figure_record.get_or_create_axes(*self._position)
+        return ax_record.caption
 
     def no_record(self):
         """Context manager to temporarily disable recording.
@@ -181,105 +152,21 @@ class RecordingAxes:
         data_arrays: Dict[str, np.ndarray],
         call_id: Optional[str] = None,
     ) -> None:
-        """Record a seaborn plotting call.
-
-        Parameters
-        ----------
-        func_name : str
-            Name of the seaborn function (e.g., 'scatterplot').
-        args : tuple
-            Processed positional arguments.
-        kwargs : dict
-            Processed keyword arguments.
-        data_arrays : dict
-            Dictionary of array data extracted from DataFrame/arrays.
-        call_id : str, optional
-            Custom ID for this call.
-        """
+        """Record a seaborn plotting call."""
         if not self._track:
             return
 
-        from .._utils._numpy_io import should_store_inline, to_serializable
-
-        # Generate call ID if not provided
-        if call_id is None:
-            call_id = self._recorder._generate_call_id(f"sns_{func_name}")
-
-        # Process data arrays into args format
-        processed_args = []
-        for i, arg in enumerate(args):
-            if arg == "__ARRAY__":
-                key = f"_arg_{i}"
-                if key in data_arrays:
-                    arr = data_arrays[key]
-                    if should_store_inline(arr):
-                        processed_args.append({
-                            "name": f"arg{i}",
-                            "data": to_serializable(arr),
-                            "dtype": str(arr.dtype),
-                        })
-                    else:
-                        processed_args.append({
-                            "name": f"arg{i}",
-                            "data": "__FILE__",
-                            "dtype": str(arr.dtype),
-                            "_array": arr,
-                        })
-            else:
-                processed_args.append({
-                    "name": f"arg{i}",
-                    "data": arg,
-                })
-
-        # Process DataFrame column data
-        for key, arr in data_arrays.items():
-            if key.startswith("_col_"):
-                param_name = key[5:]  # Remove "_col_" prefix
-                col_name = data_arrays.get(f"_colname_{param_name}", param_name)
-                if should_store_inline(arr):
-                    processed_args.append({
-                        "name": col_name,
-                        "param": param_name,
-                        "data": to_serializable(arr),
-                        "dtype": str(arr.dtype),
-                    })
-                else:
-                    processed_args.append({
-                        "name": col_name,
-                        "param": param_name,
-                        "data": "__FILE__",
-                        "dtype": str(arr.dtype),
-                        "_array": arr,
-                    })
-
-        # Process kwarg arrays
-        processed_kwargs = dict(kwargs)
-        for key, value in kwargs.items():
-            if value == "__ARRAY__":
-                arr_key = f"_kwarg_{key}"
-                if arr_key in data_arrays:
-                    arr = data_arrays[arr_key]
-                    if should_store_inline(arr):
-                        processed_kwargs[key] = to_serializable(arr)
-                    else:
-                        # Mark for file storage
-                        processed_kwargs[key] = "__FILE__"
-                        processed_kwargs[f"_array_{key}"] = arr
-
-        # Create call record
-        from .._recorder import CallRecord
-
-        record = CallRecord(
-            id=call_id,
-            function=f"sns.{func_name}",
-            args=processed_args,
-            kwargs=processed_kwargs,
-            ax_position=self._position,
-        )
+        from ._axes_seaborn import record_seaborn_call
 
-        # Add to axes record
-        ax_record = self._recorder.figure_record.get_or_create_axes(*self._position)
-        ax_record.add_call(record)
+        record_seaborn_call(
+            self._recorder,
+            self._position,
+            func_name,
+            args,
+            kwargs,
+            data_arrays,
+            call_id,
+        )
 
     # Expose common properties directly
     @property
@@ -294,6 +181,73 @@ class RecordingAxes:
     def yaxis(self):
         return self._ax.yaxis
 
+    def pie(
+        self,
+        x,
+        *,
+        id: Optional[str] = None,
+        track: bool = True,
+        **kwargs,
+    ):
+        """Pie chart with automatic SCITEX styling."""
+        from ._axes_plots import pie_plot
+
+        return pie_plot(
+            self._ax,
+            x,
+            self._recorder,
+            self._position,
+            self._track and track,
+            id,
+            **kwargs,
+        )
+
+    def imshow(
+        self,
+        X,
+        *,
+        id: Optional[str] = None,
+        track: bool = True,
+        **kwargs,
+    ):
+        """Display image with automatic SCITEX styling."""
+        from ._axes_plots import imshow_plot
+
+        return imshow_plot(
+            self._ax,
+            X,
+            self._recorder,
+            self._position,
+            self._track and track,
+            id,
+            **kwargs,
+        )
+
+    def violinplot(
+        self,
+        dataset,
+        positions=None,
+        *,
+        id: Optional[str] = None,
+        track: bool = True,
+        inner: Optional[str] = None,
+        **kwargs,
+    ):
+        """Violin plot with support for inner display options."""
+        from ._axes_plots import violinplot_plot
+
+        return violinplot_plot(
+            self._ax,
+            dataset,
+            positions,
+            self._recorder,
+            self._position,
+            self._track and track,
+            id,
+            inner,
+            **kwargs,
+        )
+
     # Methods that should not be recorded
     def get_xlim(self):
         return self._ax.get_xlim()
@@ -310,6 +264,75 @@ class RecordingAxes:
     def get_title(self):
         return self._ax.get_title()
 
+    def joyplot(
+        self,
+        arrays,
+        *,
+        overlap: float = 0.5,
+        fill_alpha: float = 0.7,
+        line_alpha: float = 1.0,
+        colors=None,
+        labels=None,
+        id: Optional[str] = None,
+        track: bool = True,
+        **kwargs,
+    ):
+        """Create a joyplot (ridgeline plot) for distribution comparison."""
+        from ._axes_plots import joyplot_plot
+
+        return joyplot_plot(
+            self._ax,
+            self,
+            arrays,
+            self._recorder,
+            self._position,
+            self._track and track,
+            id,
+            overlap,
+            fill_alpha,
+            line_alpha,
+            colors,
+            labels,
+            **kwargs,
+        )
+
+    def swarmplot(
+        self,
+        data,
+        positions=None,
+        *,
+        size: float = None,
+        color=None,
+        alpha: float = 0.7,
+        jitter: float = 0.3,
+        id: Optional[str] = None,
+        track: bool = True,
+        **kwargs,
+    ):
+        """Create a swarm plot (beeswarm plot) showing individual data points."""
+        from ._axes_plots import swarmplot_plot
+
+        return swarmplot_plot(
+            self._ax,
+            data,
+            positions,
+            self._recorder,
+            self._position,
+            self._track and track,
+            id,
+            size,
+            color,
+            alpha,
+            jitter,
+            **kwargs,
+        )
+
+    @property
+    def caption(self) -> Optional[str]:
+        """Get the panel caption metadata."""
+        ax_record = self._recorder.figure_record.get_or_create_axes(*self._position)
+        return ax_record.caption
+
 
 class _NoRecordContext:
     """Context manager to temporarily disable recording."""

figrecipe/_wrappers/_axes_helpers.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Helper functions for RecordingAxes."""
+
+from typing import Any, Dict, Optional
+
+
+def args_have_fmt_color(args: tuple) -> bool:
+    """Check if args contain a matplotlib fmt string with color specifier."""
+    color_codes = set("bgrcmykw")
+    for arg in args:
+        if isinstance(arg, str) and len(arg) >= 1 and len(arg) <= 4:
+            if arg[0] in color_codes:
+                return True
+    return False
+
+
+def extract_color_from_result(method_name: str, result) -> Optional[str]:
+    """Extract actual color used from plot result."""
+    try:
+        if method_name == "plot":
+            if result and hasattr(result[0], "get_color"):
+                return result[0].get_color()
+        elif method_name == "scatter":
+            if hasattr(result, "get_facecolor"):
+                fc = result.get_facecolor()
+                if len(fc) > 0:
+                    import matplotlib.colors as mcolors
+
+                    return mcolors.to_hex(fc[0])
+        elif method_name in ("bar", "barh"):
+            if hasattr(result, "patches") and result.patches:
+                fc = result.patches[0].get_facecolor()
+                import matplotlib.colors as mcolors
+
+                return mcolors.to_hex(fc)
+        elif method_name == "step":
+            if result and hasattr(result[0], "get_color"):
+                return result[0].get_color()
+        elif method_name == "fill_between":
+            if hasattr(result, "get_facecolor"):
+                fc = result.get_facecolor()
+                if len(fc) > 0:
+                    import matplotlib.colors as mcolors
+
+                    return mcolors.to_hex(fc[0])
+    except Exception:
+        pass
+    return None
+
+
+def process_result_refs_in_args(
+    args: tuple,
+    method_name: str,
+    result_refs: Dict[int, str],
+    referencing_methods: set,
+) -> tuple:
+    """Process args to replace matplotlib objects with references."""
+    if method_name not in referencing_methods:
+        return args
+
+    import builtins
+
+    processed = []
+    for arg in args:
+        obj_id = builtins.id(arg)
+        if obj_id in result_refs:
+            processed.append({"__ref__": result_refs[obj_id]})
+        else:
+            processed.append(arg)
+    return tuple(processed)
+
+
+def record_call_with_color_capture(
+    recorder,
+    position: tuple,
+    method_name: str,
+    args: tuple,
+    kwargs: dict,
+    result,
+    call_id: Optional[str],
+    result_refs: Dict[int, str],
+    referencing_methods: set,
+    referenceable_methods: set,
+) -> Any:
+    """Record a call with color capture and result reference handling."""
+    recorded_kwargs = kwargs.copy()
+
+    # Capture colors for methods using color cycle
+    if method_name in ("plot", "scatter", "bar", "barh", "step", "fill_between"):
+        has_fmt_color = args_have_fmt_color(args)
+        if (
+            "color" not in recorded_kwargs
+            and "c" not in recorded_kwargs
+            and not has_fmt_color
+        ):
+            actual_color = extract_color_from_result(method_name, result)
+            if actual_color is not None:
+                recorded_kwargs["color"] = actual_color
+
+        if method_name == "fill_between" and "edgecolor" not in recorded_kwargs:
+            if hasattr(result, "get_edgecolor"):
+                ec = result.get_edgecolor()
+                if len(ec) == 0:
+                    recorded_kwargs["edgecolor"] = "none"
+
+    # Process args for result references
+    processed_args = process_result_refs_in_args(
+        args, method_name, result_refs, referencing_methods
+    )
+
+    call_record = recorder.record_call(
+        ax_position=position,
+        method_name=method_name,
+        args=processed_args,
+        kwargs=recorded_kwargs,
+        call_id=call_id,
+    )
+
+    # Store result reference if applicable
+    if method_name in referenceable_methods:
+        import builtins
+
+        result_refs[builtins.id(result)] = call_record.id
+
+    return call_record
+
+
+__all__ = [
+    "args_have_fmt_color",
+    "extract_color_from_result",
+    "process_result_refs_in_args",
+    "record_call_with_color_capture",
+]
+
+# EOF