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

figrecipe/_recorder.py

@@ -25,16 +25,21 @@ class CallRecord:
     kwargs: Dict[str, Any]
     timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
     ax_position: Tuple[int, int] = (0, 0)
+    # Statistics associated with this plot call (e.g., n, mean, sem)
+    stats: Optional[Dict[str, Any]] = None
 
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary for serialization."""
-        return {
+        result = {
             "id": self.id,
             "function": self.function,
             "args": self.args,
             "kwargs": self.kwargs,
             "timestamp": self.timestamp,
         }
+        if self.stats is not None:
+            result["stats"] = self.stats
+        return result
 
     @classmethod
     def from_dict(
@@ -48,6 +53,7 @@ class CallRecord:
             kwargs=data["kwargs"],
             timestamp=data.get("timestamp", ""),
             ax_position=ax_position,
+            stats=data.get("stats"),
         )
 
 
@@ -60,6 +66,10 @@ class AxesRecord:
     decorations: List[CallRecord] = field(default_factory=list)
     # Panel-level caption (e.g., "(A) Description of this panel")
     caption: Optional[str] = None
+    # Panel-level statistics (e.g., summary stats, comparison results)
+    stats: Optional[Dict[str, Any]] = None
+    # Panel visibility (for composition)
+    visible: bool = True
 
     def add_call(self, record: CallRecord) -> None:
         """Add a plotting call record."""
@@ -77,6 +87,10 @@ class AxesRecord:
         }
         if self.caption is not None:
             result["caption"] = self.caption
+        if self.stats is not None:
+            result["stats"] = self.stats
+        if not self.visible:  # Only serialize if hidden (default is True)
+            result["visible"] = False
         return result
 
 
@@ -105,6 +119,8 @@ class FigureRecord:
     # Metadata for scientific figures (not rendered, stored in recipe)
     title_metadata: Optional[str] = None  # Figure title for publication/reference
     caption: Optional[str] = None  # Figure caption (e.g., "Fig. 1. Description...")
+    # Figure-level statistics (e.g., comparisons across panels, summary)
+    stats: Optional[Dict[str, Any]] = None
 
     def get_axes_key(self, row: int, col: int) -> str:
         """Get dictionary key for axes at position."""
@@ -157,6 +173,8 @@ class FigureRecord:
             metadata["title"] = self.title_metadata
         if self.caption is not None:
             metadata["caption"] = self.caption
+        if self.stats is not None:
+            metadata["stats"] = self.stats
         if metadata:
             result["metadata"] = metadata
         return result
@@ -181,6 +199,7 @@ class FigureRecord:
             panel_labels=fig_data.get("panel_labels"),
             title_metadata=metadata.get("title"),
             caption=metadata.get("caption"),
+            stats=metadata.get("stats"),
         )
 
         # Reconstruct axes
@@ -195,6 +214,8 @@ class FigureRecord:
             ax_record = AxesRecord(
                 position=(row, col),
                 caption=ax_data.get("caption"),
+                stats=ax_data.get("stats"),
+                visible=ax_data.get("visible", True),
             )
             for call_data in ax_data.get("calls", []):
                 ax_record.calls.append(CallRecord.from_dict(call_data, (row, col)))
@@ -271,6 +292,9 @@ class Recorder:
         if call_id is None:
             call_id = self._generate_call_id(method_name)
 
+        # Extract stats from kwargs before processing (stats is metadata, not matplotlib arg)
+        call_stats = kwargs.pop("stats", None) if "stats" in kwargs else None
+
         # Process args into serializable format
         processed_args = self._process_args(args, method_name)
 
@@ -283,6 +307,7 @@ class Recorder:
             args=processed_args,
             kwargs=processed_kwargs,
             ax_position=ax_position,
+            stats=call_stats,
         )
 
         # Add to appropriate axes
@@ -365,8 +390,8 @@ class Recorder:
         except Exception:
             pass
 
-        # Remove internal keys
-        skip_keys = {"id", "track", "_array"}
+        # Remove internal keys (stats is handled separately as metadata)
+        skip_keys = {"id", "track", "_array", "stats"}
         processed = {}
 
         for key, value in kwargs.items():

figrecipe/_reproducer/_core.py

@@ -2,6 +2,7 @@
 # -*- coding: utf-8 -*-
 """Core reproduction logic for figure reproduction."""
 
+import shutil
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Union
 
@@ -11,6 +12,7 @@ from matplotlib.axes import Axes
 
 from .._recorder import CallRecord, FigureRecord
 from .._serializer import load_recipe
+from .._utils._bundle import resolve_recipe_path
 
 
 def reproduce(
@@ -24,8 +26,11 @@ def reproduce(
     Parameters
     ----------
     path : str or Path
-        Path to .yaml or .png recipe file. If .png is provided,
-        the corresponding .yaml file will be loaded.
+        Path to recipe. Supports multiple formats:
+        - .yaml/.yml file: Direct recipe file
+        - .png/.jpg/etc: Image with associated .yaml
+        - Directory: Bundle containing recipe.yaml
+        - .zip: ZIP archive containing recipe.yaml
     calls : list of str, optional
         If provided, only reproduce these specific call IDs.
     skip_decorations : bool
@@ -43,56 +48,49 @@ def reproduce(
 
     Examples
     --------
-    >>> import figrecipe as ps
-    >>> fig, ax = ps.reproduce("experiment_001.yaml")
-    >>> fig, ax = ps.reproduce("experiment_001.png")  # Also works
+    >>> import figrecipe as fr
+    >>> fig, ax = fr.reproduce("experiment_001.yaml")
+    >>> fig, ax = fr.reproduce("experiment_001.png")  # Also works
+    >>> fig, ax = fr.reproduce("figure_bundle/")      # Directory bundle
+    >>> fig, ax = fr.reproduce("figure.zip")          # ZIP bundle
     >>> plt.show()
     """
-    path = Path(path)
-
-    # Accept both .png and .yaml - find the yaml file
-    if path.suffix.lower() in (".png", ".jpg", ".jpeg", ".pdf", ".svg"):
-        yaml_path = path.with_suffix(".yaml")
-        if not yaml_path.exists():
-            raise FileNotFoundError(
-                f"Recipe file not found: {yaml_path}. "
-                f"Expected .yaml file alongside {path}"
-            )
-        path = yaml_path
-
-    record = load_recipe(path)
+    # Resolve path to actual recipe YAML (handles directories, ZIPs, images)
+    path, temp_dir = resolve_recipe_path(path)
 
-    # Check for override file and merge if exists
-    if apply_overrides:
-        overrides_path = path.with_suffix(".overrides.json")
-        if overrides_path.exists():
-            import json
-
-            with open(overrides_path) as f:
-                data = json.load(f)
-
-            # Apply style overrides
-            manual_overrides = data.get("manual_overrides", {})
-            if manual_overrides:
-                # Merge overrides into record style
-                if record.style is None:
-                    record.style = {}
-                record.style.update(manual_overrides)
-
-            # Apply call overrides (kwargs changes from editor)
-            call_overrides = data.get("call_overrides", {})
-            if call_overrides:
-                for ax_key, ax_record in record.axes.items():
-                    for call in ax_record.calls:
-                        if call.id in call_overrides:
-                            # Merge call kwargs overrides
-                            call.kwargs.update(call_overrides[call.id])
-
-    return reproduce_from_record(
-        record,
-        calls=calls,
-        skip_decorations=skip_decorations,
-    )
+    try:
+        record = load_recipe(path)
+
+        # Check for override file and merge if exists
+        if apply_overrides:
+            overrides_path = path.with_suffix(".overrides.json")
+            if overrides_path.exists():
+                import json
+
+                with open(overrides_path) as f:
+                    data = json.load(f)
+
+                # Apply style overrides
+                manual_overrides = data.get("manual_overrides", {})
+                if manual_overrides:
+                    if record.style is None:
+                        record.style = {}
+                    record.style.update(manual_overrides)
+
+                # Apply call overrides (kwargs changes from editor)
+                call_overrides = data.get("call_overrides", {})
+                if call_overrides:
+                    for ax_key, ax_record in record.axes.items():
+                        for call in ax_record.calls:
+                            if call.id in call_overrides:
+                                call.kwargs.update(call_overrides[call.id])
+
+        return reproduce_from_record(
+            record, calls=calls, skip_decorations=skip_decorations
+        )
+    finally:
+        if temp_dir is not None and temp_dir.exists():
+            shutil.rmtree(temp_dir, ignore_errors=True)
 
 
 def reproduce_from_record(
@@ -195,6 +193,10 @@ def reproduce_from_record(
                 if result is not None:
                     result_cache[call.id] = result
 
+        # Apply panel visibility
+        if not getattr(ax_record, "visible", True):
+            ax.set_visible(False)
+
     # Finalize tick configuration and special plot types (avoids categorical axis interference)
     from ..styles._style_applier import finalize_special_plots, finalize_ticks
 
@@ -314,6 +316,15 @@ def _replay_call(
 
         return replay_swarmplot_call(ax, call)
 
+    # Handle stat_annotation specially (custom method)
+    if method_name == "stat_annotation":
+        from .._wrappers._stat_annotation import draw_stat_annotation
+
+        kwargs = call.kwargs.copy()
+        x1 = kwargs.pop("x1", 0)
+        x2 = kwargs.pop("x2", 1)
+        return draw_stat_annotation(ax, x1, x2, **kwargs)
+
     method = getattr(ax, method_name, None)
 
     if method is None:

figrecipe/_utils/__init__.py

@@ -2,6 +2,7 @@
 # -*- coding: utf-8 -*-
 """Utility modules for figrecipe."""
 
+from ._bundle import is_bundle_path, resolve_recipe_path
 from ._diff import get_non_default_kwargs, is_default_value
 from ._numpy_io import load_array, save_array
 from ._units import inch_to_mm, mm_to_inch, mm_to_pt, pt_to_mm
@@ -15,6 +16,8 @@ __all__ = [
     "inch_to_mm",
     "mm_to_pt",
     "pt_to_mm",
+    "resolve_recipe_path",
+    "is_bundle_path",
 ]
 
 # Optional: image comparison (requires PIL)

figrecipe/_utils/_bundle.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Bundle and path resolution utilities for figrecipe.
+
+This module provides utilities for resolving recipe paths from:
+- Direct YAML files (.yaml, .yml)
+- Image files (.png, .jpg, etc.) with associated YAML
+- Bundle directories containing recipe.yaml
+- ZIP files containing recipe.yaml
+
+This enables integration with FTS (Figure Transfer Specification) bundles.
+"""
+
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import Optional, Tuple, Union
+
+# Standard recipe filename in bundles
+RECIPE_FILENAME = "recipe.yaml"
+RECIPE_FILENAME_ALT = "recipe.yml"
+
+
+def resolve_recipe_path(
+    path: Union[str, Path],
+    extract_dir: Optional[Path] = None,
+) -> Tuple[Path, Optional[Path]]:
+    """Resolve a path to a recipe YAML file.
+
+    Handles multiple input formats:
+    - Direct YAML file: Returns as-is
+    - Image file (.png, etc.): Finds associated .yaml
+    - Directory: Looks for recipe.yaml inside
+    - ZIP file: Extracts and finds recipe.yaml
+
+    Parameters
+    ----------
+    path : str or Path
+        Input path - can be YAML, image, directory, or ZIP.
+    extract_dir : Path, optional
+        Directory to extract ZIP contents to. If None, uses a temp directory.
+
+    Returns
+    -------
+    tuple
+        (recipe_path, temp_dir) where temp_dir is set if extraction occurred
+        and the caller should clean it up, or None if no cleanup needed.
+
+    Raises
+    ------
+    FileNotFoundError
+        If path doesn't exist or recipe.yaml not found.
+    ValueError
+        If path type is not supported.
+
+    Examples
+    --------
+    >>> recipe_path, temp = resolve_recipe_path("figure.yaml")
+    >>> recipe_path, temp = resolve_recipe_path("figure/")
+    >>> recipe_path, temp = resolve_recipe_path("figure.zip")
+    """
+    path = Path(path)
+
+    if not path.exists():
+        raise FileNotFoundError(f"Path not found: {path}")
+
+    # Case 1: Direct YAML file
+    if path.suffix.lower() in (".yaml", ".yml"):
+        return path, None
+
+    # Case 2: Image file - find associated YAML
+    if path.suffix.lower() in (
+        ".png",
+        ".jpg",
+        ".jpeg",
+        ".pdf",
+        ".svg",
+        ".tif",
+        ".tiff",
+    ):
+        return _resolve_from_image(path), None
+
+    # Case 3: Directory - look for recipe.yaml
+    if path.is_dir():
+        return _resolve_from_directory(path), None
+
+    # Case 4: ZIP file - extract and find recipe.yaml
+    if path.suffix.lower() == ".zip":
+        return _resolve_from_zip(path, extract_dir)
+
+    raise ValueError(
+        f"Unsupported path type: {path.suffix}. "
+        f"Expected .yaml, .yml, .png, .zip, or directory."
+    )
+
+
+def _resolve_from_image(path: Path) -> Path:
+    """Find YAML recipe associated with an image file."""
+    yaml_path = path.with_suffix(".yaml")
+    if yaml_path.exists():
+        return yaml_path
+
+    yml_path = path.with_suffix(".yml")
+    if yml_path.exists():
+        return yml_path
+
+    raise FileNotFoundError(
+        f"Recipe file not found for {path.name}. "
+        f"Expected {yaml_path.name} or {yml_path.name}"
+    )
+
+
+def _resolve_from_directory(path: Path) -> Path:
+    """Find recipe.yaml inside a directory (FTS bundle)."""
+    recipe_path = path / RECIPE_FILENAME
+    if recipe_path.exists():
+        return recipe_path
+
+    recipe_alt = path / RECIPE_FILENAME_ALT
+    if recipe_alt.exists():
+        return recipe_alt
+
+    # Also check for any .yaml file as fallback
+    yaml_files = list(path.glob("*.yaml")) + list(path.glob("*.yml"))
+    if len(yaml_files) == 1:
+        return yaml_files[0]
+
+    if yaml_files:
+        raise FileNotFoundError(
+            f"Multiple YAML files found in {path}. "
+            f"Expected {RECIPE_FILENAME} or a single .yaml file."
+        )
+
+    raise FileNotFoundError(
+        f"No recipe found in directory {path}. "
+        f"Expected {RECIPE_FILENAME} or a .yaml file."
+    )
+
+
+def _resolve_from_zip(
+    path: Path,
+    extract_dir: Optional[Path] = None,
+) -> Tuple[Path, Path]:
+    """Extract ZIP and find recipe.yaml inside."""
+    if not zipfile.is_zipfile(path):
+        raise ValueError(f"Not a valid ZIP file: {path}")
+
+    # Create extraction directory
+    if extract_dir is None:
+        extract_dir = Path(tempfile.mkdtemp(prefix="figrecipe_bundle_"))
+
+    with zipfile.ZipFile(path, "r") as zf:
+        # Find recipe.yaml in the ZIP
+        recipe_name = None
+        for name in zf.namelist():
+            basename = Path(name).name
+            if basename in (RECIPE_FILENAME, RECIPE_FILENAME_ALT):
+                recipe_name = name
+                break
+
+        if recipe_name is None:
+            # Try to find any yaml file
+            yaml_files = [n for n in zf.namelist() if n.endswith((".yaml", ".yml"))]
+            if len(yaml_files) == 1:
+                recipe_name = yaml_files[0]
+            elif yaml_files:
+                raise FileNotFoundError(
+                    f"Multiple YAML files found in {path}. Expected {RECIPE_FILENAME}."
+                )
+            else:
+                raise FileNotFoundError(
+                    f"No recipe found in ZIP {path}. Expected {RECIPE_FILENAME}."
+                )
+
+        # Extract all files (needed for data files referenced by recipe)
+        zf.extractall(extract_dir)
+
+    recipe_path = extract_dir / recipe_name
+    return recipe_path, extract_dir
+
+
+def is_bundle_path(path: Union[str, Path]) -> bool:
+    """Check if path is a bundle directory or ZIP.
+
+    Parameters
+    ----------
+    path : str or Path
+        Path to check.
+
+    Returns
+    -------
+    bool
+        True if path is a directory or ZIP file.
+    """
+    path = Path(path)
+    if not path.exists():
+        return False
+    return path.is_dir() or path.suffix.lower() == ".zip"
+
+
+__all__ = [
+    "resolve_recipe_path",
+    "is_bundle_path",
+    "RECIPE_FILENAME",
+]

figrecipe/_wrappers/_axes.py

@@ -82,15 +82,26 @@ class RecordingAxes:
         """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, **kwargs):
+        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)
             if self._track and track:
+                # 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,
-                    kwargs,
+                    record_kwargs,
                     result,
                     id,
                     self._result_refs,
@@ -134,6 +145,48 @@ class RecordingAxes:
         ax_record = self._recorder.figure_record.get_or_create_axes(*self._position)
         return ax_record.caption
 
+    def set_stats(self, stats: Dict[str, Any]) -> "RecordingAxes":
+        """Set panel-level statistics metadata (not rendered, stored in recipe).
+
+        This is for storing statistical summary or comparison results
+        for this panel/axis, such as group means, sample sizes, or
+        comparison p-values.
+
+        Parameters
+        ----------
+        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
+        -------
+        RecordingAxes
+            Self for method chaining.
+
+        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}]
+        ... })
+        """
+        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.
 
@@ -333,6 +386,101 @@ class RecordingAxes:
         ax_record = self._recorder.figure_record.get_or_create_axes(*self._position)
         return ax_record.caption
 
+    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 generate_panel_caption(label=label, stats=self.stats, style=style)
+
+    def add_stat_annotation(
+        self,
+        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
+        ----------
+        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".
+        """
+        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:
     """Context manager to temporarily disable recording."""