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

figrecipe/_integrations/_scitex_stats.py

@@ -0,0 +1,298 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Integration with scitex.stats for statistical results."""
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+# Check if scitex.stats is available
+try:
+    from scitex import stats as scitex_stats
+
+    SCITEX_STATS_AVAILABLE = True
+except ImportError:
+    scitex_stats = None
+    SCITEX_STATS_AVAILABLE = False
+
+
+def from_scitex_stats(
+    stats_result: Union[Dict[str, Any], List[Dict[str, Any]]],
+) -> Dict[str, Any]:
+    """Convert scitex.stats result(s) to figrecipe stats format.
+
+    Parameters
+    ----------
+    stats_result : dict or list of dict
+        Statistical result(s) from scitex.stats. Supports:
+        - Single comparison dict
+        - List of comparison dicts
+        - scitex.stats flat format: {name, method, p_value, effect_size, ci95}
+        - scitex.stats nested format: {method: {name}, results: {p_value}}
+
+    Returns
+    -------
+    dict
+        Figrecipe-compatible stats dict with 'comparisons' list.
+
+    Examples
+    --------
+    >>> from scitex import stats
+    >>> result = stats.ttest_ind(x, y)
+    >>> fr_stats = from_scitex_stats(result)
+    >>> fig.set_stats(fr_stats)
+
+    >>> # Or for multiple comparisons
+    >>> results = [stats.ttest_ind(a, b), stats.ttest_ind(a, c)]
+    >>> fr_stats = from_scitex_stats(results)
+    """
+    # Normalize to list
+    if isinstance(stats_result, dict):
+        results = [stats_result]
+    else:
+        results = list(stats_result)
+
+    comparisons = []
+    for result in results:
+        comp = _convert_single_result(result)
+        if comp:
+            comparisons.append(comp)
+
+    return {"comparisons": comparisons}
+
+
+def _convert_single_result(result: Dict[str, Any]) -> Dict[str, Any]:
+    """Convert a single scitex.stats result to figrecipe format."""
+    # Handle flat format (legacy or from load_statsz)
+    if "p_value" in result and "results" not in result:
+        return _convert_flat_format(result)
+
+    # Handle nested format (from test functions)
+    if "results" in result:
+        return _convert_nested_format(result)
+
+    # Handle already-converted format
+    if "comparisons" in result:
+        # Already in figrecipe format, return first comparison
+        comps = result.get("comparisons", [])
+        return comps[0] if comps else {}
+
+    return {}
+
+
+def _convert_flat_format(result: Dict[str, Any]) -> Dict[str, Any]:
+    """Convert flat scitex.stats format."""
+    p_value = result.get("p_value")
+    stars = result.get("formatted") or result.get("stars")
+    if not stars and p_value is not None:
+        stars = _p_to_stars(p_value)
+
+    comp = {
+        "name": result.get("name", "comparison"),
+        "p_value": p_value,
+        "stars": stars,
+        "method": result.get("method", ""),
+    }
+
+    # Handle effect size
+    es = result.get("effect_size")
+    if es is not None:
+        ci = result.get("ci95", [])
+        if isinstance(es, (int, float)):
+            comp["effect_size"] = {
+                "name": "d",
+                "value": float(es),
+            }
+            if len(ci) >= 2:
+                comp["effect_size"]["ci_lower"] = ci[0]
+                comp["effect_size"]["ci_upper"] = ci[1]
+        elif isinstance(es, dict):
+            comp["effect_size"] = es
+
+    return comp
+
+
+def _convert_nested_format(result: Dict[str, Any]) -> Dict[str, Any]:
+    """Convert nested scitex.stats format."""
+    method_data = result.get("method", {})
+    results_data = result.get("results", {})
+
+    method_name = (
+        method_data.get("name", "")
+        if isinstance(method_data, dict)
+        else str(method_data)
+    )
+    p_value = results_data.get("p_value")
+    stars = _p_to_stars(p_value) if p_value is not None else ""
+
+    comp = {
+        "name": result.get("name", "comparison"),
+        "p_value": p_value,
+        "stars": stars,
+        "method": method_name,
+    }
+
+    # Handle effect size from results
+    es_data = results_data.get("effect_size")
+    if es_data:
+        if isinstance(es_data, dict):
+            comp["effect_size"] = es_data
+        else:
+            comp["effect_size"] = {"name": "d", "value": float(es_data)}
+
+    return comp
+
+
+def _p_to_stars(p_value: float, ns_symbol: bool = True) -> str:
+    """Convert p-value to significance stars."""
+    if p_value < 0.001:
+        return "***"
+    elif p_value < 0.01:
+        return "**"
+    elif p_value < 0.05:
+        return "*"
+    return "ns" if ns_symbol else ""
+
+
+def load_stats_bundle(path: Union[str, Path]) -> Dict[str, Any]:
+    """Load stats from a scitex.stats bundle file.
+
+    Parameters
+    ----------
+    path : str or Path
+        Path to .statsz or .zip bundle file.
+
+    Returns
+    -------
+    dict
+        Figrecipe-compatible stats dict.
+
+    Raises
+    ------
+    ImportError
+        If scitex.stats is not installed.
+    """
+    if not SCITEX_STATS_AVAILABLE:
+        raise ImportError(
+            "scitex.stats is required for bundle loading. "
+            "Install with: pip install scitex[stats]"
+        )
+
+    data = scitex_stats.load_statsz(path)
+    comparisons = data.get("comparisons", [])
+
+    # Convert each comparison
+    return from_scitex_stats(comparisons)
+
+
+def annotate_from_stats(
+    ax,
+    stats: Dict[str, Any],
+    positions: Optional[Dict[str, float]] = None,
+    style: str = "stars",
+    **kwargs,
+) -> List[Any]:
+    """Add stat annotations to axes from stats dict.
+
+    Parameters
+    ----------
+    ax : RecordingAxes
+        The axes to annotate.
+    stats : dict
+        Stats dict with 'comparisons' list. Each comparison should have:
+        - name: "Group A vs Group B" (parsed for group names)
+        - p_value: float
+        - Optional: groups: ["Group A", "Group B"]
+    positions : dict, optional
+        Mapping of group names to x positions. If None, uses 0, 1, 2, ...
+    style : str
+        Annotation style: "stars", "p_value", "both".
+    **kwargs
+        Additional arguments passed to add_stat_annotation().
+
+    Returns
+    -------
+    list
+        List of artist objects created.
+
+    Examples
+    --------
+    >>> stats = from_scitex_stats(result)
+    >>> annotate_from_stats(ax, stats, positions={"Control": 0, "Treatment": 1})
+    """
+    comparisons = stats.get("comparisons", [])
+    if not comparisons:
+        return []
+
+    artists = []
+    y_offset = 0
+
+    for comp in comparisons:
+        # Get positions for this comparison
+        x1, x2 = _get_comparison_positions(comp, positions)
+        if x1 is None or x2 is None:
+            continue
+
+        # Calculate y position (stack annotations)
+        y = kwargs.pop("y", None)
+        if y is None:
+            # Auto-calculate based on data
+            ylim = ax.get_ylim() if hasattr(ax, "get_ylim") else (0, 1)
+            y = ylim[1] + (ylim[1] - ylim[0]) * 0.05 * (1 + y_offset)
+            y_offset += 1
+
+        # Add annotation
+        result = ax.add_stat_annotation(
+            x1,
+            x2,
+            p_value=comp.get("p_value"),
+            text=comp.get("stars") if style == "stars" else None,
+            y=y,
+            style=style,
+            id=comp.get("name", "").replace(" ", "_"),
+            **kwargs,
+        )
+        artists.extend(result if isinstance(result, list) else [result])
+
+    return artists
+
+
+def _get_comparison_positions(
+    comp: Dict[str, Any],
+    positions: Optional[Dict[str, float]],
+) -> tuple:
+    """Extract x positions for a comparison."""
+    # Try explicit groups
+    groups = comp.get("groups", [])
+    if len(groups) >= 2 and positions:
+        x1 = positions.get(groups[0])
+        x2 = positions.get(groups[1])
+        if x1 is not None and x2 is not None:
+            return x1, x2
+
+    # Try parsing from name (e.g., "Control vs Treatment")
+    name = comp.get("name", "")
+    if " vs " in name:
+        parts = name.split(" vs ")
+        if len(parts) >= 2 and positions:
+            x1 = positions.get(parts[0].strip())
+            x2 = positions.get(parts[1].strip())
+            if x1 is not None and x2 is not None:
+                return x1, x2
+
+    # Try x1, x2 directly in comparison
+    if "x1" in comp and "x2" in comp:
+        return comp["x1"], comp["x2"]
+
+    # Default to sequential positions
+    if positions is None:
+        return 0, 1
+
+    return None, None
+
+
+__all__ = [
+    "SCITEX_STATS_AVAILABLE",
+    "from_scitex_stats",
+    "load_stats_bundle",
+    "annotate_from_stats",
+]

figrecipe/_params/_DECORATION_METHODS.py

@@ -22,6 +22,14 @@ DECORATION_METHODS = {
     "text",
     "annotate",
     "clabel",
+    "axis",  # For axis('off'), axis('on'), axis('equal'), etc.
+    "set_xticks",
+    "set_yticks",
+    "set_xticklabels",
+    "set_yticklabels",
+    "tick_params",
+    # Statistical annotations
+    "stat_annotation",  # Comparison brackets with stars/p-values
 }
 
 # EOF

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"),
         )
 
 
@@ -58,6 +64,12 @@ class AxesRecord:
     position: Tuple[int, int]
     calls: List[CallRecord] = field(default_factory=list)
     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."""
@@ -69,10 +81,17 @@ class AxesRecord:
 
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary for serialization."""
-        return {
+        result = {
             "calls": [c.to_dict() for c in self.calls],
             "decorations": [d.to_dict() for d in self.decorations],
         }
+        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
 
 
 @dataclass
@@ -95,6 +114,13 @@ class FigureRecord:
     suptitle: Optional[Dict[str, Any]] = None
     supxlabel: Optional[Dict[str, Any]] = None
     supylabel: Optional[Dict[str, Any]] = None
+    # Panel labels (A, B, C, D for multi-panel figures)
+    panel_labels: Optional[Dict[str, Any]] = None
+    # 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."""
@@ -138,12 +164,26 @@ class FigureRecord:
         # Add supylabel if set
         if self.supylabel is not None:
             result["figure"]["supylabel"] = self.supylabel
+        # Add panel_labels if set
+        if self.panel_labels is not None:
+            result["figure"]["panel_labels"] = self.panel_labels
+        # Add metadata section for scientific figures
+        metadata = {}
+        if self.title_metadata is not None:
+            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
 
     @classmethod
     def from_dict(cls, data: Dict[str, Any]) -> "FigureRecord":
         """Create from dictionary."""
         fig_data = data.get("figure", {})
+        metadata = data.get("metadata", {})
         record = cls(
             id=data.get("id", f"fig_{uuid.uuid4().hex[:8]}"),
             created=data.get("created", ""),
@@ -156,6 +196,10 @@ class FigureRecord:
             suptitle=fig_data.get("suptitle"),
             supxlabel=fig_data.get("supxlabel"),
             supylabel=fig_data.get("supylabel"),
+            panel_labels=fig_data.get("panel_labels"),
+            title_metadata=metadata.get("title"),
+            caption=metadata.get("caption"),
+            stats=metadata.get("stats"),
         )
 
         # Reconstruct axes
@@ -167,7 +211,12 @@ class FigureRecord:
             else:
                 row, col = 0, 0
 
-            ax_record = AxesRecord(position=(row, col))
+            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)))
             for dec_data in ax_data.get("decorations", []):
@@ -243,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)
 
@@ -255,6 +307,7 @@ class Recorder:
             args=processed_args,
             kwargs=processed_kwargs,
             ax_position=ax_position,
+            stats=call_stats,
         )
 
         # Add to appropriate axes
@@ -272,111 +325,12 @@ class Recorder:
         args: tuple,
         method_name: str,
     ) -> List[Dict[str, Any]]:
-        """Process positional arguments for storage.
-
-        Parameters
-        ----------
-        args : tuple
-            Raw positional arguments.
-        method_name : str
-            Name of the method.
+        """Process positional arguments for storage."""
+        from ._recorder_utils import process_args
 
-        Returns
-        -------
-        list
-            Processed args with name and data.
-        """
-        from ._utils._numpy_io import should_store_inline, to_serializable
-
-        processed = []
-        # Simple arg names based on common patterns
-        arg_names = self._get_arg_names(method_name, len(args))
-
-        for i, (name, value) in enumerate(zip(arg_names, args)):
-            # Handle result references (e.g., ContourSet for clabel)
-            if isinstance(value, dict) and "__ref__" in value:
-                processed.append(
-                    {
-                        "name": name,
-                        "data": {"__ref__": value["__ref__"]},
-                    }
-                )
-                continue
-
-            if isinstance(value, np.ndarray):
-                if should_store_inline(value):
-                    processed.append(
-                        {
-                            "name": name,
-                            "data": to_serializable(value),
-                            "dtype": str(value.dtype),
-                        }
-                    )
-                else:
-                    # Mark for file storage (will be handled by serializer)
-                    processed.append(
-                        {
-                            "name": name,
-                            "data": "__FILE__",
-                            "dtype": str(value.dtype),
-                            "_array": value,  # Temporary, removed during serialization
-                        }
-                    )
-            elif hasattr(value, "values"):  # pandas
-                arr = np.asarray(value)
-                if should_store_inline(arr):
-                    processed.append(
-                        {
-                            "name": name,
-                            "data": to_serializable(arr),
-                            "dtype": str(arr.dtype),
-                        }
-                    )
-                else:
-                    processed.append(
-                        {
-                            "name": name,
-                            "data": "__FILE__",
-                            "dtype": str(arr.dtype),
-                            "_array": arr,
-                        }
-                    )
-            elif (
-                isinstance(value, (list, tuple))
-                and len(value) > 0
-                and isinstance(value[0], np.ndarray)
-            ):
-                # List of arrays (e.g., boxplot, violinplot data)
-                arrays_data = [to_serializable(arr) for arr in value]
-                dtypes = [str(arr.dtype) for arr in value]
-                processed.append(
-                    {
-                        "name": name,
-                        "data": arrays_data,
-                        "dtype": (dtypes[0] if len(set(dtypes)) == 1 else dtypes),
-                        "_is_array_list": True,
-                    }
-                )
-            else:
-                # Scalar or other serializable value
-                try:
-                    processed.append(
-                        {
-                            "name": name,
-                            "data": (
-                                value if self._is_serializable(value) else str(value)
-                            ),
-                        }
-                    )
-                except (TypeError, ValueError):
-                    processed.append(
-                        {
-                            "name": name,
-                            "data": str(value),
-                        }
-                    )
-
-        return processed
+        return process_args(
+            args, method_name, self._get_arg_names, self._is_serializable
+        )
 
     def _get_arg_names(self, method_name: str, n_args: int) -> List[str]:
         """Get argument names for a method from signatures.
@@ -436,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/_recorder_utils.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Utilities for recorder argument processing."""
+
+from typing import Any, Dict, List
+
+import numpy as np
+
+
+def process_args(
+    args: tuple,
+    method_name: str,
+    get_arg_names_func,
+    is_serializable_func,
+) -> List[Dict[str, Any]]:
+    """Process positional arguments for storage.
+
+    Parameters
+    ----------
+    args : tuple
+        Raw positional arguments.
+    method_name : str
+        Name of the method.
+    get_arg_names_func : callable
+        Function to get argument names.
+    is_serializable_func : callable
+        Function to check serializability.
+
+    Returns
+    -------
+    list
+        Processed args with name and data.
+    """
+    from ._utils._numpy_io import should_store_inline, to_serializable
+
+    processed = []
+    arg_names = get_arg_names_func(method_name, len(args))
+
+    for name, value in zip(arg_names, args):
+        processed_arg = _process_single_arg(
+            name, value, should_store_inline, to_serializable, is_serializable_func
+        )
+        processed.append(processed_arg)
+
+    return processed
+
+
+def _process_single_arg(
+    name: str,
+    value: Any,
+    should_store_inline,
+    to_serializable,
+    is_serializable_func,
+) -> Dict[str, Any]:
+    """Process a single argument value."""
+    # Handle result references (e.g., ContourSet for clabel)
+    if isinstance(value, dict) and "__ref__" in value:
+        return {"name": name, "data": {"__ref__": value["__ref__"]}}
+
+    if isinstance(value, np.ndarray):
+        return _process_ndarray(name, value, should_store_inline, to_serializable)
+
+    if hasattr(value, "values"):  # pandas
+        arr = np.asarray(value)
+        return _process_ndarray(name, arr, should_store_inline, to_serializable)
+
+    if (
+        isinstance(value, (list, tuple))
+        and len(value) > 0
+        and isinstance(value[0], np.ndarray)
+    ):
+        # List of arrays (e.g., boxplot, violinplot data)
+        return _process_array_list(name, value, to_serializable)
+
+    # Scalar or other serializable value
+    return _process_scalar(name, value, is_serializable_func)
+
+
+def _process_ndarray(
+    name: str, value: np.ndarray, should_store_inline, to_serializable
+) -> Dict[str, Any]:
+    """Process numpy array argument."""
+    if should_store_inline(value):
+        return {
+            "name": name,
+            "data": to_serializable(value),
+            "dtype": str(value.dtype),
+        }
+    else:
+        # Mark for file storage (will be handled by serializer)
+        return {
+            "name": name,
+            "data": "__FILE__",
+            "dtype": str(value.dtype),
+            "_array": value,  # Temporary, removed during serialization
+        }
+
+
+def _process_array_list(name: str, value: list, to_serializable) -> Dict[str, Any]:
+    """Process list of arrays argument."""
+    arrays_data = [to_serializable(arr) for arr in value]
+    dtypes = [str(arr.dtype) for arr in value]
+    return {
+        "name": name,
+        "data": arrays_data,
+        "dtype": (dtypes[0] if len(set(dtypes)) == 1 else dtypes),
+        "_is_array_list": True,
+    }
+
+
+def _process_scalar(name: str, value: Any, is_serializable_func) -> Dict[str, Any]:
+    """Process scalar or other value."""
+    try:
+        return {
+            "name": name,
+            "data": value if is_serializable_func(value) else str(value),
+        }
+    except (TypeError, ValueError):
+        return {"name": name, "data": str(value)}
+
+
+__all__ = ["process_args"]
+
+# EOF