scitex 2.0.0__py2.py3-none-any.whl

scitex/plt/ax/_style/_show_spines.py

@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Time-stamp: "2025-06-04 11:15:00 (ywatanabe)"
+# File: ./src/scitex/plt/ax/_style/_show_spines.py
+
+"""
+Functionality:
+    Show spines for matplotlib axes with intuitive API
+Input:
+    Matplotlib axes object and spine visibility parameters
+Output:
+    Axes with specified spines made visible
+Prerequisites:
+    matplotlib
+"""
+
+import matplotlib
+from typing import Union, List
+
+
+def show_spines(
+    axis,
+    top: bool = True,
+    bottom: bool = True,
+    left: bool = True,
+    right: bool = True,
+    ticks: bool = True,
+    labels: bool = True,
+    restore_defaults: bool = True,
+    spine_width: float = None,
+    spine_color: str = None
+):
+    """
+    Shows the specified spines of a matplotlib Axes object and optionally restores ticks and labels.
+
+    This function provides the intuitive counterpart to hide_spines. It's especially useful when
+    you have spines hidden by default (as in scitex configuration) and want to selectively show them
+    for clearer scientific plots or specific visualization needs.
+
+    Parameters
+    ----------
+    axis : matplotlib.axes.Axes
+        The Axes object for which the spines will be shown.
+    top : bool, optional
+        If True, shows the top spine. Defaults to True.
+    bottom : bool, optional
+        If True, shows the bottom spine. Defaults to True.
+    left : bool, optional
+        If True, shows the left spine. Defaults to True.
+    right : bool, optional
+        If True, shows the right spine. Defaults to True.
+    ticks : bool, optional
+        If True, restores ticks on the shown spines' axes. Defaults to True.
+    labels : bool, optional
+        If True, restores labels on the shown spines' axes. Defaults to True.
+    restore_defaults : bool, optional
+        If True, restores default tick positions and labels. Defaults to True.
+    spine_width : float, optional
+        Width of the spines to show. If None, uses matplotlib default.
+    spine_color : str, optional
+        Color of the spines to show. If None, uses matplotlib default.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+        The modified Axes object with the specified spines shown.
+
+    Examples
+    --------
+    >>> fig, ax = plt.subplots()
+    >>> # Show only bottom and left spines (classic scientific plot style)
+    >>> show_spines(ax, top=False, right=False)
+    >>> plt.show()
+
+    >>> # Show all spines with custom styling
+    >>> show_spines(ax, spine_width=1.5, spine_color='black')
+    >>> plt.show()
+
+    >>> # Show spines but without ticks/labels (for clean overlay plots)
+    >>> show_spines(ax, ticks=False, labels=False)
+    >>> plt.show()
+
+    Notes
+    -----
+    This function is designed to work seamlessly with scitex plotting where spines are hidden
+    by default. It provides an intuitive API for showing spines without needing to remember
+    that hide_spines(top=False, right=False) shows top and right spines.
+    """
+    # Handle both matplotlib axes and scitex AxisWrapper
+    if hasattr(axis, '_axis_mpl'):
+        # This is an scitex AxisWrapper, get the underlying matplotlib axis
+        axis = axis._axis_mpl
+    
+    assert isinstance(
+        axis, matplotlib.axes._axes.Axes
+    ), "First argument must be a matplotlib axis or scitex AxisWrapper"
+
+    # Define which spines to show
+    spine_settings = {
+        "top": top,
+        "bottom": bottom,
+        "left": left,
+        "right": right
+    }
+
+    for spine_name, should_show in spine_settings.items():
+        # Set spine visibility
+        axis.spines[spine_name].set_visible(should_show)
+        
+        if should_show:
+            # Set spine width if specified
+            if spine_width is not None:
+                axis.spines[spine_name].set_linewidth(spine_width)
+            
+            # Set spine color if specified
+            if spine_color is not None:
+                axis.spines[spine_name].set_color(spine_color)
+
+    # Restore ticks if requested
+    if ticks and restore_defaults:
+        # Determine tick positions based on which spines are shown
+        if bottom and not top:
+            axis.xaxis.set_ticks_position('bottom')
+        elif top and not bottom:
+            axis.xaxis.set_ticks_position('top')
+        elif bottom and top:
+            axis.xaxis.set_ticks_position('both')
+        
+        if left and not right:
+            axis.yaxis.set_ticks_position('left')
+        elif right and not left:
+            axis.yaxis.set_ticks_position('right')
+        elif left and right:
+            axis.yaxis.set_ticks_position('both')
+
+    # Restore labels if requested and restore_defaults is True
+    if labels and restore_defaults:
+        # Only restore if we haven't explicitly hidden them
+        # This preserves any custom tick labels that might have been set
+        current_xticks = axis.get_xticks()
+        current_yticks = axis.get_yticks()
+        
+        if len(current_xticks) > 0 and (bottom or top):
+            # Generate default labels for x-axis
+            if not hasattr(axis, '_original_xticklabels'):
+                axis.set_xticks(current_xticks)
+        
+        if len(current_yticks) > 0 and (left or right):
+            # Generate default labels for y-axis  
+            if not hasattr(axis, '_original_yticklabels'):
+                axis.set_yticks(current_yticks)
+
+    return axis
+
+
+def show_all_spines(
+    axis,
+    spine_width: float = None,
+    spine_color: str = None,
+    ticks: bool = True,
+    labels: bool = True
+):
+    """
+    Convenience function to show all spines with optional styling.
+    
+    Parameters
+    ----------
+    axis : matplotlib.axes.Axes
+        The Axes object to modify.
+    spine_width : float, optional
+        Width of all spines.
+    spine_color : str, optional
+        Color of all spines.
+    ticks : bool, optional
+        Whether to show ticks. Defaults to True.
+    labels : bool, optional
+        Whether to show labels. Defaults to True.
+        
+    Returns
+    -------
+    matplotlib.axes.Axes
+        The modified Axes object.
+        
+    Examples
+    --------
+    >>> show_all_spines(ax, spine_width=1.2, spine_color='gray')
+    """
+    return show_spines(
+        axis,
+        top=True, bottom=True, left=True, right=True,
+        ticks=ticks, labels=labels,
+        spine_width=spine_width, spine_color=spine_color
+    )
+
+
+def show_classic_spines(
+    axis,
+    spine_width: float = None,
+    spine_color: str = None,
+    ticks: bool = True,
+    labels: bool = True
+):
+    """
+    Show only bottom and left spines (classic scientific plot style).
+    
+    Parameters
+    ----------
+    axis : matplotlib.axes.Axes
+        The Axes object to modify.
+    spine_width : float, optional
+        Width of the spines.
+    spine_color : str, optional
+        Color of the spines.
+    ticks : bool, optional
+        Whether to show ticks. Defaults to True.
+    labels : bool, optional
+        Whether to show labels. Defaults to True.
+        
+    Returns
+    -------
+    matplotlib.axes.Axes
+        The modified Axes object.
+        
+    Examples
+    --------
+    >>> show_classic_spines(ax)  # Shows only bottom and left spines
+    """
+    return show_spines(
+        axis,
+        top=False, bottom=True, left=True, right=False,
+        ticks=ticks, labels=labels,
+        spine_width=spine_width, spine_color=spine_color
+    )
+
+
+def show_box_spines(
+    axis,
+    spine_width: float = None,
+    spine_color: str = None,
+    ticks: bool = True,
+    labels: bool = True
+):
+    """
+    Show all four spines to create a box around the plot.
+    
+    This is an alias for show_all_spines but with more descriptive naming
+    for when you specifically want a boxed appearance.
+    
+    Parameters
+    ----------
+    axis : matplotlib.axes.Axes
+        The Axes object to modify.
+    spine_width : float, optional
+        Width of the box spines.
+    spine_color : str, optional
+        Color of the box spines.
+    ticks : bool, optional
+        Whether to show ticks. Defaults to True.
+    labels : bool, optional
+        Whether to show labels. Defaults to True.
+        
+    Returns
+    -------
+    matplotlib.axes.Axes
+        The modified Axes object.
+        
+    Examples
+    --------
+    >>> show_box_spines(ax, spine_width=1.0, spine_color='black')
+    """
+    return show_all_spines(axis, spine_width, spine_color, ticks, labels)
+
+
+def toggle_spines(
+    axis,
+    top: bool = None,
+    bottom: bool = None,
+    left: bool = None,
+    right: bool = None
+):
+    """
+    Toggle the visibility of spines (show if hidden, hide if shown).
+    
+    Parameters
+    ----------
+    axis : matplotlib.axes.Axes
+        The Axes object to modify.
+    top : bool, optional
+        If specified, sets top spine visibility. If None, toggles current state.
+    bottom : bool, optional
+        If specified, sets bottom spine visibility. If None, toggles current state.
+    left : bool, optional
+        If specified, sets left spine visibility. If None, toggles current state.
+    right : bool, optional
+        If specified, sets right spine visibility. If None, toggles current state.
+        
+    Returns
+    -------
+    matplotlib.axes.Axes
+        The modified Axes object.
+        
+    Examples
+    --------
+    >>> toggle_spines(ax)  # Toggles all spines
+    >>> toggle_spines(ax, top=True, right=True)  # Shows top and right, toggles others
+    """
+    spine_names = ['top', 'bottom', 'left', 'right']
+    spine_params = [top, bottom, left, right]
+    
+    for spine_name, param in zip(spine_names, spine_params):
+        if param is None:
+            # Toggle current state
+            current_state = axis.spines[spine_name].get_visible()
+            axis.spines[spine_name].set_visible(not current_state)
+        else:
+            # Set specific state
+            axis.spines[spine_name].set_visible(param)
+    
+    return axis
+
+
+# Convenient aliases for common use cases
+def scientific_spines(axis, **kwargs):
+    """Alias for show_classic_spines - shows only bottom and left spines."""
+    return show_classic_spines(axis, **kwargs)
+
+
+def clean_spines(axis, **kwargs):
+    """Alias for showing no spines - useful for overlay plots or clean visualizations."""
+    return show_spines(axis, top=False, bottom=False, left=False, right=False, **kwargs)
+
+
+# EOF

scitex/plt/color/_PARAMS.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-05-02 09:14:09 (ywatanabe)"
+# File: /home/ywatanabe/proj/_scitex_repo/src/scitex/plt/colors/_PARAMS.py
+# ----------------------------------------
+import os
+
+__FILE__ = "./src/scitex/plt/colors/_PARAMS.py"
+__DIR__ = os.path.dirname(__FILE__)
+# ----------------------------------------
+
+# RGB
+RGB = {
+    "white": [255, 255, 255],
+    "black": [0, 0, 0],
+    "blue": [0, 128, 192],
+    "red": [255, 70, 50],
+    "pink": [255, 150, 200],
+    "green": [20, 180, 20],
+    "yellow": [230, 160, 20],
+    "gray": [128, 128, 128],
+    "grey": [128, 128, 128],
+    "purple": [200, 50, 255],
+    "light_blue": [20, 200, 200],
+    "brown": [128, 0, 0],
+    "navy": [0, 0, 100],
+    "orange": [228, 94, 50],
+}
+
+RGB_NORM = {
+    k: [round(r / 255, 2), round(g / 255, 2), round(b / 255, 2)]
+    for k, (r, g, b) in RGB.items()
+}
+
+# RGBA
+DEF_ALPHA = 0.9
+RGBA = {k: [r, g, b, DEF_ALPHA] for k, (r, g, b) in RGB.items()}
+RGBA_NORM = {k: [r, g, b, DEF_ALPHA] for k, (r, g, b) in RGB_NORM.items()}
+RGBA_NORM_FOR_CYCLE = {
+    k: v for k, v in RGBA_NORM.items() if k not in ["white", "grey", "black"]
+}
+
+# HEX
+HEX = {
+    "blue": "#0080C0",
+    "red": "#FF4632",
+    "pink": "#FF96C8",
+    "green": "#14B414",
+    "yellow": "#E6A014",
+    "gray": "#808080",
+    "grey": "#808080",
+    "purple": "#C832FF",
+    "light_blue": "#14C8C8",
+    "brown": "#800000",
+    "navy": "#000064",
+    "orange": "#E45E32",
+}
+
+
+PARAMS = dict(
+    RGB=RGB,
+    RGBA=RGBA,
+    RGBA_NORM=RGBA_NORM,
+    RGBA_NORM_FOR_CYCLE=RGBA_NORM_FOR_CYCLE,
+    HEX=HEX,
+)
+
+# pprint(PARAMS)
+
+# EOF

scitex/plt/color/__init__.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Scitex color module."""
+
+from ._add_hue_col import add_hue_col
+from ._colors import bgr2bgra, bgr2rgb, bgra2bgr, bgra2hex, bgra2rgba, cycle_color, cycle_color_bgr, cycle_color_rgb, gradiate_color, gradiate_color_bgr, gradiate_color_bgra, gradiate_color_rgb, gradiate_color_rgba, rgb2bgr, rgb2rgba, rgba2bgra, rgba2hex, rgba2rgb, str2bgr, str2bgra, str2hex, str2rgb, str2rgba, to_hex, to_rgb, to_rgba, update_alpha
+from ._get_colors_from_cmap import get_categorical_colors_from_cmap, get_color_from_cmap, get_colors_from_cmap
+from ._interpolate import gen_interpolate, interpolate
+from ._PARAMS import PARAMS, DEF_ALPHA, RGB, RGB_NORM, RGBA, RGBA_NORM
+from ._vizualize_colors import vizualize_colors
+
+__all__ = [
+    "PARAMS",
+    "DEF_ALPHA",
+    "RGB",
+    "RGB_NORM",
+    "RGBA",
+    "RGBA_NORM",
+    "add_hue_col",
+    "bgr2bgra",
+    "bgr2rgb",
+    "bgra2bgr",
+    "bgra2hex",
+    "bgra2rgba",
+    "cycle_color",
+    "cycle_color_bgr",
+    "cycle_color_rgb",
+    "gen_interpolate",
+    "get_categorical_colors_from_cmap",
+    "get_color_from_cmap",
+    "get_colors_from_cmap",
+    "gradiate_color",
+    "gradiate_color_bgr",
+    "gradiate_color_bgra",
+    "gradiate_color_rgb",
+    "gradiate_color_rgba",
+    "interpolate",
+    "rgb2bgr",
+    "rgb2rgba",
+    "rgba2bgra",
+    "rgba2hex",
+    "rgba2rgb",
+    "str2bgr",
+    "str2bgra",
+    "str2hex",
+    "str2rgb",
+    "str2rgba",
+    "to_hex",
+    "to_rgb",
+    "to_rgba",
+    "update_alpha",
+    "vizualize_colors",
+]

scitex/plt/color/_add_hue_col.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-05-02 18:02:24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex_repo/src/scitex/plt/color/_add_hue_col.py
+# ----------------------------------------
+import os
+
+__FILE__ = "./src/scitex/plt/color/_add_hue_col.py"
+__DIR__ = os.path.dirname(__FILE__)
+# ----------------------------------------
+
+import numpy as np
+import pandas as pd
+
+
+def add_hue_col(df):
+    df["hue"] = 0
+    dummy_row = pd.DataFrame(
+        columns=df.columns,
+        data=np.array([np.nan for _ in df.columns]).reshape(1, -1),
+    )
+    dummy_row = {}
+    for col in df.columns:
+        dtype = df[col].dtype
+        if dtype is np.dtype(object):
+            dummy_row[col] = np.nan
+        if dtype is np.dtype(float):
+            dummy_row[col] = np.nan
+        if dtype is np.dtype(np.int64):
+            dummy_row[col] = np.nan
+        if dtype is np.dtype(bool):
+            dummy_row[col] = None
+
+    dummy_row = pd.DataFrame(pd.Series(dummy_row)).T
+
+    dummy_row["hue"] = 1
+    df_added = pd.concat([df, dummy_row], axis=0)
+    return df_added
+
+
+# EOF

scitex/plt/color/_colors.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-05-02 12:19:50 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex_repo/src/scitex/plt/colors/_colors.py
+# ----------------------------------------
+import os
+
+__FILE__ = "./src/scitex/plt/colors/_colors.py"
+__DIR__ = os.path.dirname(__FILE__)
+# ----------------------------------------
+
+import matplotlib.colors as _colors
+import numpy as np
+
+from ...decorators._deprecated import deprecated
+from ._PARAMS import PARAMS
+
+# RGB
+# ------------------------------
+
+
+def str2rgb(c):
+    return PARAMS["RGB"][c]
+
+
+def str2rgba(c, alpha=1.0):
+    rgba = rgb2rgba(PARAMS["RGB"][c])
+    rgba[-1] = alpha
+    return rgba
+
+
+def rgb2rgba(rgb, alpha=1.0, round=2):
+    rgb = np.array(rgb).astype(float)
+    rgb /= 255
+    return [*rgb.round(round), alpha]
+
+
+def rgba2rgb(rgba):
+    rgba = np.array(rgba).astype(float)
+    rgb = (rgba[:3] * 255).clip(0, 255)
+    return rgb.round(2).tolist()
+
+
+def rgba2hex(rgba):
+    return "#{:02x}{:02x}{:02x}{:02x}".format(
+        int(rgba[0]), int(rgba[1]), int(rgba[2]), int(rgba[3] * 255)
+    )
+
+
+def cycle_color_rgb(i_color, colors=None):
+    if colors is None:
+        colors = list(PARAMS["RGB"].keys())
+    n_colors = len(colors)
+    return colors[i_color % n_colors]
+
+
+def gradiate_color_rgb(rgb_or_rgba, n=5):
+
+    # Separate RGB and alpha if present
+    if len(rgb_or_rgba) == 4:  # RGBA format
+        rgb = rgb_or_rgba[:3]
+        alpha = rgb_or_rgba[3]
+        has_alpha = True
+    else:  # RGB format
+        rgb = rgb_or_rgba
+        alpha = None
+        has_alpha = False
+
+    # Scale RGB values to 0-1 range if they're in 0-255 range
+    if any(val > 1 for val in rgb):
+        rgb = [val / 255 for val in rgb]
+
+    rgb_hsv = _colors.rgb_to_hsv(np.array(rgb))
+
+    gradient = []
+    for step in range(n):
+        color_hsv = [
+            rgb_hsv[0],
+            rgb_hsv[1],
+            rgb_hsv[2] * (1.0 - (step / n)),
+        ]
+        color_rgb = [int(v * 255) for v in _colors.hsv_to_rgb(color_hsv)]
+
+        if has_alpha:
+            gradient.append(rgb2rgba(color_rgb, alpha=alpha))
+        else:
+            gradient.append(color_rgb)
+
+    return gradient
+
+
+def gradiate_color_rgba(rgb_or_rgba, n=5):
+    return gradiate_color_rgb(rgb_or_rgba, n)
+
+
+# BGRA
+# ------------------------------
+def str2bgr(c):
+    return rgb2bgr(str2rgb(c))
+
+
+def str2bgra(c, alpha=1.0):
+    return rgba2bgra(str2rgba(c))
+
+
+def bgr2bgra(bgra, alpha=1.0, round=2):
+    return rgb2rgba(bgra, alpha=alpha, round=round)
+
+
+def bgra2bgr(bgra):
+    return rgba2rgb(bgra)
+
+
+def bgra2hex(bgra):
+    """Convert BGRA color format to hex format."""
+    rgba = bgra2rgba(bgra)
+    return rgba2hex(rgba)
+
+
+def cycle_color_bgr(i_color, colors=None):
+    rgb_color = str2rgb(cycle_color(i_color, colors=colors))
+    return rgb2bgr(rgb_color)
+
+
+def gradiate_color_bgr(bgr_or_bgra, n=5):
+    rgb_or_rgba = (
+        bgr2rgb(bgr_or_bgra) if len(bgr_or_bgra) == 3 else bgra2rgba(bgr_or_bgra)
+    )
+    rgb_gradient = gradiate_color_rgb(rgb_or_rgba, n)
+    return [
+        rgb2bgr(color) if len(color) == 3 else rgba2bgra(color)
+        for color in rgb_gradient
+    ]
+
+
+def gradiate_color_bgra(bgra, n=5):
+    return gradiate_color_bgr(bgra, n)
+
+
+# Common
+# ------------------------------
+def bgr2rgb(bgr):
+    """Convert BGR color format to RGB format."""
+    return [bgr[2], bgr[1], bgr[0]]
+
+
+def rgb2bgr(rgb):
+    """Convert RGB color format to BGR format."""
+    return [rgb[2], rgb[1], rgb[0]]
+
+
+def bgra2rgba(bgra):
+    """Convert BGRA color format to RGBA format."""
+    return [bgra[2], bgra[1], bgra[0], bgra[3]]
+
+
+def rgba2bgra(rgba):
+    """Convert RGBA color format to BGRA format."""
+    return [rgba[2], rgba[1], rgba[0], rgba[3]]
+
+
+def str2hex(c):
+    return PARAMS["HEX"][c]
+
+
+def update_alpha(rgba, alpha):
+    rgba_list = list(rgba)
+    rgba_list[-1] = alpha
+    return rgba_list
+
+
+def cycle_color(i_color, colors=None):
+    return cycle_color_rgb(i_color, colors=colors)
+
+
+# Deprecated
+# ------------------------------
+@deprecated("Use str2rgb instead")
+def to_rgb(c):
+    return str2rgb(c)
+
+
+@deprecated("use str2rgba instewad")
+def to_rgba(c, alpha=1.0):
+    return str2rgba(c, alpha=alpha)
+
+
+@deprecated("use str2hex instead")
+def to_hex(c):
+    return PARAMS["HEX"][c]
+
+
+@deprecated("use gradiate_color_rgb/rgba/bgr/bgra instead")
+def gradiate_color(rgb_or_rgba, n=5):
+    return gradiate_color_rgb(rgb_or_rgba, n)
+
+
+if __name__ == "__main__":
+    c = "blue"
+    print(to_rgb(c))
+    print(to_rgba(c))
+    print(to_hex(c))
+    print(cycle_color(1))
+
+# EOF