scitex 2.5.0__py3-none-any.whl → 2.7.3__py3-none-any.whl

scitex/plt/_subplots/_AxisWrapper.py

@@ -14,9 +14,14 @@ from functools import wraps
 
 import matplotlib
 
+from scitex import logging
+
+logger = logging.getLogger(__name__)
+
 from ._AxisWrapperMixins import (
     AdjustmentMixin,
     MatplotlibPlotMixin,
+    RawMatplotlibMixin,
     SeabornMixin,
     TrackingMixin,
     UnitAwareMixin,
@@ -24,10 +29,17 @@ from ._AxisWrapperMixins import (
 from scitex.plt.styles import apply_plot_defaults, apply_plot_postprocess
 
 
-class AxisWrapper(MatplotlibPlotMixin, SeabornMixin, AdjustmentMixin, TrackingMixin, UnitAwareMixin):
+class AxisWrapper(
+    MatplotlibPlotMixin,
+    SeabornMixin,
+    RawMatplotlibMixin,
+    AdjustmentMixin,
+    TrackingMixin,
+    UnitAwareMixin,
+):
     def __init__(self, fig_scitex, axis_mpl, track):
         """Initialize the AxisWrapper.
-        
+
         Args:
             fig_scitex: Parent figure wrapper
             axis_mpl: Matplotlib axis to wrap
@@ -53,31 +65,35 @@ class AxisWrapper(MatplotlibPlotMixin, SeabornMixin, AdjustmentMixin, TrackingMi
         self.id = 0
         self._counter_part = matplotlib.axes.Axes
         self._tracking_depth = 0  # Depth counter to prevent tracking internal calls
-        
+
         # Initialize unit awareness
         UnitAwareMixin.__init__(self)
 
     def get_figure(self, root=True):
         """Get the figure, compatible with matplotlib 3.8+"""
         return self._fig_mpl
-    
+
     def twinx(self):
         """Create a twin y-axis and wrap it with AxisWrapper."""
         twin_ax = self._axes_mpl.twinx()
+
         # Create a mock figure wrapper for the twin axis
         class MockFigWrapper:
             def __init__(self, fig_mpl):
                 self._fig_mpl = fig_mpl
+
         mock_fig = MockFigWrapper(self._fig_mpl)
         return AxisWrapper(fig_scitex=mock_fig, axis_mpl=twin_ax, track=self.track)
-    
+
     def twiny(self):
         """Create a twin x-axis and wrap it with AxisWrapper."""
         twin_ax = self._axes_mpl.twiny()
+
         # Create a mock figure wrapper for the twin axis
         class MockFigWrapper:
             def __init__(self, fig_mpl):
                 self._fig_mpl = fig_mpl
+
         mock_fig = MockFigWrapper(self._fig_mpl)
         return AxisWrapper(fig_scitex=mock_fig, axis_mpl=twin_ax, track=self.track)
 
@@ -102,17 +118,19 @@ class AxisWrapper(MatplotlibPlotMixin, SeabornMixin, AdjustmentMixin, TrackingMi
                     # Increment tracking depth to detect internal calls
                     # Internal calls (depth > 1) won't be tracked
                     self._tracking_depth += 1
-                    is_top_level_call = (self._tracking_depth == 1)
+                    is_top_level_call = self._tracking_depth == 1
 
                     try:
                         # Apply pre-processing defaults from styles module
-                        apply_plot_defaults(__method_name__, kwargs, id_value, self._axes_mpl)
+                        apply_plot_defaults(
+                            __method_name__, kwargs, id_value, self._axes_mpl
+                        )
 
                         # Pop scitex-specific kwargs before calling matplotlib
                         # These are handled in post-processing
                         scitex_kwargs = {}
-                        if __method_name__ == 'violinplot':
-                            scitex_kwargs['boxplot'] = kwargs.pop('boxplot', True)
+                        if __method_name__ == "violinplot":
+                            scitex_kwargs["boxplot"] = kwargs.pop("boxplot", True)
 
                         # Call the original matplotlib method
                         result = orig_attr(*args, **kwargs)
@@ -124,7 +142,9 @@ class AxisWrapper(MatplotlibPlotMixin, SeabornMixin, AdjustmentMixin, TrackingMi
                                 # plot() returns list of Line2D objects
                                 for item in result:
                                     item._scitex_id = id_value
-                            elif hasattr(result, '__iter__') and not isinstance(result, str):
+                            elif hasattr(result, "__iter__") and not isinstance(
+                                result, str
+                            ):
                                 # Other containers (e.g., bar containers)
                                 try:
                                     for item in result:
@@ -142,7 +162,9 @@ class AxisWrapper(MatplotlibPlotMixin, SeabornMixin, AdjustmentMixin, TrackingMi
                         kwargs.update(scitex_kwargs)
 
                         # Apply post-processing styling from styles module
-                        apply_plot_postprocess(__method_name__, result, self._axes_mpl, kwargs, args)
+                        apply_plot_postprocess(
+                            __method_name__, result, self._axes_mpl, kwargs, args
+                        )
 
                         # Determine if tracking should occur
                         # Only track top-level calls (depth == 1), not internal matplotlib calls
@@ -154,21 +176,44 @@ class AxisWrapper(MatplotlibPlotMixin, SeabornMixin, AdjustmentMixin, TrackingMi
                         # Expanded list of matplotlib plotting methods to track
                         tracking_methods = {
                             # Basic plots
-                            'plot', 'scatter', 'bar', 'barh', 'hist', 'boxplot', 'violinplot',
+                            "plot",
+                            "scatter",
+                            "bar",
+                            "barh",
+                            "hist",
+                            "boxplot",
+                            "violinplot",
                             # Line plots
-                            'fill_between', 'fill_betweenx', 'errorbar', 'step', 'stem',
+                            "fill_between",
+                            "fill_betweenx",
+                            "errorbar",
+                            "step",
+                            "stem",
                             # Statistical plots
-                            'hist2d', 'hexbin', 'pie',
+                            "hist2d",
+                            "hexbin",
+                            "pie",
                             # Contour plots
-                            'contour', 'contourf', 'tricontour', 'tricontourf',
+                            "contour",
+                            "contourf",
+                            "tricontour",
+                            "tricontourf",
                             # Image plots
-                            'imshow', 'matshow', 'spy',
+                            "imshow",
+                            "matshow",
+                            "spy",
                             # Quiver plots
-                            'quiver', 'streamplot',
+                            "quiver",
+                            "streamplot",
                             # 3D-related (if axes3d)
-                            'plot3D', 'scatter3D', 'bar3d', 'plot_surface', 'plot_wireframe',
+                            "plot3D",
+                            "scatter3D",
+                            "bar3d",
+                            "plot_surface",
+                            "plot_wireframe",
                             # Text and annotations (data-containing)
-                            'annotate', 'text'
+                            "annotate",
+                            "text",
                         }
                         if should_track and __method_name__ in tracking_methods:
                             # Use the _track method from TrackingMixin
@@ -177,13 +222,15 @@ class AxisWrapper(MatplotlibPlotMixin, SeabornMixin, AdjustmentMixin, TrackingMi
                                 # Convert args to tracked_dict for consistency with other tracking
                                 tracked_dict = {"args": args}
                                 self._track(
-                                    should_track, id_value, __method_name__, tracked_dict, kwargs
+                                    should_track,
+                                    id_value,
+                                    __method_name__,
+                                    tracked_dict,
+                                    kwargs,
                                 )
                             except AttributeError:
-                                warnings.warn(
-                                    f"Tracking setup incomplete for AxisWrapper ({__method_name__}).",
-                                    UserWarning,
-                                    stacklevel=2,
+                                logger.warning(
+                                    f"Tracking setup incomplete for AxisWrapper ({__method_name__})."
                                 )
                             except Exception as e:
                                 # Silently continue if tracking fails to not break plotting
@@ -201,11 +248,9 @@ class AxisWrapper(MatplotlibPlotMixin, SeabornMixin, AdjustmentMixin, TrackingMi
         # 2. If not found on instance, try the counterpart type (fallback)
         if hasattr(self._counter_part, name):
             counterpart_attr = getattr(self._counter_part, name)
-            warnings.warn(
+            logger.warning(
                 f"SciTeX Axis_MplWrapper: '{name}' not directly handled. "
-                f"Falling back to underlying '{self._counter_part.__name__}' attribute.",
-                UserWarning,
-                stacklevel=2,
+                f"Falling back to underlying '{self._counter_part.__name__}' attribute."
             )
             # If the counterpart attribute is callable (likely a method descriptor)
             if callable(counterpart_attr):
@@ -233,47 +278,69 @@ class AxisWrapper(MatplotlibPlotMixin, SeabornMixin, AdjustmentMixin, TrackingMi
     def __dir__(self):
         # Start with attributes from the class and all parent classes (mixins)
         attrs = set()
-        
+
         # Get attributes from all parent classes including mixins
         for cls in self.__class__.__mro__:
             attrs.update(cls.__dict__.keys())
-        
+
         # Add instance attributes
         attrs.update(self.__dict__.keys())
-        
+
         # Safely get matplotlib axes attributes
         try:
             # Get attributes from the wrapped matplotlib axes
-            if hasattr(self._axes_mpl, '__class__'):
+            if hasattr(self._axes_mpl, "__class__"):
                 # Get class methods from matplotlib.axes.Axes
                 for cls in self._axes_mpl.__class__.__mro__:
-                    attrs.update(name for name in cls.__dict__.keys() if not name.startswith('_'))
-            
+                    attrs.update(
+                        name for name in cls.__dict__.keys() if not name.startswith("_")
+                    )
+
             # Add instance attributes of the matplotlib axes
-            if hasattr(self._axes_mpl, '__dict__'):
-                attrs.update(name for name in self._axes_mpl.__dict__.keys() if not name.startswith('_'))
-                
+            if hasattr(self._axes_mpl, "__dict__"):
+                attrs.update(
+                    name
+                    for name in self._axes_mpl.__dict__.keys()
+                    if not name.startswith("_")
+                )
+
         except Exception:
             # If any error occurs, add common matplotlib methods manually
-            attrs.update(['plot', 'scatter', 'bar', 'barh', 'hist', 'boxplot', 
-                         'set_xlabel', 'set_ylabel', 'set_title', 'legend',
-                         'set_xlim', 'set_ylim', 'grid', 'annotate', 'text'])
-        
+            attrs.update(
+                [
+                    "plot",
+                    "scatter",
+                    "bar",
+                    "barh",
+                    "hist",
+                    "boxplot",
+                    "set_xlabel",
+                    "set_ylabel",
+                    "set_title",
+                    "legend",
+                    "set_xlim",
+                    "set_ylim",
+                    "grid",
+                    "annotate",
+                    "text",
+                ]
+            )
+
         # Remove private attributes
-        attrs = {attr for attr in attrs if not attr.startswith('_')}
-        
+        attrs = {attr for attr in attrs if not attr.startswith("_")}
+
         return sorted(attrs)
-        
+
     def flatten(self):
         """Return a list containing just this axis.
-        
+
         This method makes AxisWrapper compatible with code that calls flatten()
         on an axes collection. It returns a list containing just this single axis
         to maintain consistency with AxesWrapper.flatten().
-        
+
         Returns:
             list: A list containing this axis wrapper
-            
+
         Example:
             # When working with either AxesWrapper or AxisWrapper, this works:
             axes_list = list(axes.flatten())

scitex/plt/_subplots/_AxisWrapperMixins/_AdjustmentMixin/__init__.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-13 (ywatanabe)"
+# File: __init__.py - AdjustmentMixin package
+
+"""
+AdjustmentMixin - Modular axis adjustment mixin for AxisWrapper.
+
+This package provides axis adjustment functionality split into logical submodules:
+- _labels: Label rotation and legend positioning
+- _metadata: Axis labels, titles, and scientific metadata
+- _visual: Visual adjustments (ticks, spines, extend, shift)
+"""
+
+import os
+
+__FILE__ = __file__
+__DIR__ = os.path.dirname(__FILE__)
+
+from ._labels import LabelsMixin
+from ._metadata import MetadataMixin
+from ._visual import VisualAdjustmentMixin
+
+
+class AdjustmentMixin(LabelsMixin, MetadataMixin, VisualAdjustmentMixin):
+    """Mixin class for matplotlib axis adjustments.
+
+    Combines multiple specialized mixins:
+    - LabelsMixin: Label rotation and legend positioning
+    - MetadataMixin: Axis labels, titles, and scientific metadata
+    - VisualAdjustmentMixin: Ticks, spines, extend, shift
+    """
+    pass
+
+
+# EOF

scitex/plt/_subplots/_AxisWrapperMixins/_AdjustmentMixin/_labels.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-13 (ywatanabe)"
+# File: _labels.py - Label rotation and legend handling
+
+"""Mixin for label rotation and legend positioning."""
+
+import os
+
+from scitex import logging
+
+__FILE__ = __file__
+__DIR__ = os.path.dirname(__FILE__)
+
+logger = logging.getLogger(__name__)
+
+
+class LabelsMixin:
+    """Mixin for label rotation and legend positioning."""
+
+    def _get_ax_module(self):
+        """Lazy import ax module to avoid circular imports."""
+        from .....plt import ax as ax_module
+        return ax_module
+
+    def rotate_labels(
+        self,
+        x: float = None,
+        y: float = None,
+        x_ha: str = None,
+        y_ha: str = None,
+        x_va: str = None,
+        y_va: str = None,
+        auto_adjust: bool = True,
+        scientific_convention: bool = True,
+        tight_layout: bool = False,
+    ) -> None:
+        """Rotate x and y axis labels with automatic positioning.
+
+        Parameters
+        ----------
+        x : float or None, optional
+            Rotation angle for x-axis labels in degrees.
+        y : float or None, optional
+            Rotation angle for y-axis labels in degrees.
+        x_ha, y_ha : str or None, optional
+            Horizontal alignment for x/y-axis labels.
+        x_va, y_va : str or None, optional
+            Vertical alignment for x/y-axis labels.
+        auto_adjust : bool, optional
+            Whether to automatically adjust alignment. Default is True.
+        scientific_convention : bool, optional
+            Whether to follow scientific conventions. Default is True.
+        tight_layout : bool, optional
+            Whether to apply tight_layout. Default is False.
+        """
+        self._axis_mpl = self._get_ax_module().rotate_labels(
+            self._axis_mpl,
+            x=x,
+            y=y,
+            x_ha=x_ha,
+            y_ha=y_ha,
+            x_va=x_va,
+            y_va=y_va,
+            auto_adjust=auto_adjust,
+            scientific_convention=scientific_convention,
+            tight_layout=tight_layout,
+        )
+
+    def legend(
+        self, *args, loc: str = "best", check_overlap: bool = False, **kwargs
+    ) -> None:
+        """Places legend at specified location, with support for outside positions.
+
+        Parameters
+        ----------
+        *args : tuple
+            Positional arguments (handles, labels) as in matplotlib
+        loc : str
+            Legend position. Default is "best" (matplotlib auto-placement).
+            Special positions:
+            - "best": Matplotlib automatic placement
+            - "outer": Place outside plot area (right side)
+            - "separate": Save legend as a separate figure file
+            - upper/lower/center variants: e.g. "upper right out"
+        check_overlap : bool
+            If True, checks for overlap between legend and data.
+        **kwargs : dict
+            Additional keyword arguments passed to legend()
+        """
+        import matplotlib.pyplot as plt
+
+        if loc == "outer":
+            legend = self._axis_mpl.legend(
+                *args, loc="center left", bbox_to_anchor=(1.02, 0.5), **kwargs
+            )
+            if hasattr(self, "_figure_wrapper") and self._figure_wrapper:
+                self._figure_wrapper._fig_mpl.tight_layout()
+                self._figure_wrapper._fig_mpl.subplots_adjust(right=0.85)
+            return legend
+
+        elif loc == "separate":
+            handles, labels = self._axis_mpl.get_legend_handles_labels()
+            if not handles:
+                logger.warning("No legend handles found.")
+                return None
+
+            fig = self._axis_mpl.get_figure()
+            if not hasattr(fig, "_separate_legend_params"):
+                fig._separate_legend_params = []
+
+            figsize = kwargs.pop("figsize", (4, 3))
+            dpi = kwargs.pop("dpi", 150)
+            frameon = kwargs.pop("frameon", True)
+            fancybox = kwargs.pop("fancybox", True)
+            shadow = kwargs.pop("shadow", True)
+
+            axis_id = self._get_axis_id(fig)
+
+            fig._separate_legend_params.append({
+                "axis": self._axis_mpl,
+                "axis_id": axis_id,
+                "handles": handles,
+                "labels": labels,
+                "figsize": figsize,
+                "dpi": dpi,
+                "frameon": frameon,
+                "fancybox": fancybox,
+                "shadow": shadow,
+                "kwargs": kwargs,
+            })
+
+            if self._axis_mpl.get_legend():
+                self._axis_mpl.get_legend().remove()
+
+            return None
+
+        outside_positions = {
+            "upper right out": ("center left", (1.15, 0.85)),
+            "right upper out": ("center left", (1.15, 0.85)),
+            "center right out": ("center left", (1.15, 0.5)),
+            "right out": ("center left", (1.15, 0.5)),
+            "right": ("center left", (1.05, 0.5)),
+            "lower right out": ("center left", (1.15, 0.15)),
+            "right lower out": ("center left", (1.15, 0.15)),
+            "upper left out": ("center right", (-0.25, 0.85)),
+            "left upper out": ("center right", (-0.25, 0.85)),
+            "center left out": ("center right", (-0.25, 0.5)),
+            "left out": ("center right", (-0.25, 0.5)),
+            "left": ("center right", (-0.15, 0.5)),
+            "lower left out": ("center right", (-0.25, 0.15)),
+            "left lower out": ("center right", (-0.25, 0.15)),
+            "upper center out": ("lower center", (0.5, 1.25)),
+            "upper out": ("lower center", (0.5, 1.25)),
+            "lower center out": ("upper center", (0.5, -0.25)),
+            "lower out": ("upper center", (0.5, -0.25)),
+        }
+
+        if loc in outside_positions:
+            location, bbox = outside_positions[loc]
+            legend_obj = self._axis_mpl.legend(
+                *args, loc=location, bbox_to_anchor=bbox, **kwargs
+            )
+        else:
+            legend_obj = self._axis_mpl.legend(*args, loc=loc, **kwargs)
+
+        if check_overlap and legend_obj is not None:
+            self._check_legend_overlap(legend_obj)
+
+        return legend_obj
+
+    def _get_axis_id(self, fig):
+        """Get unique axis identifier for separate legend handling."""
+        axis_id = None
+
+        try:
+            fig_axes = fig.get_axes()
+            for idx, ax in enumerate(fig_axes):
+                if ax is self._axis_mpl:
+                    axis_id = f"ax_{idx:02d}"
+                    break
+        except:
+            pass
+
+        if axis_id is None and hasattr(self._axis_mpl, "get_subplotspec"):
+            try:
+                spec = self._axis_mpl.get_subplotspec()
+                if spec is not None:
+                    gridspec = spec.get_gridspec()
+                    nrows, ncols = gridspec.get_geometry()
+                    rowspan = spec.rowspan
+                    colspan = spec.colspan
+                    row_start = rowspan.start if hasattr(rowspan, "start") else rowspan
+                    col_start = colspan.start if hasattr(colspan, "start") else colspan
+                    flat_idx = row_start * ncols + col_start
+                    axis_id = f"ax_{flat_idx:02d}"
+            except:
+                pass
+
+        if axis_id is None:
+            axis_id = f"ax_{len(fig._separate_legend_params):02d}"
+
+        return axis_id
+
+    def _check_legend_overlap(self, legend_obj):
+        """Check if legend overlaps with plotted data and issue warning if needed."""
+        import warnings
+        import matplotlib.transforms as transforms
+        import numpy as np
+
+        try:
+            fig = self._axis_mpl.get_figure()
+            fig.canvas.draw()
+
+            legend_bbox = legend_obj.get_window_extent(fig.canvas.get_renderer())
+            inv_transform = self._axis_mpl.transData.inverted()
+            legend_bbox_data = legend_bbox.transformed(inv_transform)
+
+            data_bboxes = []
+
+            for line in self._axis_mpl.get_lines():
+                if line.get_visible():
+                    try:
+                        data = line.get_xydata()
+                        if len(data) > 0:
+                            data_bboxes.append(data)
+                    except:
+                        pass
+
+            for collection in self._axis_mpl.collections:
+                if collection.get_visible():
+                    try:
+                        offsets = collection.get_offsets()
+                        if len(offsets) > 0:
+                            data_bboxes.append(offsets)
+                    except:
+                        pass
+
+            if data_bboxes:
+                all_data = np.vstack(data_bboxes)
+
+                x_overlap = (all_data[:, 0] >= legend_bbox_data.x0) & (
+                    all_data[:, 0] <= legend_bbox_data.x1
+                )
+                y_overlap = (all_data[:, 1] >= legend_bbox_data.y0) & (
+                    all_data[:, 1] <= legend_bbox_data.y1
+                )
+                overlap_points = np.sum(x_overlap & y_overlap)
+                overlap_pct = (overlap_points / len(all_data)) * 100
+
+                if overlap_pct > 5:
+                    logger.warning(
+                        f"Legend overlaps with {overlap_pct:.1f}% of data points. "
+                        f"Consider using loc='outer' or loc='separate'."
+                    )
+                    return True
+
+        except Exception:
+            pass
+
+        return False
+
+
+# EOF