scitex 2.1.3__py3-none-any.whl → 2.4.0__py3-none-any.whl

scitex/plt/ax/_plot/_stx_shaded_line.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-01 13:15:00 (ywatanabe)"
+# File: ./src/scitex/plt/ax/_plot/_plot_shaded_line.py
+
+"""Line plots with shaded uncertainty regions (e.g., confidence intervals)."""
+
+from typing import Any, List, Optional, Tuple, Union
+
+import numpy as np
+import pandas as pd
+from matplotlib.axes import Axes
+
+from scitex.types import ColorLike
+from ....plt.utils import assert_valid_axis
+
+
+def _plot_single_shaded_line(
+    axis: Union[Axes, "AxisWrapper"],
+    xx: np.ndarray,
+    y_lower: np.ndarray,
+    y_middle: np.ndarray,
+    y_upper: np.ndarray,
+    color: Optional[ColorLike] = None,
+    alpha: float = 0.3,
+    **kwargs: Any,
+) -> Tuple[Union[Axes, "AxisWrapper"], pd.DataFrame]:
+    """Plot a single line with shaded area between y_lower and y_upper bounds.
+
+    Parameters
+    ----------
+    axis : matplotlib.axes.Axes or AxisWrapper
+        Axes to plot on.
+    xx : np.ndarray
+        X values.
+    y_lower : np.ndarray
+        Lower bound y values.
+    y_middle : np.ndarray
+        Middle (mean/median) y values.
+    y_upper : np.ndarray
+        Upper bound y values.
+    color : ColorLike, optional
+        Color for line and fill.
+    alpha : float, default 0.3
+        Transparency for shaded region.
+    **kwargs : dict
+        Additional keyword arguments passed to plot().
+
+    Returns
+    -------
+    axis : matplotlib.axes.Axes or AxisWrapper
+        The axes with the plot.
+    df : pd.DataFrame
+        DataFrame with x, y_lower, y_middle, y_upper columns.
+    """
+    assert_valid_axis(axis, "First argument must be a matplotlib axis or scitex axis wrapper")
+    assert (
+        len(xx) == len(y_middle) == len(y_lower) == len(y_upper)
+    ), "All arrays must have the same length"
+
+    label = kwargs.pop("label", None)
+    axis.plot(xx, y_middle, color=color, alpha=alpha, label=label, **kwargs)
+    kwargs["linewidth"] = 0
+    kwargs["edgecolor"] = "none"  # Remove edge line
+    axis.fill_between(xx, y_lower, y_upper, alpha=alpha, color=color, **kwargs)
+
+    return axis, pd.DataFrame(
+        {"x": xx, "y_lower": y_lower, "y_middle": y_middle, "y_upper": y_upper}
+    )
+
+
+def _plot_shaded_line(
+    axis: Union[Axes, "AxisWrapper"],
+    xs: List[np.ndarray],
+    ys_lower: List[np.ndarray],
+    ys_middle: List[np.ndarray],
+    ys_upper: List[np.ndarray],
+    color: Optional[Union[List[ColorLike], ColorLike]] = None,
+    **kwargs: Any,
+) -> Tuple[Union[Axes, "AxisWrapper"], List[pd.DataFrame]]:
+    """Plot multiple lines with shaded areas between ys_lower and ys_upper bounds.
+
+    Parameters
+    ----------
+    axis : matplotlib.axes.Axes or AxisWrapper
+        Axes to plot on.
+    xs : list of np.ndarray
+        List of x value arrays.
+    ys_lower : list of np.ndarray
+        List of lower bound y value arrays.
+    ys_middle : list of np.ndarray
+        List of middle y value arrays.
+    ys_upper : list of np.ndarray
+        List of upper bound y value arrays.
+    color : ColorLike or list of ColorLike, optional
+        Color(s) for lines and fills.
+    **kwargs : dict
+        Additional keyword arguments passed to plot().
+
+    Returns
+    -------
+    axis : matplotlib.axes.Axes or AxisWrapper
+        The axes with the plots.
+    results : list of pd.DataFrame
+        List of DataFrames with plot data.
+    """
+    assert_valid_axis(axis, "First argument must be a matplotlib axis or scitex axis wrapper")
+    assert (
+        len(xs) == len(ys_lower) == len(ys_middle) == len(ys_upper)
+    ), "All input lists must have the same length"
+
+    results = []
+    colors = color
+    color_list = colors
+
+    if colors is not None:
+        if not isinstance(colors, list):
+            color_list = [colors] * len(xs)
+        else:
+            assert len(colors) == len(xs), "Number of colors must match number of lines"
+            color_list = colors
+
+        for idx, (xx, y_lower, y_middle, y_upper) in enumerate(
+            zip(xs, ys_lower, ys_middle, ys_upper)
+        ):
+            this_kwargs = kwargs.copy()
+            this_kwargs["color"] = color_list[idx]
+            _, result_df = _plot_single_shaded_line(
+                axis, xx, y_lower, y_middle, y_upper, **this_kwargs
+            )
+            results.append(result_df)
+    else:
+        for xx, y_lower, y_middle, y_upper in zip(xs, ys_lower, ys_middle, ys_upper):
+            _, result_df = _plot_single_shaded_line(
+                axis, xx, y_lower, y_middle, y_upper, **kwargs
+            )
+            results.append(result_df)
+
+    return axis, results
+
+
+def stx_shaded_line(
+    axis: Union[Axes, "AxisWrapper"],
+    xs: Union[np.ndarray, List[np.ndarray]],
+    ys_lower: Union[np.ndarray, List[np.ndarray]],
+    ys_middle: Union[np.ndarray, List[np.ndarray]],
+    ys_upper: Union[np.ndarray, List[np.ndarray]],
+    color: Optional[Union[ColorLike, List[ColorLike]]] = None,
+    **kwargs: Any,
+) -> Tuple[Union[Axes, "AxisWrapper"], Union[pd.DataFrame, List[pd.DataFrame]]]:
+    """Plot line(s) with shaded uncertainty regions.
+
+    Automatically handles both single and multiple line cases. Useful for
+    plotting mean/median with confidence intervals or standard deviation bands.
+
+    Parameters
+    ----------
+    axis : matplotlib.axes.Axes or AxisWrapper
+        Axes to plot on.
+    xs : np.ndarray or list of np.ndarray
+        X values (single array or list of arrays for multiple lines).
+    ys_lower : np.ndarray or list of np.ndarray
+        Lower bound y values.
+    ys_middle : np.ndarray or list of np.ndarray
+        Middle (mean/median) y values.
+    ys_upper : np.ndarray or list of np.ndarray
+        Upper bound y values.
+    color : ColorLike or list of ColorLike, optional
+        Color(s) for lines and shaded regions.
+    **kwargs : dict
+        Additional keyword arguments passed to plot().
+
+    Returns
+    -------
+    axis : matplotlib.axes.Axes or AxisWrapper
+        The axes with the plot(s).
+    data : pd.DataFrame or list of pd.DataFrame
+        DataFrame(s) containing plot data with columns:
+        x, y_lower, y_middle, y_upper.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> import scitex as stx
+    >>> x = np.linspace(0, 10, 100)
+    >>> y_mean = np.sin(x)
+    >>> y_std = 0.2
+    >>> fig, ax = stx.plt.subplots()
+    >>> ax, df = stx.plt.ax.stx_shaded_line(
+    ...     ax, x, y_mean - y_std, y_mean, y_mean + y_std,
+    ...     color='blue', alpha=0.3
+    ... )
+    """
+    is_single = not (
+        isinstance(xs, list)
+        and isinstance(ys_lower, list)
+        and isinstance(ys_middle, list)
+        and isinstance(ys_upper, list)
+    )
+
+    if is_single:
+        assert (
+            len(xs) == len(ys_lower) == len(ys_middle) == len(ys_upper)
+        ), "All arrays must have the same length for single line plot"
+
+        return _plot_single_shaded_line(
+            axis, xs, ys_lower, ys_middle, ys_upper, color=color, **kwargs
+        )
+    else:
+        return _plot_shaded_line(
+            axis, xs, ys_lower, ys_middle, ys_upper, color=color, **kwargs
+        )
+
+
+# EOF

scitex/plt/ax/_plot/{_plot_violin.py → _stx_violin.py}

@@ -17,9 +17,9 @@ import seaborn as sns
 from ....plt.utils import assert_valid_axis
 
 
-def plot_violin(
+def stx_violin(
     ax,
-    data_list,
+    values_list,
     labels=None,
     colors=None,
     half=False,
@@ -32,10 +32,10 @@ def plot_violin(
     ----------
     ax : matplotlib.axes.Axes or scitex.plt._subplots.AxisWrapper
         The axes to plot on
-    data_list : list
-        List of arrays to plot as violins
+    values_list : list of array-like, shape (n_groups,) where each element is (n_samples,)
+        List of 1D arrays to plot as violins, one per group
     labels : list, optional
-        Labels for each array in data_list
+        Labels for each array in values_list
     colors : list, optional
         Colors for each violin
     half : bool, optional
@@ -48,11 +48,18 @@ def plot_violin(
     ax : matplotlib.axes.Axes or scitex.plt._subplots.AxisWrapper
         The axes object with the plot
     """
+    # Add sample size to label if provided (show range if variable)
+    if kwargs.get("label"):
+        n_per_group = [len(g) for g in values_list]
+        n_min, n_max = min(n_per_group), max(n_per_group)
+        n_str = str(n_min) if n_min == n_max else f"{n_min}-{n_max}"
+        kwargs["label"] = f"{kwargs['label']} ($n$={n_str})"
+
     # Convert list-style data to DataFrame
     all_values = []
     all_groups = []
 
-    for idx, values in enumerate(data_list):
+    for idx, values in enumerate(values_list):
         all_values.extend(values)
         group_label = labels[idx] if labels and idx < len(labels) else f"x {idx}"
         all_groups.extend([group_label] * len(values))

scitex/plt/ax/_style/__init__.py

@@ -11,6 +11,7 @@ __DIR__ = os.path.dirname(__FILE__)
 
 from ._add_marginal_ax import add_marginal_ax
 from ._add_panel import add_panel
+from ._auto_scale_axis import auto_scale_axis
 from ._extend import extend
 from ._force_aspect import force_aspect
 from ._format_label import format_label
@@ -34,5 +35,8 @@ from ._share_axes import (
     set_ylims,
 )
 from ._shift import shift
+from ._show_spines import show_spines
+from ._style_boxplot import style_boxplot
+from ._style_violinplot import style_violinplot
 
 # EOF

scitex/plt/ax/_style/_auto_scale_axis.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Time-stamp: "2025-11-19 18:45:00 (ywatanabe)"
+# File: ./src/scitex/plt/ax/_style/_auto_scale_axis.py
+
+"""
+Automatic axis scaling to factor out common powers of 10.
+
+This utility automatically detects when axis tick values are very small or very large
+and factors out the appropriate power of 10, updating both the tick labels and axis label.
+
+Examples:
+    0.0000, 0.0008, 0.0016, 0.0024  →  0, 0.8, 1.6, 2.4  with label "[×10⁻³]"
+    10000, 20000, 30000, 40000      →  10, 20, 30, 40    with label "[×10³]"
+"""
+
+import numpy as np
+from typing import Optional, Tuple
+
+
+def detect_scale_factor(values: np.ndarray, threshold: float = 1e-2) -> Tuple[int, bool]:
+    """
+    Detect appropriate power of 10 to factor out from axis values.
+
+    Parameters
+    ----------
+    values : np.ndarray
+        Array of tick values on the axis
+    threshold : float
+        Threshold below which we consider factoring out (default: 0.01)
+
+    Returns
+    -------
+    power : int
+        Power of 10 to factor out (e.g., -3 for values like 0.001-0.009)
+    should_scale : bool
+        Whether scaling should be applied
+
+    Examples
+    --------
+    >>> detect_scale_factor(np.array([0.0, 0.0008, 0.0016, 0.0024]))
+    (-3, True)
+    >>> detect_scale_factor(np.array([10000, 20000, 30000]))
+    (3, True)
+    >>> detect_scale_factor(np.array([0, 1, 2, 3]))
+    (0, False)
+    """
+    # Filter out zero values for calculation
+    nonzero_values = values[values != 0]
+
+    if len(nonzero_values) == 0:
+        return 0, False
+
+    # Get the order of magnitude of the maximum absolute value
+    max_abs = np.max(np.abs(nonzero_values))
+
+    # Check if values are very small (< threshold) or very large (> 1/threshold)
+    if max_abs < threshold:
+        # Values are very small - factor out negative power
+        power = int(np.floor(np.log10(max_abs)))
+        return power, True
+    elif max_abs > 1.0 / threshold:
+        # Values are very large - factor out positive power
+        power = int(np.floor(np.log10(max_abs)))
+        # Only scale if power >= 3 (thousands or larger)
+        if power >= 3:
+            return power, True
+
+    return 0, False
+
+
+def format_scale_factor(power: int) -> str:
+    """
+    Format the scale factor for display in axis label.
+
+    Parameters
+    ----------
+    power : int
+        Power of 10 (e.g., -3, 3, 6)
+
+    Returns
+    -------
+    str
+        Formatted string using matplotlib mathtext (e.g., "×10$^{-3}$", "×10$^{6}$")
+
+    Examples
+    --------
+    >>> format_scale_factor(-3)
+    '×10$^{-3}$'
+    >>> format_scale_factor(6)
+    '×10$^{6}$'
+    """
+    if power == 0:
+        return ""
+
+    # Use matplotlib's mathtext for reliable rendering across all formats
+    return f"×10$^{{{power}}}$"
+
+
+def auto_scale_axis(ax, axis: str = 'both', threshold: float = 1e-2) -> None:
+    """
+    Automatically scale axis to factor out common powers of 10.
+
+    This function:
+    1. Detects when tick values are very small or very large
+    2. Factors out the appropriate power of 10
+    3. Updates tick labels to show factored values
+    4. Appends the scale factor to the axis label
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        Axes object to apply scaling to
+    axis : str, optional
+        Which axis to scale: 'x', 'y', or 'both' (default: 'both')
+    threshold : float, optional
+        Threshold for triggering scaling (default: 1e-2)
+        Values with max < threshold or max > 1/threshold will be scaled
+
+    Examples
+    --------
+    >>> import matplotlib.pyplot as plt
+    >>> fig, ax = plt.subplots()
+    >>> ax.plot([0, 1, 2], [0.0001, 0.0002, 0.0003])
+    >>> ax.set_ylabel('Density')
+    >>> auto_scale_axis(ax, axis='y')
+    >>> # Y-axis now shows: 0.1, 0.2, 0.3 with label "Density [×10⁻³]"
+
+    Notes
+    -----
+    - Only scales if the range of values justifies it (very small or very large)
+    - Preserves the original axis label and appends the scale factor
+    - Uses Unicode superscripts for clean display (×10⁻³, ×10⁶, etc.)
+    """
+    import matplotlib.ticker as ticker
+
+    def scale_axis_impl(ax_obj, is_x_axis: bool):
+        """Internal implementation for scaling a single axis."""
+        # Get current tick values
+        if is_x_axis:
+            tick_values = np.array(ax_obj.get_xticks())
+            get_label = ax_obj.get_xlabel
+            set_label = ax_obj.set_xlabel
+            set_formatter = ax_obj.xaxis.set_major_formatter
+        else:
+            tick_values = np.array(ax_obj.get_yticks())
+            get_label = ax_obj.get_ylabel
+            set_label = ax_obj.set_ylabel
+            set_formatter = ax_obj.yaxis.set_major_formatter
+
+        # Detect if scaling is needed
+        power, should_scale = detect_scale_factor(tick_values, threshold)
+
+        if not should_scale:
+            return
+
+        # Create scaling factor
+        scale_factor = 10 ** power
+
+        # Update tick formatter to show scaled values
+        def format_func(value, pos):
+            scaled_value = value / scale_factor
+            # Format with appropriate precision
+            if abs(scaled_value) < 10:
+                return f'{scaled_value:.1f}'
+            else:
+                return f'{scaled_value:.0f}'
+
+        set_formatter(ticker.FuncFormatter(format_func))
+
+        # Update axis label with scale factor
+        current_label = get_label()
+        scale_str = format_scale_factor(power)
+
+        # Check if label already has units in brackets
+        if '[' in current_label and ']' in current_label:
+            # Insert scale factor before the closing bracket
+            # e.g., "Density [a.u.]" → "Density [×10⁻³ a.u.]"
+            label_parts = current_label.rsplit(']', 1)
+            new_label = f"{label_parts[0]} {scale_str}]{label_parts[1]}"
+        else:
+            # Append scale factor in brackets
+            # e.g., "Density" → "Density [×10⁻³]"
+            new_label = f"{current_label} [{scale_str}]" if current_label else f"[{scale_str}]"
+
+        set_label(new_label)
+
+    # Apply to requested axes
+    if axis in ['x', 'both']:
+        scale_axis_impl(ax, is_x_axis=True)
+    if axis in ['y', 'both']:
+        scale_axis_impl(ax, is_x_axis=False)
+
+
+# EOF

scitex/plt/ax/_style/_format_units.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-11-19 15:10:00 (ywatanabe)"
+# File: ./src/scitex/plt/ax/_style/_format_units.py
+
+"""
+Utility functions for formatting axis labels with proper unit notation.
+"""
+
+from typing import Optional
+
+
+def format_label(label: str, unit: Optional[str] = None) -> str:
+    """
+    Format axis label with unit in brackets (publication standard).
+
+    Parameters
+    ----------
+    label : str
+        The label text (e.g., "Time", "Voltage")
+    unit : str, optional
+        The unit (e.g., "s", "mV", "Hz"). If None, returns label as-is.
+
+    Returns
+    -------
+    str
+        Formatted label with unit in brackets (e.g., "Time [s]")
+
+    Examples
+    --------
+    >>> stx.ax.format_label("Time", "s")
+    'Time [s]'
+
+    >>> stx.ax.format_label("Voltage", "mV")
+    'Voltage [mV]'
+
+    >>> stx.ax.format_label("Count")
+    'Count'
+
+    >>> # Direct usage with axis
+    >>> ax.set_xlabel(stx.ax.format_label("Time", "s"))
+    >>> ax.set_ylabel(stx.ax.format_label("Amplitude", "mV"))
+
+    Notes
+    -----
+    According to publication standards (Nature, Science, Cell), units should be
+    enclosed in square brackets, not parentheses:
+    - Correct: "Time [s]", "Voltage [mV]"
+    - Incorrect: "Time (s)", "Voltage (mV)"
+    """
+    if unit is None or unit == "":
+        return label
+    return f"{label} [{unit}]"
+
+
+def format_label_auto(text: str) -> str:
+    """
+    Automatically convert parentheses-style units to bracket-style.
+
+    This function detects units in parentheses and converts them to brackets.
+
+    Parameters
+    ----------
+    text : str
+        Label text, possibly with units in parentheses
+
+    Returns
+    -------
+    str
+        Label text with units in brackets
+
+    Examples
+    --------
+    >>> stx.ax.format_label_auto("Time (s)")
+    'Time [s]'
+
+    >>> stx.ax.format_label_auto("Voltage (mV)")
+    'Voltage [mV]'
+
+    >>> stx.ax.format_label_auto("Count")
+    'Count'
+
+    Notes
+    -----
+    This is useful for automatically correcting existing labels that use
+    parentheses notation.
+    """
+    import re
+
+    # Pattern to match units in parentheses at the end of the string
+    # e.g., "Time (s)" or "Frequency (Hz)"
+    pattern = r'\s*\(([^)]+)\)\s*$'
+
+    match = re.search(pattern, text)
+    if match:
+        unit = match.group(1)
+        label = text[:match.start()].strip()
+        return f"{label} [{unit}]"
+
+    return text
+
+
+# EOF

scitex/plt/ax/_style/_set_ticks.py

@@ -12,8 +12,8 @@ __DIR__ = os.path.dirname(__FILE__)
 import matplotlib.pyplot as plt
 import numpy as np
 
-from ....dict._to_str import to_str
-from ....types import is_listed_X
+from scitex.dict._to_str import to_str
+from scitex.types import is_listed_X
 
 
 def set_ticks(ax, xvals=None, xticks=None, yvals=None, yticks=None):

scitex/plt/ax/_style/_style_barplot.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-01 20:00:00 (ywatanabe)"
+# File: ./src/scitex/plt/ax/_style/_style_barplot.py
+
+"""
+Style bar plot elements with millimeter-based control.
+
+Default values are loaded from SCITEX_STYLE.yaml via presets.py.
+"""
+
+from typing import Optional, Union, List
+
+from scitex.plt.styles.presets import SCITEX_STYLE
+
+# Get defaults from centralized config
+_DEFAULT_EDGE_THICKNESS_MM = SCITEX_STYLE.get("bar_edge_thickness_mm", 0.2)
+
+
+def style_barplot(
+    bar_container,
+    edge_thickness_mm: float = None,
+    edgecolor: Optional[Union[str, List[str]]] = 'black',
+):
+    """
+    Apply consistent styling to matplotlib bar plot elements.
+
+    Parameters
+    ----------
+    bar_container : BarContainer
+        Container returned by ax.bar() or ax.barh()
+    edge_thickness_mm : float, optional
+        Edge line thickness in millimeters (default: 0.2mm)
+    edgecolor : str or list of str, optional
+        Edge color(s) for bars. If None, uses default matplotlib colors.
+
+    Returns
+    -------
+    bar_container : BarContainer
+        The styled bar container
+
+    Examples
+    --------
+    >>> fig, ax = stx.plt.subplots(**stx.plt.presets.NATURE_STYLE)
+    >>> bars = ax.bar(x, heights)
+    >>> stx.plt.ax.style_barplot(bars, edge_thickness_mm=0.2, edgecolor='black')
+    """
+    from scitex.plt.utils import mm_to_pt
+
+    # Use centralized default if not specified
+    if edge_thickness_mm is None:
+        edge_thickness_mm = _DEFAULT_EDGE_THICKNESS_MM
+
+    # Convert mm to points
+    lw_pt = mm_to_pt(edge_thickness_mm)
+
+    # Style each bar
+    for i, bar in enumerate(bar_container):
+        bar.set_linewidth(lw_pt)
+        if edgecolor is not None:
+            if isinstance(edgecolor, list):
+                bar.set_edgecolor(edgecolor[i % len(edgecolor)])
+            else:
+                bar.set_edgecolor(edgecolor)
+
+    return bar_container
+
+
+# EOF