scitex 2.0.0__py2.py3-none-any.whl

scitex/plt/ax/_plot/_plot_heatmap.py

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-05-02 22:21:41 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex_repo/src/scitex/plt/ax/_plot/_plot_heatmap.py
+# ----------------------------------------
+import os
+
+__FILE__ = "./src/scitex/plt/ax/_plot/_plot_heatmap.py"
+__DIR__ = os.path.dirname(__FILE__)
+# ----------------------------------------
+
+import matplotlib
+import matplotlib.pyplot as plt
+import numpy as np
+
+
+def plot_heatmap(
+    ax,
+    data,
+    x_labels=None,
+    y_labels=None,
+    cmap="viridis",
+    cbar_label="ColorBar Label",
+    annot_format="{x:.1f}",
+    show_annot=True,
+    annot_color_lighter="black",
+    annot_color_darker="white",
+    **kwargs,
+):
+    """
+    Plot a heatmap on the given axes.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        The axes to plot on
+    data : array-like
+        The 2D data to display as heatmap
+    x_labels : list, optional
+        Labels for the x-axis
+    y_labels : list, optional
+        Labels for the y-axis
+    cmap : str or matplotlib colormap, optional
+        Colormap to use, default "viridis"
+    cbar_label : str, optional
+        Label for the colorbar, default "ColorBar Label"
+    show_annot : bool, optional
+        Whether to annotate the heatmap with values, default True
+    annot_format : str, optional
+        Format string for annotations, default "{x:.1f}"
+    annot_color_lighter : str, optional
+        Color for annotations on lighter background, default "black"
+    annot_color_darker : str, optional
+        Color for annotations on darker background, default "white"
+    **kwargs
+        Additional keyword arguments passed to matplotlib.axes.Axes.imshow()
+
+    Returns
+    -------
+    im : matplotlib.image.AxesImage
+        The image object created by imshow
+    cbar : matplotlib.colorbar.Colorbar
+        The colorbar object
+    """
+
+    im, cbar = _mpl_heatmap(
+        data,
+        x_labels,
+        y_labels,
+        ax=ax,
+        cmap=cmap,
+        cbarlabel=cbar_label,
+    )
+
+    if show_annot:
+        textcolors = _switch_annot_colors(cmap, annot_color_lighter, annot_color_darker)
+        texts = _mpl_annotate_heatmap(
+            im,
+            valfmt=annot_format,
+            textcolors=textcolors,
+        )
+
+    return ax, im, cbar
+
+
+def _switch_annot_colors(cmap, annot_color_lighter, annot_color_darker):
+    # Get colormap
+    cmap_obj = plt.cm.get_cmap(cmap)
+
+    # Sample the colormap at its extremes
+    dark_color = cmap_obj(0.1)  # Not using 0.0 to avoid edge effects
+    light_color = cmap_obj(0.9)  # Not using 1.0 to avoid edge effects
+
+    # Calculate perceived brightness
+    dark_brightness = (
+        0.2126 * dark_color[0] + 0.7152 * dark_color[1] + 0.0722 * dark_color[2]
+    )
+    light_brightness = (
+        0.2126 * light_color[0] + 0.7152 * light_color[1] + 0.0722 * light_color[2]
+    )
+
+    # Choose text colors based on background brightness
+    if dark_brightness < 0.5:
+        return (annot_color_lighter, annot_color_darker)
+    else:
+        return (annot_color_darker, annot_color_lighter)
+
+
+def _mpl_heatmap(
+    data, row_labels, col_labels, ax=None, cbar_kw=None, cbarlabel="", **kwargs
+):
+    """
+    A function to annotate a heatmap.
+
+    Parameters
+    ----------
+    im : matplotlib.image.AxesImage
+        The image to be annotated
+    data : array-like, optional
+        Data used to annotate. If None, the image's array is used
+    valfmt : str or matplotlib.ticker.Formatter, optional
+        Format of the annotations, default "{x:.2f}"
+    textcolors : tuple of str, optional
+        Colors for the annotations. The first is used for values below
+        threshold, the second for those above, default ("lightgray", "black")
+    threshold : float, optional
+        Value in normalized colormap space (0 to 1) above which the
+        second color is used. If None, 0.7*max(data) is used
+    **textkw
+        Additional keyword arguments passed to matplotlib.axes.Axes.text()
+
+    Returns
+    -------
+    texts : list of matplotlib.text.Text
+        The annotation text objects
+    """
+
+    if ax is None:
+        ax = plt.gca()
+
+    if cbar_kw is None:
+        cbar_kw = {}
+
+    # Plot the heatmap
+    im = ax.imshow(data, **kwargs)
+
+    # Create colorbar
+    cbar = ax.figure.colorbar(im, ax=ax, **cbar_kw)
+    cbar.ax.set_ylabel(cbarlabel, rotation=-90, va="bottom")
+
+    # Show all ticks and label them with the respective list entries.
+    ax.set_xticks(
+        range(data.shape[1]),
+        labels=col_labels,
+        # rotation=45,
+        # ha="right",
+        # rotation_mode="anchor",
+    )
+    ax.set_yticks(range(data.shape[0]), labels=row_labels)
+
+    # Let the horizontal axes labeling appear on top.
+    ax.tick_params(top=False, bottom=True, labeltop=False, labelbottom=True)
+
+    # Turn spines off
+    ax.spines[:].set_visible(False)
+
+    ax.set_xticks(np.arange(data.shape[1] + 1) - 0.5, minor=True)
+    ax.set_yticks(np.arange(data.shape[0] + 1) - 0.5, minor=True)
+    ax.tick_params(which="minor", bottom=False, left=False)
+
+    return im, cbar
+
+
+def _mpl_annotate_heatmap(
+    im,
+    data=None,
+    valfmt="{x:.2f}",
+    textcolors=("lightgray", "black"),
+    threshold=None,
+    **textkw,
+):
+    """
+    A function to annotate a heatmap.
+
+    Parameters
+    ----------
+    im : matplotlib.image.AxesImage
+        The image to be annotated
+    data : array-like, optional
+        Data used to annotate. If None, the image's array is used
+    valfmt : str or matplotlib.ticker.Formatter, optional
+        Format of the annotations, default "{x:.2f}"
+    textcolors : tuple of str, optional
+        Colors for the annotations. The first is used for values below
+        threshold, the second for those above, default ("lightgray", "black")
+    threshold : float, optional
+        Value in normalized colormap space (0 to 1) above which the
+        second color is used. If None, 0.7*max(data) is used
+    **textkw
+        Additional keyword arguments passed to matplotlib.axes.Axes.text()
+
+    Returns
+    -------
+    texts : list of matplotlib.text.Text
+        The annotation text objects
+    """
+
+    if not isinstance(data, (list, np.ndarray)):
+        data = im.get_array()
+
+    # Normalize the threshold to the images color range.
+    if threshold is not None:
+        threshold = im.norm(threshold)
+    else:
+        # Use 0.7 instead of 0.5 for better visibility with most colormaps
+        threshold = im.norm(data.max()) * 0.7
+
+    # Set default alignment to center, but allow it to be
+    # overwritten by textkw.
+    kw = dict(horizontalalignment="center", verticalalignment="center")
+    kw.update(textkw)
+
+    # Get the formatter in case a string is supplied
+    if isinstance(valfmt, str):
+        valfmt = matplotlib.ticker.StrMethodFormatter(valfmt)
+
+    # Loop over the data and create a `Text` for each "pixel".
+    # Change the text's color depending on the data.
+    texts = []
+    for ii in range(data.shape[0]):
+        for jj in range(data.shape[1]):
+            kw.update(color=textcolors[int(im.norm(data[ii, jj]) > threshold)])
+            text = im.axes.text(jj, ii, valfmt(data[ii, jj], None), **kw)
+            texts.append(text)
+
+    return texts
+
+
+if __name__ == "__main__":
+    import matplotlib
+    import matplotlib as mpl
+    import matplotlib.pyplot as plt
+    import numpy as np
+
+    data = np.random.rand(5, 10)
+    x_labels = [f"X{ii+1}" for ii in range(5)]
+    y_labels = [f"Y{ii+1}" for ii in range(10)]
+
+    fig, ax = plt.subplots()
+
+    im, cbar = plot_heatmap(
+        ax,
+        data,
+        x_labels=x_labels,
+        y_labels=y_labels,
+        show_annot=True,
+        annot_color_lighter="white",
+        annot_color_darker="black",
+        cmap="Blues",
+    )
+
+    fig.tight_layout()
+    plt.show()
+    # EOF
+
+# EOF

scitex/plt/ax/_plot/_plot_image.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-05-01 08:39:46 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex_repo/src/scitex/plt/ax/_plot/_plot_image2d.py
+# ----------------------------------------
+import os
+
+__FILE__ = "./src/scitex/plt/ax/_plot/_plot_image2d.py"
+__DIR__ = os.path.dirname(__FILE__)
+# ----------------------------------------
+
+import matplotlib
+from scitex.plt.utils import assert_valid_axis
+
+
+def plot_image(
+    ax,
+    arr_2d,
+    cbar=True,
+    cbar_label=None,
+    cbar_shrink=1.0,
+    cbar_fraction=0.046,
+    cbar_pad=0.04,
+    cmap="viridis",
+    aspect="auto",
+    vmin=None,
+    vmax=None,
+    **kwargs,
+):
+    """
+    Imshows an two-dimensional array with theese two conditions:
+    1) The first dimension represents the x dim, from left to right.
+    2) The second dimension represents the y dim, from bottom to top
+    
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes or scitex.plt._subplots._AxisWrapper.AxisWrapper
+        The axis to plot on
+    arr_2d : numpy.ndarray
+        The 2D array to display
+    cbar : bool, optional
+        Whether to show colorbar, by default True
+    cbar_label : str, optional
+        Label for the colorbar, by default None
+    cbar_shrink : float, optional
+        Shrink factor for the colorbar, by default 1.0
+    cbar_fraction : float, optional
+        Fraction of original axes to use for colorbar, by default 0.046
+    cbar_pad : float, optional
+        Padding between the image axes and colorbar axes, by default 0.04
+    cmap : str, optional
+        Colormap name, by default "viridis"
+    aspect : str, optional
+        Aspect ratio adjustment, by default "auto"
+    vmin : float, optional
+        Minimum data value for colormap scaling, by default None
+    vmax : float, optional
+        Maximum data value for colormap scaling, by default None
+    **kwargs
+        Additional keyword arguments passed to ax.imshow()
+        
+    Returns
+    -------
+    matplotlib.axes.Axes or scitex.plt._subplots._AxisWrapper.AxisWrapper
+        The axis with the image plotted
+    """
+    assert_valid_axis(ax, "First argument must be a matplotlib axis or scitex axis wrapper")
+    assert arr_2d.ndim == 2, "Input array must be 2-dimensional"
+
+    if kwargs.get("xyz"):
+        kwargs.pop("xyz")
+
+    # Transposes arr_2d for correct orientation
+    arr_2d = arr_2d.T
+
+    # Cals the original ax.imshow() method on the transposed array
+    im = ax.imshow(arr_2d, cmap=cmap, vmin=vmin, vmax=vmax, aspect=aspect, **kwargs)
+
+    # Color bar
+    if cbar:
+        fig = ax.get_figure()
+        _cbar = fig.colorbar(
+            im, ax=ax, shrink=cbar_shrink, fraction=cbar_fraction, pad=cbar_pad
+        )
+        if cbar_label:
+            _cbar.set_label(cbar_label)
+
+    # Invert y-axis to match typical image orientation
+    ax.invert_yaxis()
+
+    return ax
+
+
+# EOF

scitex/plt/ax/_plot/_plot_joyplot.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-05-02 09:03:23 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex_repo/src/scitex/plt/ax/_plot/_plot_joyplot.py
+# ----------------------------------------
+import os
+
+__FILE__ = "./src/scitex/plt/ax/_plot/_plot_joyplot.py"
+__DIR__ = os.path.dirname(__FILE__)
+# ----------------------------------------
+
+import warnings
+
+import joypy
+
+from .._style._set_xyt import set_xyt as scitex_plt_set_xyt
+
+
+def plot_joyplot(ax, data, orientation="vertical", **kwargs):
+    """
+    Create a joyplot (ridgeline plot) with proper orientation handling.
+    
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        The axes to plot on
+    data : pandas.DataFrame or array-like
+        The data to plot
+    orientation : str, default "vertical"
+        Plot orientation. Either "vertical" or "horizontal"
+    **kwargs
+        Additional keyword arguments passed to joypy.joyplot()
+    
+    Returns
+    -------
+    matplotlib.axes.Axes
+        The axes with the joyplot
+    
+    Raises
+    ------
+    ValueError
+        If orientation is not "vertical" or "horizontal"
+    """
+    if orientation not in ["vertical", "horizontal"]:
+        raise ValueError("orientation must be either 'vertical' or 'horizontal'")
+    
+    # Handle orientation by setting appropriate joypy parameters
+    if orientation == "horizontal":
+        # For horizontal orientation, we need to transpose the data display
+        # joypy doesn't have direct horizontal support, so we work with the result
+        kwargs.setdefault("kind", "kde")  # Ensure we're using KDE plots
+        
+    fig, axes = joypy.joyplot(
+        data=data,
+        **kwargs,
+    )
+
+    # Set appropriate labels based on orientation
+    if orientation == "vertical":
+        ax = scitex_plt_set_xyt(ax, None, "Density", "Joyplot")
+    elif orientation == "horizontal":
+        ax = scitex_plt_set_xyt(ax, "Density", None, "Joyplot")
+        # For horizontal plots, we might need additional transformations
+        # This is a limitation of joypy which primarily supports vertical plots
+
+    return ax
+
+
+# def plot_vertical_joyplot(ax, data, **kwargs):
+#     return _plot_joyplot(ax, data, "vertical", **kwargs)
+
+
+# def plot_horizontal_joyplot(ax, data, **kwargs):
+#     return _plot_joyplot(ax, data, "horizontal", **kwargs)
+
+# EOF

scitex/plt/ax/_plot/_plot_raster.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-05-01 15:23:01 (ywatanabe)"
+# File: /home/ywatanabe/proj/_scitex_repo/src/scitex/plt/ax/_plot/_plot_raster.py
+# ----------------------------------------
+import os
+
+__FILE__ = "./src/scitex/plt/ax/_plot/_plot_raster.py"
+__DIR__ = os.path.dirname(__FILE__)
+# ----------------------------------------
+
+import matplotlib
+from bisect import bisect_left
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+from ....plt.utils import assert_valid_axis
+
+
+def plot_raster(
+    ax,
+    event_times,
+    time=None,
+    labels=None,
+    colors=None,
+    orientation="horizontal",
+    y_offset=None,
+    lineoffsets=None,
+    apply_set_n_ticks=True,
+    n_xticks=4,
+    n_yticks=None,
+    **kwargs
+):
+    """
+    Create a raster plot using eventplot with custom labels and colors.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes or scitex.plt._subplots.AxisWrapper
+        The axes on which to draw the raster plot.
+    event_times : Array-like or list of lists
+        Time points of events by channels/trials
+    time : array-like, optional
+        The time indices for the events (default: np.linspace(0, max(event_times))).
+    labels : list, optional
+        Labels for each channel/trial.
+    colors : list, optional
+        Colors for each channel/trial.
+    orientation: str, optional
+        Orientation of raster plot (default: horizontal).
+    y_offset : float, optional
+        Vertical spacing between trials/channels.
+    lineoffsets : array-like, optional
+        Y-positions for each trial/channel (overrides automatic positioning).
+    apply_set_n_ticks : bool, optional
+        Whether to apply set_n_ticks for cleaner axis (default: True).
+    n_xticks : int, optional
+        Number of x-axis ticks (default: 4).
+    n_yticks : int or None, optional
+        Number of y-axis ticks (default: None, auto-determined).
+    **kwargs : dict
+        Additional keyword arguments for eventplot.
+
+    Returns
+    -------
+    ax : matplotlib.axes.Axes or scitex.plt._subplots.AxisWrapper
+        The axes with the raster plot.
+    df : pandas.DataFrame
+        DataFrame with time indices and channel events.
+    """
+    assert_valid_axis(ax, "First argument must be a matplotlib axis or scitex axis wrapper")
+
+    # Format event_times data
+    event_times_list = _ensure_list(event_times)
+
+    # Handle colors and labels
+    colors = _handle_colors(colors, event_times_list)
+    
+    # Handle lineoffsets for positioning between trials/channels
+    if lineoffsets is None:
+        if y_offset is None:
+            y_offset = 1.0  # Default spacing
+        lineoffsets = np.arange(len(event_times_list)) * y_offset
+    
+    # Ensure lineoffsets is iterable and matches event_times_list length
+    if np.isscalar(lineoffsets):
+        lineoffsets = [lineoffsets]
+    if len(lineoffsets) < len(event_times_list):
+        lineoffsets = list(lineoffsets) + list(range(len(lineoffsets), len(event_times_list)))
+
+    # Plotting as eventplot using event_times_list with proper positioning
+    for ii, (pos, color, offset) in enumerate(zip(event_times_list, colors, lineoffsets)):
+        label = _define_label(labels, ii)
+        ax.eventplot(pos, lineoffsets=offset, orientation=orientation, 
+                    colors=color, label=label, **kwargs)
+
+    # Apply set_n_ticks for cleaner axes if requested
+    if apply_set_n_ticks:
+        from scitex.plt.ax._style._set_n_ticks import set_n_ticks
+        
+        # For categorical y-axis (trials/channels), use appropriate tick count
+        if n_yticks is None:
+            n_yticks = min(len(event_times_list), 8)  # Max 8 ticks for readability
+        
+        # Only apply if we have reasonable numeric ranges
+        try:
+            x_range = ax.get_xlim()
+            y_range = ax.get_ylim()
+            
+            # Apply x-ticks if we have a reasonable numeric range
+            if x_range[1] - x_range[0] > 0:
+                set_n_ticks(ax, n_xticks=n_xticks, n_yticks=None)
+            
+            # Apply y-ticks only if we don't have categorical labels
+            if labels is None and y_range[1] - y_range[0] > 0:
+                set_n_ticks(ax, n_xticks=None, n_yticks=n_yticks)
+                
+        except Exception:
+            # Skip set_n_ticks if there are issues (e.g., categorical data)
+            pass
+
+    # Legend
+    if labels is not None:
+        ax.legend()
+
+    # Return event_times in a useful format
+    event_times_digital_df = _event_times_to_digital_df(event_times_list, time, lineoffsets)
+
+    return ax, event_times_digital_df
+
+
+def _ensure_list(event_times):
+    return [[pos] if isinstance(pos, (int, float)) else pos for pos in event_times]
+
+
+def _define_label(labels, ii):
+    if (labels is not None) and (ii < len(labels)):
+        return labels[ii]
+    else:
+        return None
+
+
+def _handle_colors(colors, event_times_list):
+    if colors is None:
+        colors = plt.rcParams["axes.prop_cycle"].by_key()["color"]
+    if len(colors) < len(event_times_list):
+        colors = colors * (len(event_times_list) // len(colors) + 1)
+    return colors
+
+
+def _event_times_to_digital_df(event_times_list, time, lineoffsets=None):
+    if time is None:
+        time = np.linspace(0, np.max([np.max(pos) for pos in event_times_list]), 1000)
+
+    digi = np.full((len(event_times_list), len(time)), np.nan, dtype=float)
+
+    for i_ch, posis_ch in enumerate(event_times_list):
+        for posi_ch in posis_ch:
+            i_insert = bisect_left(time, posi_ch)
+            if i_insert == len(time):
+                i_insert -= 1
+            # Use lineoffset position if available, otherwise use channel index
+            if lineoffsets is not None and i_ch < len(lineoffsets):
+                digi[i_ch, i_insert] = lineoffsets[i_ch]
+            else:
+                digi[i_ch, i_insert] = i_ch
+
+    return pd.DataFrame(digi.T, index=time)
+
+
+# EOF

scitex/plt/ax/_plot/_plot_rectangle.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-05-01 08:45:44 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex_repo/src/scitex/plt/ax/_plot/_plot_rectangle.py
+# ----------------------------------------
+import os
+
+__FILE__ = "./src/scitex/plt/ax/_plot/_plot_rectangle.py"
+__DIR__ = os.path.dirname(__FILE__)
+# ----------------------------------------
+
+from matplotlib.patches import Rectangle
+
+
+def plot_rectangle(ax, xx, yy, ww, hh, **kwargs):
+    """Add a rectangle patch to an axes.
+
+    Convenience function for adding rectangular patches to plots, useful for
+    highlighting regions, creating box annotations, or drawing geometric shapes.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        The axes to add the rectangle to.
+    xx : float
+        X-coordinate of the rectangle's bottom-left corner.
+    yy : float
+        Y-coordinate of the rectangle's bottom-left corner.
+    ww : float
+        Width of the rectangle.
+    hh : float
+        Height of the rectangle.
+    **kwargs : dict
+        Additional keyword arguments passed to matplotlib.patches.Rectangle.
+        Common options include:
+        - facecolor/fc : fill color
+        - edgecolor/ec : edge color
+        - linewidth/lw : edge line width
+        - alpha : transparency (0-1)
+        - linestyle/ls : edge line style
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+        The axes with the rectangle added.
+
+    Examples
+    --------
+    >>> fig, ax = plt.subplots()
+    >>> ax.plot([0, 10], [0, 10])
+    >>> # Highlight a region
+    >>> plot_rectangle(ax, 2, 3, 4, 3, facecolor='yellow', alpha=0.3)
+
+    >>> # Draw a box annotation
+    >>> plot_rectangle(ax, 5, 5, 2, 2, facecolor='none', edgecolor='red', linewidth=2)
+
+    >>> # Create a filled rectangle
+    >>> plot_rectangle(ax, 0, 0, 1, 1, facecolor='blue', edgecolor='black')
+
+    See Also
+    --------
+    matplotlib.patches.Rectangle : The underlying Rectangle class
+    matplotlib.axes.Axes.add_patch : Method used to add the patch
+    """
+    ax.add_patch(Rectangle((xx, yy), ww, hh, **kwargs))
+    return ax
+
+
+# EOF