scitex 2.7.0__py3-none-any.whl → 2.8.1__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,
@@ -25,7 +30,12 @@ from scitex.plt.styles import apply_plot_defaults, apply_plot_postprocess
 
 
 class AxisWrapper(
-    MatplotlibPlotMixin, SeabornMixin, AdjustmentMixin, TrackingMixin, UnitAwareMixin
+    MatplotlibPlotMixin,
+    SeabornMixin,
+    RawMatplotlibMixin,
+    AdjustmentMixin,
+    TrackingMixin,
+    UnitAwareMixin,
 ):
     def __init__(self, fig_scitex, axis_mpl, track):
         """Initialize the AxisWrapper.
@@ -219,10 +229,8 @@ class AxisWrapper(
                                     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
@@ -240,11 +248,9 @@ class AxisWrapper(
         # 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):

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

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

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-13 (ywatanabe)"
+# File: _metadata.py - Axis metadata and labels
+
+"""Mixin for axis labels, titles, and metadata."""
+
+import os
+from typing import Optional
+
+__FILE__ = __file__
+__DIR__ = os.path.dirname(__FILE__)
+
+
+class MetadataMixin:
+    """Mixin for setting axis labels, titles, and metadata."""
+
+    def _get_ax_module(self):
+        """Lazy import ax module to avoid circular imports."""
+        from .....plt import ax as ax_module
+        return ax_module
+
+    def set_xyt(
+        self,
+        x: Optional[str] = None,
+        y: Optional[str] = None,
+        t: Optional[str] = None,
+        format_labels: bool = True,
+    ) -> None:
+        """Set xlabel, ylabel, and title."""
+        self._axis_mpl = self._get_ax_module().set_xyt(
+            self._axis_mpl,
+            x=x,
+            y=y,
+            t=t,
+            format_labels=format_labels,
+        )
+
+    def set_xytc(
+        self,
+        x: Optional[str] = None,
+        y: Optional[str] = None,
+        t: Optional[str] = None,
+        c: Optional[str] = None,
+        format_labels: bool = True,
+    ) -> None:
+        """Set xlabel, ylabel, title, and caption for automatic saving.
+
+        Parameters
+        ----------
+        x : str, optional
+            X-axis label
+        y : str, optional
+            Y-axis label
+        t : str, optional
+            Title
+        c : str, optional
+            Caption to be saved automatically with scitex.io.save()
+        format_labels : bool, optional
+            Whether to apply automatic formatting, by default True
+        """
+        self._axis_mpl = self._get_ax_module().set_xytc(
+            self._axis_mpl,
+            x=x,
+            y=y,
+            t=t,
+            c=c,
+            format_labels=format_labels,
+        )
+
+        if c is not False and c is not None:
+            self._scitex_caption = c
+
+    def set_supxyt(
+        self,
+        xlabel: Optional[str] = None,
+        ylabel: Optional[str] = None,
+        title: Optional[str] = None,
+        format_labels: bool = True,
+    ) -> None:
+        """Set figure-level xlabel, ylabel, and title (suptitle)."""
+        self._axis_mpl = self._get_ax_module().set_supxyt(
+            self._axis_mpl,
+            xlabel=xlabel,
+            ylabel=ylabel,
+            title=title,
+            format_labels=format_labels,
+        )
+
+    def set_supxytc(
+        self,
+        xlabel: Optional[str] = None,
+        ylabel: Optional[str] = None,
+        title: Optional[str] = None,
+        caption: Optional[str] = None,
+        format_labels: bool = True,
+    ) -> None:
+        """Set figure-level xlabel, ylabel, title, and caption.
+
+        Parameters
+        ----------
+        xlabel : str, optional
+            Figure-level X-axis label
+        ylabel : str, optional
+            Figure-level Y-axis label
+        title : str, optional
+            Figure-level title (suptitle)
+        caption : str, optional
+            Figure-level caption for automatic saving
+        format_labels : bool, optional
+            Whether to apply automatic formatting
+        """
+        self._axis_mpl = self._get_ax_module().set_supxytc(
+            self._axis_mpl,
+            xlabel=xlabel,
+            ylabel=ylabel,
+            title=title,
+            caption=caption,
+            format_labels=format_labels,
+        )
+
+        if caption is not False and caption is not None:
+            fig = self._axis_mpl.get_figure()
+            fig._scitex_main_caption = caption
+
+    def set_meta(
+        self,
+        caption=None,
+        methods=None,
+        stats=None,
+        keywords=None,
+        experimental_details=None,
+        journal_style=None,
+        significance=None,
+        **kwargs,
+    ) -> None:
+        """Set comprehensive scientific metadata with YAML export capability.
+
+        Parameters
+        ----------
+        caption : str, optional
+            Figure caption text
+        methods : str, optional
+            Experimental methods description
+        stats : str, optional
+            Statistical analysis details
+        keywords : List[str], optional
+            Keywords for categorization
+        experimental_details : Dict[str, Any], optional
+            Structured experimental parameters
+        journal_style : str, optional
+            Target journal style
+        significance : str, optional
+            Significance statement
+        **kwargs : additional metadata
+        """
+        self._axis_mpl = self._get_ax_module().set_meta(
+            self._axis_mpl,
+            caption=caption,
+            methods=methods,
+            stats=stats,
+            keywords=keywords,
+            experimental_details=experimental_details,
+            journal_style=journal_style,
+            significance=significance,
+            **kwargs,
+        )
+
+    def set_figure_meta(
+        self,
+        caption=None,
+        methods=None,
+        stats=None,
+        significance=None,
+        funding=None,
+        conflicts=None,
+        data_availability=None,
+        **kwargs,
+    ) -> None:
+        """Set figure-level metadata for multi-panel figures.
+
+        Parameters
+        ----------
+        caption : str, optional
+            Figure-level caption
+        methods : str, optional
+            Overall experimental methods
+        stats : str, optional
+            Overall statistical approach
+        significance : str, optional
+            Significance and implications
+        funding : str, optional
+            Funding acknowledgments
+        conflicts : str, optional
+            Conflict of interest statement
+        data_availability : str, optional
+            Data availability statement
+        **kwargs : additional metadata
+        """
+        self._axis_mpl = self._get_ax_module().set_figure_meta(
+            self._axis_mpl,
+            caption=caption,
+            methods=methods,
+            stats=stats,
+            significance=significance,
+            funding=funding,
+            conflicts=conflicts,
+            data_availability=data_availability,
+            **kwargs,
+        )
+
+
+# EOF

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

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-13 (ywatanabe)"
+# File: _visual.py - Visual adjustments (ticks, spines, position)
+
+"""Mixin for visual adjustments including ticks, spines, and positioning."""
+
+import os
+from typing import List, Optional, Union
+
+__FILE__ = __file__
+__DIR__ = os.path.dirname(__FILE__)
+
+
+class VisualAdjustmentMixin:
+    """Mixin for visual adjustments to axis appearance."""
+
+    def _get_ax_module(self):
+        """Lazy import ax module to avoid circular imports."""
+        from .....plt import ax as ax_module
+        return ax_module
+
+    def set_ticks(
+        self,
+        xvals: Optional[List[Union[int, float]]] = None,
+        xticks: Optional[List[str]] = None,
+        yvals: Optional[List[Union[int, float]]] = None,
+        yticks: Optional[List[str]] = None,
+    ) -> None:
+        """Set custom tick positions and labels.
+
+        Parameters
+        ----------
+        xvals : list of numbers, optional
+            Positions for x-axis ticks
+        xticks : list of str, optional
+            Labels for x-axis ticks
+        yvals : list of numbers, optional
+            Positions for y-axis ticks
+        yticks : list of str, optional
+            Labels for y-axis ticks
+        """
+        self._axis_mpl = self._get_ax_module().set_ticks(
+            self._axis_mpl,
+            xvals=xvals,
+            xticks=xticks,
+            yvals=yvals,
+            yticks=yticks,
+        )
+
+    def set_n_ticks(self, n_xticks: int = 4, n_yticks: int = 4) -> None:
+        """Set the number of ticks on each axis.
+
+        Parameters
+        ----------
+        n_xticks : int, optional
+            Number of ticks on x-axis, by default 4
+        n_yticks : int, optional
+            Number of ticks on y-axis, by default 4
+        """
+        self._axis_mpl = self._get_ax_module().set_n_ticks(
+            self._axis_mpl, n_xticks=n_xticks, n_yticks=n_yticks
+        )
+
+    def hide_spines(
+        self,
+        top: bool = True,
+        bottom: bool = False,
+        left: bool = False,
+        right: bool = True,
+        ticks: bool = False,
+        labels: bool = False,
+    ) -> None:
+        """Hide specific spines and optionally ticks/labels.
+
+        Parameters
+        ----------
+        top : bool, optional
+            Hide top spine, by default True
+        bottom : bool, optional
+            Hide bottom spine, by default False
+        left : bool, optional
+            Hide left spine, by default False
+        right : bool, optional
+            Hide right spine, by default True
+        ticks : bool, optional
+            Hide all ticks, by default False
+        labels : bool, optional
+            Hide all tick labels, by default False
+        """
+        self._axis_mpl = self._get_ax_module().hide_spines(
+            self._axis_mpl,
+            top=top,
+            bottom=bottom,
+            left=left,
+            right=right,
+            ticks=ticks,
+            labels=labels,
+        )
+
+    def extend(self, x_ratio: float = 1.0, y_ratio: float = 1.0) -> None:
+        """Extend axis limits by a ratio.
+
+        Parameters
+        ----------
+        x_ratio : float, optional
+            Ratio to extend x-axis by, by default 1.0
+        y_ratio : float, optional
+            Ratio to extend y-axis by, by default 1.0
+        """
+        self._axis_mpl = self._get_ax_module().extend(
+            self._axis_mpl, x_ratio=x_ratio, y_ratio=y_ratio
+        )
+
+    def shift(self, dx: float = 0, dy: float = 0) -> None:
+        """Shift axis position.
+
+        Parameters
+        ----------
+        dx : float, optional
+            Horizontal shift, by default 0
+        dy : float, optional
+            Vertical shift, by default 0
+        """
+        self._axis_mpl = self._get_ax_module().shift(self._axis_mpl, dx=dx, dy=dy)
+
+
+# EOF