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

figrecipe/_wrappers/_axes.py

@@ -79,179 +79,113 @@ 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.
-
-        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)
+        """Create a wrapper function that records the call."""
+        from ._axes_helpers import record_call_with_color_capture
+
+        def wrapper(
+            *args,
+            id: Optional[str] = None,
+            track: bool = True,
+            stats: Optional[Dict[str, Any]] = None,
+            **kwargs,
+        ):
+            # Call matplotlib method (without stats - it's metadata only)
             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",
-                ):
-                    # Check if fmt string already specifies color (e.g., "b-", "r--")
-                    has_fmt_color = self._args_have_fmt_color(args)
-                    if (
-                        "color" not in recorded_kwargs
-                        and "c" not in recorded_kwargs
-                        and not has_fmt_color
-                    ):
-                        actual_color = self._extract_color_from_result(
-                            method_name, result
-                        )
-                        if actual_color is not None:
-                            recorded_kwargs["color"] = actual_color
-
-                # Process args to detect result references (e.g., clabel's ContourSet)
-                processed_args = self._process_result_refs_in_args(args, method_name)
-
-                call_record = self._recorder.record_call(
-                    ax_position=self._position,
-                    method_name=method_name,
-                    args=processed_args,
-                    kwargs=recorded_kwargs,
-                    call_id=id,
+                # Re-add stats to kwargs for recording
+                record_kwargs = kwargs.copy()
+                if stats is not None:
+                    record_kwargs["stats"] = stats
+                record_call_with_color_capture(
+                    self._recorder,
+                    self._position,
+                    method_name,
+                    args,
+                    record_kwargs,
+                    result,
+                    id,
+                    self._result_refs,
+                    self.RESULT_REFERENCING_METHODS,
+                    self.RESULT_REFERENCEABLE_METHODS,
                 )
-
-                # Store result reference for methods whose results can be used later
-                if method_name in self.RESULT_REFERENCEABLE_METHODS:
-                    import builtins
-
-                    self._result_refs[builtins.id(result)] = call_record.id
-
             return result
 
         return wrapper
 
-    def _process_result_refs_in_args(self, args: tuple, method_name: str) -> tuple:
-        """Process args to replace matplotlib objects with references.
+    def set_caption(self, caption: str) -> "RecordingAxes":
+        """Set panel caption metadata (not rendered, stored in recipe).
 
-        For methods like clabel that take a ContourSet as argument,
-        replace the object with a reference to the original call_id.
+        This is for storing a description for this panel/axis,
+        typically used in multi-panel scientific figures
+        (e.g., "(A) Control group measurements").
 
         Parameters
         ----------
-        args : tuple
-            Original arguments.
-        method_name : str
-            Name of the method.
+        caption : str
+            The panel caption text.
 
         Returns
         -------
-        tuple
-            Processed args with references.
-        """
-        if method_name not in self.RESULT_REFERENCING_METHODS:
-            return args
+        RecordingAxes
+            Self for method chaining.
 
-        import builtins
+        Examples
+        --------
+        >>> fig, axes = fr.subplots(1, 2)
+        >>> axes[0].set_caption("(A) Control group")
+        >>> axes[1].set_caption("(B) Treatment group")
+        """
+        ax_record = self._recorder.figure_record.get_or_create_axes(*self._position)
+        ax_record.caption = caption
+        return self
 
-        processed = []
-        for i, arg in enumerate(args):
-            obj_id = builtins.id(arg)
-            if obj_id in self._result_refs:
-                # This arg is a reference to a previous call's result
-                processed.append({"__ref__": self._result_refs[obj_id]})
-            else:
-                processed.append(arg)
-        return tuple(processed)
+    @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 _args_have_fmt_color(self, args: tuple) -> bool:
-        """Check if args contain a matplotlib fmt string with color specifier.
+    def set_stats(self, stats: Dict[str, Any]) -> "RecordingAxes":
+        """Set panel-level statistics metadata (not rendered, stored in recipe).
 
-        Fmt strings like "b-", "r--", "go" contain color codes (b,g,r,c,m,y,k,w).
+        This is for storing statistical summary or comparison results
+        for this panel/axis, such as group means, sample sizes, or
+        comparison p-values.
 
         Parameters
         ----------
-        args : tuple
-            Arguments passed to plot method.
+        stats : dict
+            Statistics dictionary. Common keys include:
+            - n: sample size
+            - mean: mean value
+            - std: standard deviation
+            - sem: standard error of the mean
+            - comparisons: list of comparison results
 
         Returns
         -------
-        bool
-            True if a fmt string with color is found.
-        """
-        color_codes = set("bgrcmykw")
-        for arg in args:
-            if isinstance(arg, str) and len(arg) >= 1 and len(arg) <= 4:
-                # Fmt strings are short (e.g., "b-", "r--", "go", "k:")
-                if arg[0] in color_codes:
-                    return True
-        return False
-
-    def _extract_color_from_result(self, method_name: str, result) -> Optional[str]:
-        """Extract actual color used from plot result.
-
-        Parameters
-        ----------
-        method_name : str
-            Name of the plotting method.
-        result : Any
-            Return value from the plotting method.
+        RecordingAxes
+            Self for method chaining.
 
-        Returns
-        -------
-        str or None
-            The color used, or None if not extractable.
+        Examples
+        --------
+        >>> fig, axes = fr.subplots(1, 2)
+        >>> axes[0].set_stats({"n": 50, "mean": 3.2, "std": 1.1})
+        >>> axes[1].set_stats({
+        ...     "n": 48,
+        ...     "mean": 5.1,
+        ...     "comparisons": [{"vs": "control", "p_value": 0.003}]
+        ... })
         """
-        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.stats = stats
+        return self
+
+    @property
+    def stats(self) -> Optional[Dict[str, Any]]:
+        """Get the panel-level statistics metadata."""
+        ax_record = self._recorder.figure_record.get_or_create_axes(*self._position)
+        return ax_record.stats
 
     def no_record(self):
         """Context manager to temporarily disable recording.
@@ -271,116 +205,22 @@ 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,
-                    }
-                )
+        from ._axes_seaborn import record_seaborn_call
 
-        # 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,
+        record_seaborn_call(
+            self._recorder,
+            self._position,
+            func_name,
+            args,
+            kwargs,
+            data_arrays,
+            call_id,
         )
 
-        # Add to axes record
-        ax_record = self._recorder.figure_record.get_or_create_axes(*self._position)
-        ax_record.add_call(record)
-
     # Expose common properties directly
     @property
     def figure(self):
@@ -402,64 +242,18 @@ class RecordingAxes:
         track: bool = True,
         **kwargs,
     ):
-        """Pie chart with automatic SCITEX styling.
-
-        Parameters
-        ----------
-        x : array-like
-            Wedge sizes.
-        id : str, optional
-            Custom ID for this call.
-        track : bool, optional
-            Whether to record this call (default: True).
-        **kwargs
-            Additional arguments passed to matplotlib's pie.
-
-        Returns
-        -------
-        tuple
-            (patches, texts) or (patches, texts, autotexts) if autopct is set.
-        """
-        from ..styles import get_style
-        from ..styles._style_applier import check_font
-
-        # Call matplotlib's pie
-        result = self._ax.pie(x, **kwargs)
-
-        # Get style settings
-        style = get_style()
-        if style:
-            pie_style = style.get("pie", {})
-            text_pt = pie_style.get("text_pt", 6)
-            show_axes = pie_style.get("show_axes", False)
-            font_family = check_font(style.get("fonts", {}).get("family", "Arial"))
-
-            # Apply text size to all pie text elements (labels and percentages)
-            for text in self._ax.texts:
-                text.set_fontsize(text_pt)
-                text.set_fontfamily(font_family)
-
-            # Hide axes if configured (default: hide for pie charts)
-            if not show_axes:
-                self._ax.set_xticks([])
-                self._ax.set_yticks([])
-                self._ax.set_xticklabels([])
-                self._ax.set_yticklabels([])
-                # Hide spines
-                for spine in self._ax.spines.values():
-                    spine.set_visible(False)
-
-        # Record the call if tracking is enabled
-        if self._track and track:
-            self._recorder.record_call(
-                ax_position=self._position,
-                method_name="pie",
-                args=(x,),
-                kwargs=kwargs,
-                call_id=id,
-            )
-
-        return result
+        """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,
@@ -469,61 +263,18 @@ class RecordingAxes:
         track: bool = True,
         **kwargs,
     ):
-        """Display image with automatic SCITEX styling.
-
-        Parameters
-        ----------
-        X : array-like
-            Image data.
-        id : str, optional
-            Custom ID for this call.
-        track : bool, optional
-            Whether to record this call (default: True).
-        **kwargs
-            Additional arguments passed to matplotlib's imshow.
-
-        Returns
-        -------
-        AxesImage
-            The created image.
-        """
-        from ..styles import get_style
-
-        # Call matplotlib's imshow
-        result = self._ax.imshow(X, **kwargs)
-
-        # Get style settings
-        style = get_style()
-        if style:
-            imshow_style = style.get("imshow", {})
-            show_axes = imshow_style.get("show_axes", True)
-            show_labels = imshow_style.get("show_labels", True)
-
-            # Hide axes if configured
-            if not show_axes:
-                self._ax.set_xticks([])
-                self._ax.set_yticks([])
-                self._ax.set_xticklabels([])
-                self._ax.set_yticklabels([])
-                # Hide spines
-                for spine in self._ax.spines.values():
-                    spine.set_visible(False)
-
-            if not show_labels:
-                self._ax.set_xlabel("")
-                self._ax.set_ylabel("")
-
-        # Record the call if tracking is enabled
-        if self._track and track:
-            self._recorder.record_call(
-                ax_position=self._position,
-                method_name="imshow",
-                args=(X,),
-                kwargs=kwargs,
-                call_id=id,
-            )
-
-        return result
+        """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,
@@ -535,238 +286,21 @@ class RecordingAxes:
         inner: Optional[str] = None,
         **kwargs,
     ):
-        """Violin plot with support for inner display options.
-
-        Parameters
-        ----------
-        dataset : array-like
-            Data to plot.
-        positions : array-like, optional
-            Position of each violin on x-axis.
-        id : str, optional
-            Custom ID for this call.
-        track : bool, optional
-            Whether to record this call (default: True).
-        inner : str, optional
-            Inner display type: "box", "quartile", "stick", "point", "swarm", or None.
-            Default is from style config (SCITEX default: "box").
-        **kwargs
-            Additional arguments passed to matplotlib's violinplot.
-
-        Returns
-        -------
-        dict
-            Dictionary with violin parts (bodies, cbars, cmins, cmaxes, cmeans, cmedians).
-        """
-        from ..styles import get_style
-
-        # Get style settings
-        style = get_style()
-        violin_style = style.get("violinplot", {}) if style else {}
-
-        # Determine inner type (user kwarg > style config > default)
-        if inner is None:
-            inner = violin_style.get("inner", "box")
+        """Violin plot with support for inner display options."""
+        from ._axes_plots import violinplot_plot
 
-        # Get violin display options from style
-        showmeans = kwargs.pop("showmeans", violin_style.get("showmeans", False))
-        showmedians = kwargs.pop("showmedians", violin_style.get("showmedians", True))
-        showextrema = kwargs.pop("showextrema", violin_style.get("showextrema", False))
-
-        # Call matplotlib's violinplot
-        result = self._ax.violinplot(
+        return violinplot_plot(
+            self._ax,
             dataset,
-            positions=positions,
-            showmeans=showmeans,
-            showmedians=showmedians if inner not in ("box", "swarm") else False,
-            showextrema=showextrema if inner not in ("box", "swarm") else False,
+            positions,
+            self._recorder,
+            self._position,
+            self._track and track,
+            id,
+            inner,
             **kwargs,
         )
 
-        # Apply alpha from style to violin bodies
-        alpha = violin_style.get("alpha", 0.7)
-        if "bodies" in result:
-            for body in result["bodies"]:
-                body.set_alpha(alpha)
-
-        # Overlay inner elements based on inner type
-        if positions is None:
-            positions = list(range(1, len(dataset) + 1))
-
-        if inner == "box":
-            self._add_violin_inner_box(dataset, positions, violin_style)
-        elif inner == "swarm":
-            self._add_violin_inner_swarm(dataset, positions, violin_style)
-        elif inner == "quartile":
-            # quartile lines are handled by showmedians + showextrema
-            pass
-        elif inner == "stick":
-            self._add_violin_inner_stick(dataset, positions, violin_style)
-        elif inner == "point":
-            self._add_violin_inner_point(dataset, positions, violin_style)
-
-        # Record the call if tracking is enabled
-        if self._track and track:
-            recorded_kwargs = kwargs.copy()
-            recorded_kwargs["inner"] = inner
-            recorded_kwargs["showmeans"] = showmeans
-            recorded_kwargs["showmedians"] = showmedians
-            recorded_kwargs["showextrema"] = showextrema
-
-            self._recorder.record_call(
-                ax_position=self._position,
-                method_name="violinplot",
-                args=(dataset,),
-                kwargs=recorded_kwargs,
-                call_id=id,
-            )
-
-        return result
-
-    def _add_violin_inner_box(self, dataset, positions, style: Dict[str, Any]) -> None:
-        """Add box plot inside violin.
-
-        Parameters
-        ----------
-        dataset : array-like
-            Data arrays for each violin.
-        positions : array-like
-            X positions of violins.
-        style : dict
-            Violin style configuration.
-        """
-        from ..styles._style_applier import mm_to_pt
-
-        whisker_lw = mm_to_pt(style.get("whisker_mm", 0.2))
-        median_size = mm_to_pt(style.get("median_mm", 0.8))
-
-        for i, (data, pos) in enumerate(zip(dataset, positions)):
-            data = np.asarray(data)
-            q1, median, q3 = np.percentile(data, [25, 50, 75])
-            iqr = q3 - q1
-            whisker_low = max(data.min(), q1 - 1.5 * iqr)
-            whisker_high = min(data.max(), q3 + 1.5 * iqr)
-
-            # Draw box (Q1 to Q3)
-            self._ax.vlines(
-                pos, q1, q3, colors="black", linewidths=whisker_lw, zorder=3
-            )
-            # Draw whiskers
-            self._ax.vlines(
-                pos,
-                whisker_low,
-                q1,
-                colors="black",
-                linewidths=whisker_lw * 0.5,
-                zorder=3,
-            )
-            self._ax.vlines(
-                pos,
-                q3,
-                whisker_high,
-                colors="black",
-                linewidths=whisker_lw * 0.5,
-                zorder=3,
-            )
-            # Draw median as a white dot with black edge
-            self._ax.scatter(
-                [pos],
-                [median],
-                s=median_size**2,
-                c="white",
-                edgecolors="black",
-                linewidths=whisker_lw,
-                zorder=4,
-            )
-
-    def _add_violin_inner_swarm(
-        self, dataset, positions, style: Dict[str, Any]
-    ) -> None:
-        """Add swarm points inside violin.
-
-        Parameters
-        ----------
-        dataset : array-like
-            Data arrays for each violin.
-        positions : array-like
-            X positions of violins.
-        style : dict
-            Violin style configuration.
-        """
-        from ..styles._style_applier import mm_to_pt
-
-        point_size = mm_to_pt(style.get("median_mm", 0.8))
-
-        for data, pos in zip(dataset, positions):
-            data = np.asarray(data)
-            n = len(data)
-
-            # Simple swarm: jitter x positions
-            # More sophisticated swarm would avoid overlaps
-            jitter = np.random.default_rng(42).uniform(-0.15, 0.15, n)
-            x_positions = pos + jitter
-
-            self._ax.scatter(
-                x_positions, data, s=point_size**2, c="black", alpha=0.5, zorder=3
-            )
-
-    def _add_violin_inner_stick(
-        self, dataset, positions, style: Dict[str, Any]
-    ) -> None:
-        """Add stick (line) markers inside violin for each data point.
-
-        Parameters
-        ----------
-        dataset : array-like
-            Data arrays for each violin.
-        positions : array-like
-            X positions of violins.
-        style : dict
-            Violin style configuration.
-        """
-        from ..styles._style_applier import mm_to_pt
-
-        lw = mm_to_pt(style.get("whisker_mm", 0.2))
-
-        for data, pos in zip(dataset, positions):
-            data = np.asarray(data)
-            # Draw short horizontal lines at each data point
-            for val in data:
-                self._ax.hlines(
-                    val,
-                    pos - 0.05,
-                    pos + 0.05,
-                    colors="black",
-                    linewidths=lw * 0.5,
-                    alpha=0.3,
-                    zorder=3,
-                )
-
-    def _add_violin_inner_point(
-        self, dataset, positions, style: Dict[str, Any]
-    ) -> None:
-        """Add point markers inside violin for each data point.
-
-        Parameters
-        ----------
-        dataset : array-like
-            Data arrays for each violin.
-        positions : array-like
-            X positions of violins.
-        style : dict
-            Violin style configuration.
-        """
-        from ..styles._style_applier import mm_to_pt
-
-        point_size = mm_to_pt(style.get("median_mm", 0.8)) * 0.5
-
-        for data, pos in zip(dataset, positions):
-            data = np.asarray(data)
-            x_positions = np.full_like(data, pos)
-            self._ax.scatter(
-                x_positions, data, s=point_size**2, c="black", alpha=0.3, zorder=3
-            )
-
     # Methods that should not be recorded
     def get_xlim(self):
         return self._ax.get_xlim()
@@ -796,158 +330,24 @@ class RecordingAxes:
         track: bool = True,
         **kwargs,
     ):
-        """Create a joyplot (ridgeline plot) for distribution comparison.
-
-        Parameters
-        ----------
-        arrays : list of array-like or dict
-            List of 1D arrays for each ridge. If dict, uses values.
-        overlap : float, default 0.5
-            Amount of overlap between ridges (0 = no overlap, 1 = full overlap).
-        fill_alpha : float, default 0.7
-            Alpha for the filled KDE area.
-        line_alpha : float, default 1.0
-            Alpha for the KDE line.
-        colors : list, optional
-            Colors for each ridge. If None, uses color cycle.
-        labels : list of str, optional
-            Labels for each ridge (for y-axis).
-        id : str, optional
-            Custom ID for this call.
-        track : bool, optional
-            Whether to record this call (default: True).
-        **kwargs
-            Additional arguments.
-
-        Returns
-        -------
-        RecordingAxes
-            Self for method chaining.
-
-        Examples
-        --------
-        >>> ax.joyplot([data1, data2, data3], overlap=0.5)
-        >>> ax.joyplot({"A": arr_a, "B": arr_b}, labels=["A", "B"])
-        """
-        from scipy import stats
-
-        from .._utils._units import mm_to_pt
-        from ..styles import get_style
-
-        # Convert dict to list of arrays
-        if isinstance(arrays, dict):
-            if labels is None:
-                labels = list(arrays.keys())
-            arrays = list(arrays.values())
-
-        n_ridges = len(arrays)
-
-        # Get colors from style or use default cycle
-        if colors is None:
-            style = get_style()
-            if style and "colors" in style and "palette" in style.colors:
-                palette = list(style.colors.palette)
-                # Normalize RGB 0-255 to 0-1
-                colors = []
-                for c in palette:
-                    if isinstance(c, (list, tuple)) and len(c) >= 3:
-                        if all(v <= 1.0 for v in c):
-                            colors.append(tuple(c))
-                        else:
-                            colors.append(tuple(v / 255.0 for v in c))
-                    else:
-                        colors.append(c)
-            else:
-                # Matplotlib default color cycle
-                import matplotlib.pyplot as plt
-
-                colors = [c["color"] for c in plt.rcParams["axes.prop_cycle"]]
-
-        # Calculate global x range
-        all_data = np.concatenate([np.asarray(arr) for arr in arrays])
-        x_min, x_max = np.min(all_data), np.max(all_data)
-        x_range = x_max - x_min
-        x_padding = x_range * 0.1
-        x = np.linspace(x_min - x_padding, x_max + x_padding, 200)
-
-        # Calculate KDEs and find max density for scaling
-        kdes = []
-        max_density = 0
-        for arr in arrays:
-            arr = np.asarray(arr)
-            if len(arr) > 1:
-                kde = stats.gaussian_kde(arr)
-                density = kde(x)
-                kdes.append(density)
-                max_density = max(max_density, np.max(density))
-            else:
-                kdes.append(np.zeros_like(x))
-
-        # Scale factor for ridge height
-        ridge_height = 1.0 / (1.0 - overlap * 0.5) if overlap < 1 else 2.0
-
-        # Get line width from style
-        style = get_style()
-        lw = mm_to_pt(0.2)  # Default
-        if style and "lines" in style:
-            lw = mm_to_pt(style.lines.get("trace_mm", 0.2))
-
-        # Plot each ridge from back to front
-        for i in range(n_ridges - 1, -1, -1):
-            color = colors[i % len(colors)]
-            baseline = i * (1.0 - overlap)
-
-            # Scale density to fit nicely
-            scaled_density = (
-                kdes[i] / max_density * ridge_height if max_density > 0 else kdes[i]
-            )
-
-            # Fill
-            self._ax.fill_between(
-                x,
-                baseline,
-                baseline + scaled_density,
-                facecolor=color,
-                edgecolor="none",
-                alpha=fill_alpha,
-            )
-            # Line on top
-            self._ax.plot(
-                x,
-                baseline + scaled_density,
-                color=color,
-                alpha=line_alpha,
-                linewidth=lw,
-            )
-
-        # Set y limits
-        self._ax.set_ylim(-0.1, n_ridges * (1.0 - overlap) + ridge_height)
-
-        # Set y-axis labels if provided
-        if labels:
-            y_positions = [(i * (1.0 - overlap)) + 0.3 for i in range(n_ridges)]
-            self._ax.set_yticks(y_positions)
-            self._ax.set_yticklabels(labels)
-        else:
-            # Hide y-axis ticks for cleaner look
-            self._ax.set_yticks([])
-
-        # Record the call if tracking is enabled
-        if self._track and track:
-            self._recorder.record_call(
-                ax_position=self._position,
-                method_name="joyplot",
-                args=(arrays,),
-                kwargs={
-                    "overlap": overlap,
-                    "fill_alpha": fill_alpha,
-                    "line_alpha": line_alpha,
-                    "labels": labels,
-                },
-                call_id=id,
-            )
-
-        return self
+        """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,
@@ -962,167 +362,124 @@ class RecordingAxes:
         track: bool = True,
         **kwargs,
     ):
-        """Create a swarm plot (beeswarm plot) showing individual data points.
-
-        Parameters
-        ----------
-        data : list of array-like
-            List of 1D arrays to plot.
-        positions : array-like, optional
-            X positions for each swarm. Default is 1, 2, 3, ...
-        size : float, optional
-            Marker size in mm. Default from style config.
-        color : color or list of colors, optional
-            Colors for each swarm.
-        alpha : float, default 0.7
-            Transparency of markers.
-        jitter : float, default 0.3
-            Width of jitter spread (in data units).
-        id : str, optional
-            Custom ID for this call.
-        track : bool, optional
-            Whether to record this call (default: True).
-        **kwargs
-            Additional arguments passed to scatter.
-
-        Returns
-        -------
-        list
-            List of PathCollection objects.
+        """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,
+        )
 
-        Examples
-        --------
-        >>> ax.swarmplot([data1, data2, data3])
-        >>> ax.swarmplot([arr1, arr2], positions=[0, 1], color=['red', 'blue'])
-        """
-        from .._utils._units import mm_to_pt
-        from ..styles import get_style
-
-        # Get style
-        style = get_style()
-
-        # Default marker size from style
-        if size is None:
-            if style and "markers" in style:
-                size = style.markers.get("scatter_mm", 0.8)
-            else:
-                size = 0.8
-        size_pt = mm_to_pt(size) ** 2  # matplotlib uses area
-
-        # Get colors
-        if color is None:
-            if style and "colors" in style and "palette" in style.colors:
-                palette = list(style.colors.palette)
-                colors = []
-                for c in palette:
-                    if isinstance(c, (list, tuple)) and len(c) >= 3:
-                        if all(v <= 1.0 for v in c):
-                            colors.append(tuple(c))
-                        else:
-                            colors.append(tuple(v / 255.0 for v in c))
-                    else:
-                        colors.append(c)
-            else:
-                import matplotlib.pyplot as plt
-
-                colors = [c["color"] for c in plt.rcParams["axes.prop_cycle"]]
-        elif isinstance(color, list):
-            colors = color
-        else:
-            colors = [color] * len(data)
-
-        # Default positions
-        if positions is None:
-            positions = list(range(1, len(data) + 1))
-
-        # Random generator for reproducible jitter
-        rng = np.random.default_rng(42)
-
-        results = []
-        for i, (arr, pos) in enumerate(zip(data, positions)):
-            arr = np.asarray(arr)
-
-            # Create jittered x positions using beeswarm algorithm (simplified)
-            x_jitter = self._beeswarm_positions(arr, jitter, rng)
-            x_positions = pos + x_jitter
-
-            c = colors[i % len(colors)]
-            result = self._ax.scatter(
-                x_positions, arr, s=size_pt, c=[c], alpha=alpha, **kwargs
-            )
-            results.append(result)
+    @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
 
-        # Record the call if tracking is enabled
-        if self._track and track:
-            self._recorder.record_call(
-                ax_position=self._position,
-                method_name="swarmplot",
-                args=(data,),
-                kwargs={
-                    "positions": positions,
-                    "size": size,
-                    "alpha": alpha,
-                    "jitter": jitter,
-                },
-                call_id=id,
-            )
+    def generate_panel_caption(
+        self, label: Optional[str] = None, style: str = "publication"
+    ) -> str:
+        """Generate a caption for this panel from stats metadata."""
+        from ._caption_generator import generate_panel_caption
 
-        return results
+        return generate_panel_caption(label=label, stats=self.stats, style=style)
 
-    def _beeswarm_positions(
+    def add_stat_annotation(
         self,
-        data: np.ndarray,
-        width: float,
-        rng: np.random.Generator,
-    ) -> np.ndarray:
-        """Calculate beeswarm-style x positions to minimize overlap.
-
-        This is a simplified beeswarm that uses binning and jittering.
-        For a true beeswarm, we'd need to iteratively place points.
+        x1: float,
+        x2: float,
+        p_value: Optional[float] = None,
+        text: Optional[str] = None,
+        y: Optional[float] = None,
+        style: str = "stars",
+        bracket_height: Optional[float] = None,
+        text_offset: Optional[float] = None,
+        color: Optional[str] = None,
+        linewidth: Optional[float] = None,
+        fontsize: Optional[float] = None,
+        fontweight: Optional[str] = None,
+        id: Optional[str] = None,
+        track: bool = True,
+        **kwargs,
+    ):
+        """Add a statistical comparison annotation (bracket with stars/p-value).
 
         Parameters
         ----------
-        data : array
-            Y values of points.
-        width : float
-            Maximum jitter width.
-        rng : Generator
-            Random number generator.
-
-        Returns
-        -------
-        array
-            X offsets for each point.
+        x1, x2 : float
+            X positions of the two groups being compared.
+        p_value : float, optional
+            P-value for automatic star conversion.
+        text : str, optional
+            Custom text (overrides p_value formatting).
+        y : float, optional
+            Y position for bracket (auto-calculated if None).
+        style : str
+            "stars", "p_value", "both", or "bracket_only".
         """
-        n = len(data)
-        if n == 0:
-            return np.array([])
-
-        # Sort data and get order
-        order = np.argsort(data)
-        sorted_data = data[order]
-
-        # Group nearby points and offset them
-        x_offsets = np.zeros(n)
-
-        # Simple approach: bin by quantiles and spread within each bin
-        n_bins = max(1, int(np.sqrt(n)))
-        bin_edges = np.percentile(sorted_data, np.linspace(0, 100, n_bins + 1))
-
-        for i in range(n_bins):
-            mask = (sorted_data >= bin_edges[i]) & (sorted_data <= bin_edges[i + 1])
-            n_in_bin = mask.sum()
-            if n_in_bin > 0:
-                # Spread points evenly within bin width
-                offsets = np.linspace(-width / 2, width / 2, n_in_bin)
-                # Add small random noise
-                offsets += rng.uniform(-width * 0.1, width * 0.1, n_in_bin)
-                x_offsets[mask] = offsets
-
-        # Restore original order
-        result = np.zeros(n)
-        result[order] = x_offsets
-        return result
+        from ._stat_annotation import draw_stat_annotation
+
+        # Draw the annotation
+        artists = draw_stat_annotation(
+            self._ax,
+            x1,
+            x2,
+            y=y,
+            text=text,
+            p_value=p_value,
+            style=style,
+            bracket_height=bracket_height,
+            text_offset=text_offset,
+            color=color,
+            linewidth=linewidth,
+            fontsize=fontsize,
+            fontweight=fontweight,
+            **kwargs,
+        )
+
+        # Record if tracking
+        if self._track and track:
+            call_id = id if id else self._recorder._generate_call_id("stat_annotation")
+            record_kwargs = {
+                "x1": x1,
+                "x2": x2,
+                "p_value": p_value,
+                "text": text,
+                "y": y,
+                "style": style,
+                "bracket_height": bracket_height,
+                "text_offset": text_offset,
+                "color": color,
+                "linewidth": linewidth,
+                "fontsize": fontsize,
+            }
+            record_kwargs.update(kwargs)
+            # Remove None values
+            record_kwargs = {k: v for k, v in record_kwargs.items() if v is not None}
+
+            from .._recorder import CallRecord
+
+            record = CallRecord(
+                id=call_id,
+                function="stat_annotation",
+                args=[],
+                kwargs=record_kwargs,
+                ax_position=self._position,
+            )
+            ax_record = self._recorder.figure_record.get_or_create_axes(*self._position)
+            ax_record.add_decoration(record)
+
+        return artists
 
 
 class _NoRecordContext: