scitex 2.8.1__py3-none-any.whl → 2.10.0__py3-none-any.whl

scitex/logging/_warnings.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-21"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/logging/_warnings.py
+
+"""Warning system for SciTeX, mimicking Python's warnings module.
+
+Usage:
+    import scitex.logging as logging
+    from scitex.logging import UnitWarning
+
+    # Emit a warning
+    logging.warn("Missing units on axis label", UnitWarning)
+
+    # Filter warnings (like warnings.filterwarnings)
+    logging.filterwarnings("ignore", category=UnitWarning)
+    logging.filterwarnings("error", category=UnitWarning)  # Raise as exception
+    logging.filterwarnings("always", category=UnitWarning)  # Always show
+"""
+
+import logging as _logging
+from typing import Dict, Optional, Type, Set
+
+# =============================================================================
+# Warning Categories (similar to Python's warning classes)
+# =============================================================================
+
+
+class SciTeXWarning(UserWarning):
+    """Base warning class for all SciTeX warnings."""
+
+    pass
+
+
+class UnitWarning(SciTeXWarning):
+    """Warning for axis label unit issues (educational for SI conventions).
+
+    Raised when:
+    - Axis labels are missing units
+    - Units use parentheses instead of brackets (SI prefers [])
+    - Units use division instead of negative exponents (m/s vs m·s⁻¹)
+    """
+
+    pass
+
+
+class StyleWarning(SciTeXWarning):
+    """Warning for style/formatting issues."""
+
+    pass
+
+
+class SciTeXDeprecationWarning(SciTeXWarning):
+    """Warning for deprecated SciTeX features."""
+
+    pass
+
+
+class PerformanceWarning(SciTeXWarning):
+    """Warning for performance issues."""
+
+    pass
+
+
+class DataLossWarning(SciTeXWarning):
+    """Warning for potential data loss."""
+
+    pass
+
+
+# =============================================================================
+# Warning Filter Registry
+# =============================================================================
+
+# Actions: "ignore", "error", "always", "default", "once", "module"
+_filters: Dict[Type[SciTeXWarning], str] = {}
+_seen_warnings: Set[str] = set()  # For "once" action
+
+
+def filterwarnings(
+    action: str,
+    category: Type[SciTeXWarning] = SciTeXWarning,
+    message: Optional[str] = None,
+) -> None:
+    """Control warning behavior (like warnings.filterwarnings).
+
+    Parameters
+    ----------
+    action : str
+        One of:
+        - "ignore": Never show this warning
+        - "error": Raise as exception
+        - "always": Always show
+        - "default": Show first occurrence per location
+        - "once": Show only once total
+        - "module": Show once per module
+    category : type
+        Warning category (default: SciTeXWarning = all)
+    message : str, optional
+        Regex pattern to match warning message (not implemented yet)
+
+    Examples
+    --------
+    >>> import scitex.logging as logging
+    >>> from scitex.logging import UnitWarning
+    >>> logging.filterwarnings("ignore", category=UnitWarning)
+    """
+    valid_actions = {"ignore", "error", "always", "default", "once", "module"}
+    if action not in valid_actions:
+        raise ValueError(f"Invalid action '{action}'. Must be one of: {valid_actions}")
+
+    _filters[category] = action
+
+
+def resetwarnings() -> None:
+    """Reset all warning filters to default behavior."""
+    global _filters, _seen_warnings
+    _filters = {}
+    _seen_warnings = set()
+
+
+def _get_action(category: Type[SciTeXWarning]) -> str:
+    """Get the action for a warning category, checking inheritance."""
+    # Check exact match first
+    if category in _filters:
+        return _filters[category]
+
+    # Check parent classes
+    for filter_cat, action in _filters.items():
+        if issubclass(category, filter_cat):
+            return action
+
+    # Default action
+    return "default"
+
+
+# =============================================================================
+# Warning Emission
+# =============================================================================
+
+
+def warn(
+    message: str,
+    category: Type[SciTeXWarning] = SciTeXWarning,
+    stacklevel: int = 2,
+) -> None:
+    """Emit a warning (like warnings.warn but integrated with scitex.logging).
+
+    Parameters
+    ----------
+    message : str
+        Warning message
+    category : type
+        Warning category (default: SciTeXWarning)
+    stacklevel : int
+        Stack level for source location (default: 2 = caller)
+
+    Examples
+    --------
+    >>> import scitex.logging as logging
+    >>> from scitex.logging import UnitWarning
+    >>> logging.warn("X axis has no units", UnitWarning)
+    """
+    import inspect
+
+    action = _get_action(category)
+
+    # Handle action
+    if action == "ignore":
+        return
+
+    if action == "error":
+        raise category(message)
+
+    # Get source location for "once", "module", "default" actions
+    frame = inspect.currentframe()
+    for _ in range(stacklevel):
+        if frame is not None:
+            frame = frame.f_back
+
+    location = ""
+    if frame is not None:
+        filename = frame.f_code.co_filename
+        lineno = frame.f_lineno
+        location = f"{filename}:{lineno}"
+
+    # Check if already seen
+    warn_key = f"{category.__name__}:{message}:{location}"
+
+    if action == "once":
+        if warn_key in _seen_warnings:
+            return
+        _seen_warnings.add(warn_key)
+    elif action == "default":
+        # Show first per location
+        loc_key = f"{category.__name__}:{location}"
+        if loc_key in _seen_warnings:
+            return
+        _seen_warnings.add(loc_key)
+    elif action == "module":
+        # Show once per module
+        if frame is not None:
+            module_key = f"{category.__name__}:{frame.f_code.co_filename}"
+            if module_key in _seen_warnings:
+                return
+            _seen_warnings.add(module_key)
+
+    # Emit via scitex.logging
+    logger = _logging.getLogger("scitex.warnings")
+    category_name = category.__name__
+
+    # Format: "UnitWarning: message"
+    logger.warning(f"{category_name}: {message}")
+
+
+# =============================================================================
+# Convenience Warning Functions
+# =============================================================================
+
+
+def warn_deprecated(
+    old_name: str, new_name: str, version: Optional[str] = None
+) -> None:
+    """Issue a deprecation warning."""
+    message = f"{old_name} is deprecated. Use {new_name} instead."
+    if version:
+        message += f" Will be removed in version {version}."
+    warn(message, SciTeXDeprecationWarning, stacklevel=3)
+
+
+def warn_performance(operation: str, suggestion: str) -> None:
+    """Issue a performance warning."""
+    message = f"Performance warning in {operation}: {suggestion}"
+    warn(message, PerformanceWarning, stacklevel=3)
+
+
+def warn_data_loss(operation: str, detail: str) -> None:
+    """Issue a data loss warning."""
+    message = f"Potential data loss in {operation}: {detail}"
+    warn(message, DataLossWarning, stacklevel=3)
+
+
+__all__ = [
+    # Warning categories
+    "SciTeXWarning",
+    "UnitWarning",
+    "StyleWarning",
+    "SciTeXDeprecationWarning",
+    "PerformanceWarning",
+    "DataLossWarning",
+    # Functions
+    "warn",
+    "filterwarnings",
+    "resetwarnings",
+    # Convenience functions
+    "warn_deprecated",
+    "warn_performance",
+    "warn_data_loss",
+]
+
+# EOF

scitex/plt/__init__.py

@@ -179,7 +179,10 @@ try:
 except Exception:
     pass  # Use matplotlib default colors if color module fails
 
-from ._tpl import termplot
+try:
+    from ._tpl import termplot
+except ImportError:
+    termplot = None
 from . import color
 from . import utils
 from . import ax

scitex/plt/_figrecipe.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-01 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/plt/_figrecipe.py
+# ----------------------------------------
+"""
+Figrecipe integration for scitex.
+
+This module provides integration with figrecipe for reproducible matplotlib figures.
+Uses csv_format="single" by default for backward compatibility with scitex's
+SigmaPlot-compatible CSV format.
+
+Usage
+-----
+>>> import scitex.plt as splt
+>>> fig, ax = splt.subplots()
+>>> ax.plot([1, 2, 3], [4, 5, 6], id='data')
+>>> splt.save_recipe(fig, 'figure.yaml')  # Saves recipe with single CSV
+"""
+
+from pathlib import Path
+from typing import Any, Dict, Literal, Optional, Tuple, Union
+
+from scitex import logging
+
+logger = logging.getLogger(__name__)
+
+# Check if figrecipe is available
+try:
+    import figrecipe as fr
+
+    FIGRECIPE_AVAILABLE = True
+except ImportError:
+    FIGRECIPE_AVAILABLE = False
+    fr = None
+
+
+def check_figrecipe_available() -> bool:
+    """Check if figrecipe is installed."""
+    return FIGRECIPE_AVAILABLE
+
+
+def subplots(
+    nrows: int = 1,
+    ncols: int = 1,
+    **kwargs,
+) -> Tuple[Any, Any]:
+    """Create recording-enabled subplots using figrecipe.
+
+    This is a wrapper around figrecipe.subplots() that creates
+    figures with recording capabilities for reproducibility.
+
+    Parameters
+    ----------
+    nrows, ncols : int
+        Number of rows and columns.
+    **kwargs
+        Additional arguments passed to figrecipe.subplots().
+
+    Returns
+    -------
+    fig : RecordingFigure
+        Figrecipe's wrapped figure.
+    axes : RecordingAxes or ndarray
+        Wrapped axes.
+
+    Raises
+    ------
+    ImportError
+        If figrecipe is not installed.
+    """
+    if not FIGRECIPE_AVAILABLE:
+        raise ImportError(
+            "figrecipe is not installed. Install with: pip install figrecipe"
+        )
+
+    return fr.subplots(nrows, ncols, **kwargs)
+
+
+def save_recipe(
+    fig,
+    path: Union[str, Path],
+    csv_format: Literal["single", "separate"] = "single",
+    data_format: Literal["csv", "npz", "inline"] = "csv",
+    validate: bool = True,
+    verbose: bool = True,
+    **kwargs,
+) -> Optional[Tuple[Path, Path]]:
+    """Save figure recipe using figrecipe with scitex-compatible CSV format.
+
+    This function saves a matplotlib figure as a reproducible recipe using
+    figrecipe. By default, uses csv_format="single" for backward compatibility
+    with scitex's SigmaPlot-compatible CSV format.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure or RecordingFigure
+        The figure to save.
+    path : str or Path
+        Output path (.yaml for recipe, .png/.pdf for image+recipe).
+    csv_format : str
+        CSV format: 'single' (scitex-compatible, default) or 'separate'.
+        - 'single': All columns in one CSV with scitex naming convention
+        - 'separate': One CSV per variable (figrecipe default)
+    data_format : str
+        Data format: 'csv' (default), 'npz', or 'inline'.
+    validate : bool
+        If True (default), validate reproducibility after saving.
+    verbose : bool
+        If True (default), print save status.
+    **kwargs
+        Additional arguments passed to figrecipe.save().
+
+    Returns
+    -------
+    tuple or None
+        (image_path, yaml_path) if successful, None if figrecipe unavailable.
+
+    Examples
+    --------
+    >>> import scitex.plt as splt
+    >>> fig, ax = splt.subplots()
+    >>> ax.plot([1, 2, 3], [4, 5, 6])
+    >>> splt.save_recipe(fig, 'output.yaml')  # Single CSV format (scitex-compatible)
+    >>> splt.save_recipe(fig, 'output.yaml', csv_format='separate')  # Separate CSVs
+    """
+    if not FIGRECIPE_AVAILABLE:
+        logger.warning(
+            "figrecipe is not installed. Recipe not saved. "
+            "Install with: pip install figrecipe"
+        )
+        return None
+
+    path = Path(path)
+
+    # Handle different figure types
+    # If it's a scitex FigWrapper, extract the matplotlib figure
+    if hasattr(fig, "_fig_mpl"):
+        mpl_fig = fig._fig_mpl
+    elif hasattr(fig, "figure"):
+        mpl_fig = fig.figure
+    else:
+        mpl_fig = fig
+
+    # Check if fig is already a figrecipe RecordingFigure
+    if hasattr(fig, "_recorder"):
+        # Already a RecordingFigure, use figrecipe's save directly
+        return fr.save(
+            fig,
+            path,
+            data_format=data_format,
+            csv_format=csv_format,
+            validate=validate,
+            verbose=verbose,
+            **kwargs,
+        )
+
+    # For regular matplotlib figures, we need to wrap them first
+    # This requires re-creating the figure with figrecipe
+    logger.warning(
+        "Figure is not a RecordingFigure. For full recipe support, "
+        "create figures with fr.subplots() or splt.subplots_recipe()."
+    )
+    return None
+
+
+def load_recipe(path: Union[str, Path]) -> Tuple[Any, Any]:
+    """Load and reproduce a figure from a recipe file.
+
+    Parameters
+    ----------
+    path : str or Path
+        Path to .yaml recipe file.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+        Reproduced figure.
+    axes : Axes or list of Axes
+        Reproduced axes.
+
+    Raises
+    ------
+    ImportError
+        If figrecipe is not installed.
+    """
+    if not FIGRECIPE_AVAILABLE:
+        raise ImportError(
+            "figrecipe is not installed. Install with: pip install figrecipe"
+        )
+
+    return fr.reproduce(path)
+
+
+def recipe_info(path: Union[str, Path]) -> Dict[str, Any]:
+    """Get information about a recipe without reproducing.
+
+    Parameters
+    ----------
+    path : str or Path
+        Path to .yaml recipe file.
+
+    Returns
+    -------
+    dict
+        Recipe information including figure settings, calls, etc.
+
+    Raises
+    ------
+    ImportError
+        If figrecipe is not installed.
+    """
+    if not FIGRECIPE_AVAILABLE:
+        raise ImportError(
+            "figrecipe is not installed. Install with: pip install figrecipe"
+        )
+
+    return fr.info(path)
+
+
+# Convenience aliases
+reproduce = load_recipe
+info = recipe_info
+
+
+__all__ = [
+    "FIGRECIPE_AVAILABLE",
+    "check_figrecipe_available",
+    "subplots",
+    "save_recipe",
+    "load_recipe",
+    "reproduce",
+    "recipe_info",
+    "info",
+]
+
+# EOF

scitex/plt/_subplots/_AxisWrapper.py

@@ -189,10 +189,14 @@ class AxisWrapper(
                             "errorbar",
                             "step",
                             "stem",
+                            # Fill and area plots
+                            "fill",
+                            "stackplot",
                             # Statistical plots
                             "hist2d",
                             "hexbin",
                             "pie",
+                            "eventplot",
                             # Contour plots
                             "contour",
                             "contourf",
@@ -202,6 +206,8 @@ class AxisWrapper(
                             "imshow",
                             "matshow",
                             "spy",
+                            "pcolormesh",
+                            "pcolor",
                             # Quiver plots
                             "quiver",
                             "streamplot",

scitex/plt/_subplots/_AxisWrapperMixins/_UnitAwareMixin.py

@@ -19,9 +19,111 @@ Features:
 """
 
 from typing import Optional, Dict, Tuple, Union, Any
+import re
 import numpy as np
 from scitex.units import Unit, Q, Units
-from scitex.errors import SciTeXError
+from scitex.logging import SciTeXError
+import scitex.logging as logging
+from scitex.logging import UnitWarning, warn as _warn
+
+# Valid dimensionless/special unit markers
+_VALID_DIMENSIONLESS = {"[-]", "[a.u.]", "[arb. units]", "[dimensionless]", "[1]", "[A.U.]"}
+
+
+def _convert_to_negative_exponent(unit: str) -> str:
+    """Convert unit with / to negative exponent format.
+
+    Examples:
+        m/s -> m·s⁻¹
+        kg/m^2 -> kg·m⁻²
+        W/m^2/K -> W·m⁻²·K⁻¹
+    """
+    superscript = str.maketrans("0123456789-", "⁰¹²³⁴⁵⁶⁷⁸⁹⁻")
+
+    parts = unit.split("/")
+    if len(parts) < 2:
+        return unit
+
+    result = parts[0]
+    for part in parts[1:]:
+        exp_match = re.match(r"([a-zA-Z]+)\^?(\d+)?", part)
+        if exp_match:
+            base = exp_match.group(1)
+            exp = exp_match.group(2) or "1"
+            neg_exp = f"-{exp}".translate(superscript)
+            result += f"·{base}{neg_exp}"
+        else:
+            result += f"·{part}⁻¹"
+
+    return result
+
+
+def validate_axis_label(label: str, axis_name: str = "axis") -> str:
+    """Validate and warn about axis label units (educational for scientific standards).
+
+    Checks for:
+    - Missing units
+    - Non-standard format (prefer [] over ())
+    - Suggests ^-1 format over /
+
+    Parameters
+    ----------
+    label : str
+        Axis label to validate
+    axis_name : str
+        Name for warning messages (e.g., "X axis", "Y axis")
+
+    Returns
+    -------
+    str
+        Original label (warnings are educational, not auto-correcting)
+    """
+    if not label:
+        return label
+
+    # Check for units in brackets [] or parentheses ()
+    has_square_brackets = bool(re.search(r"\[.*?\]", label))
+    has_parentheses = bool(re.search(r"\(.*?\)", label))
+
+    unit_match_square = re.search(r"\[(.*?)\]", label)
+    unit_match_paren = re.search(r"\((.*?)\)", label)
+
+    if not has_square_brackets and not has_parentheses:
+        _warn(
+            f"{axis_name} label '{label}' has no units. "
+            f"Consider: '{label} [unit]' or '{label} [-]' for dimensionless",
+            UnitWarning,
+            stacklevel=3,
+        )
+        return label
+
+    if has_parentheses and not has_square_brackets:
+        unit = unit_match_paren.group(1) if unit_match_paren else ""
+        suggested = re.sub(r"\((.*?)\)", f"[{unit}]", label)
+        _warn(
+            f"{axis_name} label '{label}' uses parentheses. "
+            f"SI convention prefers: '{suggested}'",
+            UnitWarning,
+            stacklevel=3,
+        )
+
+    unit_content = None
+    if unit_match_square:
+        unit_content = unit_match_square.group(1)
+    elif unit_match_paren:
+        unit_content = unit_match_paren.group(1)
+
+    if unit_content and "/" in unit_content:
+        suggested_unit = _convert_to_negative_exponent(unit_content)
+        if suggested_unit != unit_content:
+            suggested_label = label.replace(f"[{unit_content}]", f"[{suggested_unit}]")
+            _warn(
+                f"{axis_name} uses '/' in units. Consider: '{suggested_label}'",
+                UnitWarning,
+                stacklevel=3,
+            )
+
+    return label
 
 
 class UnitMismatchError(SciTeXError):
@@ -287,6 +389,9 @@ class UnitAwareMixin:
         if self._x_unit:
             label = f"{label} [{self._x_unit.symbol}]"
 
+        # Validate units (educational warnings for scientific standards)
+        validate_axis_label(label, "X axis")
+
         self._axes_mpl.set_xlabel(label)
 
     def set_ylabel(self, label: str, unit: Optional[Union[str, Unit]] = None) -> None:
@@ -305,6 +410,9 @@ class UnitAwareMixin:
         if self._y_unit:
             label = f"{label} [{self._y_unit.symbol}]"
 
+        # Validate units (educational warnings for scientific standards)
+        validate_axis_label(label, "Y axis")
+
         self._axes_mpl.set_ylabel(label)
 
     def set_zlabel(self, label: str, unit: Optional[Union[str, Unit]] = None) -> None:
@@ -326,4 +434,7 @@ class UnitAwareMixin:
         if self._z_unit:
             label = f"{label} [{self._z_unit.symbol}]"
 
+        # Validate units (educational warnings for scientific standards)
+        validate_axis_label(label, "Z axis")
+
         self._axes_mpl.set_zlabel(label)

scitex/plt/_subplots/_FigWrapper.py

@@ -304,6 +304,21 @@ class FigWrapper:
                     for ax in self.axes:
                         yield ax
 
+    @property
+    def history(self):
+        """Aggregate tracking history from all axes in the figure.
+
+        Returns a combined OrderedDict of all tracking records from all axes,
+        enabling FTS bundle creation to build encoding from plot operations.
+        """
+        from collections import OrderedDict
+
+        combined = OrderedDict()
+        for ax in self._traverse_axes():
+            if hasattr(ax, "history") and ax.history:
+                combined.update(ax.history)
+        return combined
+
     def legend(self, *args, loc="best", **kwargs):
         """Legend with 'best' automatic placement by default for all axes."""
         for ax in self._traverse_axes():