scitex 2.3.0__py3-none-any.whl → 2.4.1__py3-none-any.whl

scitex/plt/ax/_plot/_plot_statistical_shaded_line.py

@@ -14,24 +14,50 @@ import numpy as np
 import pandas as pd
 from ....plt.utils import assert_valid_axis
 
-from ._plot_shaded_line import plot_shaded_line as scitex_plt_plot_shaded_line
+from ._stx_shaded_line import stx_shaded_line as scitex_plt_plot_shaded_line
 
 
-def plot_line(axis, data, xx=None, **kwargs):
+def _format_sample_size(values_2d):
+    """Format sample size string, showing range if variable due to NaN.
+
+    Parameters
+    ----------
+    values_2d : np.ndarray, shape (n_samples, n_points)
+        2D array where sample count may vary per column due to NaN.
+
+    Returns
+    -------
+    str
+        Formatted sample size string, e.g., "20" or "18-20".
+    """
+    if values_2d.ndim == 1:
+        return "1"
+
+    # Count non-NaN values per column (timepoint)
+    n_per_point = np.sum(~np.isnan(values_2d), axis=0)
+    n_min, n_max = int(n_per_point.min()), int(n_per_point.max())
+
+    if n_min == n_max:
+        return str(n_min)
+    else:
+        return f"{n_min}-{n_max}"
+
+
+def stx_line(axis, values_1d, xx=None, **kwargs):
     """
     Plot a simple line.
-    
+
     Parameters
     ----------
     axis : matplotlib.axes.Axes or scitex.plt._subplots.AxisWrapper
         The axis to plot on
-    data : array-like
-        Data to plot
-    xx : array-like, optional
-        X coordinates for the data. If None, will use np.arange(len(data))
+    values_1d : array-like, shape (n_points,)
+        1D array of y-values to plot
+    xx : array-like, shape (n_points,), optional
+        X coordinates for the data. If None, will use np.arange(len(values_1d))
     **kwargs
         Additional keyword arguments passed to axis.plot()
-        
+
     Returns
     -------
     axis : matplotlib.axes.Axes or scitex.plt._subplots.AxisWrapper
@@ -40,36 +66,38 @@ def plot_line(axis, data, xx=None, **kwargs):
         DataFrame with x and y values
     """
     assert_valid_axis(axis, "First argument must be a matplotlib axis or scitex axis wrapper")
-    data = np.asarray(data)
-    assert data.ndim <= 2, f"Data must be 1D or 2D, got {data.ndim}D"
+    values_1d = np.asarray(values_1d)
+    assert values_1d.ndim <= 2, f"Data must be 1D or 2D, got {values_1d.ndim}D"
     if xx is None:
-        xx = np.arange(len(data))
+        xx = np.arange(len(values_1d))
     else:
         xx = np.asarray(xx)
     assert len(xx) == len(
-        data
-    ), f"xx length ({len(xx)}) must match data length ({len(data)})"
-    axis.plot(xx, data, **kwargs)
-    return axis, pd.DataFrame({"x": xx, "y": data})
+        values_1d
+    ), f"xx length ({len(xx)}) must match values_1d length ({len(values_1d)})"
+
+    axis.plot(xx, values_1d, **kwargs)
+    return axis, pd.DataFrame({"x": xx, "y": values_1d})
 
 
-def plot_mean_std(axis, data, xx=None, sd=1, **kwargs):
+def stx_mean_std(axis, values_2d, xx=None, sd=1, **kwargs):
     """
     Plot mean line with standard deviation shading.
-    
+
     Parameters
     ----------
     axis : matplotlib.axes.Axes or scitex.plt._subplots.AxisWrapper
         The axis to plot on
-    data : array-like
-        Data to plot, can be 1D or 2D. If 2D, mean and std are calculated across the first dimension
-    xx : array-like, optional
-        X coordinates for the data. If None, will use np.arange(len(data))
+    values_2d : array-like, shape (n_samples, n_points) or (n_points,)
+        2D array where mean and std are calculated across axis=0 (samples).
+        Can also be 1D for a single line without shading.
+    xx : array-like, shape (n_points,), optional
+        X coordinates for the data. If None, will use np.arange(n_points)
     sd : float, optional
         Number of standard deviations for the shaded region. Default is 1
     **kwargs
-        Additional keyword arguments passed to plot_shaded_line()
-        
+        Additional keyword arguments passed to stx_shaded_line()
+
     Returns
     -------
     axis : matplotlib.axes.Axes or scitex.plt._subplots.AxisWrapper
@@ -78,51 +106,52 @@ def plot_mean_std(axis, data, xx=None, sd=1, **kwargs):
     assert_valid_axis(axis, "First argument must be a matplotlib axis or scitex axis wrapper")
     assert isinstance(sd, (int, float)), f"sd must be a number, got {type(sd)}"
     assert sd >= 0, f"sd must be non-negative, got {sd}"
-    data = np.asarray(data)
-    assert data.ndim <= 2, f"Data must be 1D or 2D, got {data.ndim}D"
+    values_2d = np.asarray(values_2d)
+    assert values_2d.ndim <= 2, f"Data must be 1D or 2D, got {values_2d.ndim}D"
     if xx is None:
-        xx = np.arange(data.shape[1] if data.ndim > 1 else len(data))
+        xx = np.arange(values_2d.shape[1] if values_2d.ndim > 1 else len(values_2d))
     else:
         xx = np.asarray(xx)
-    expected_len = data.shape[1] if data.ndim > 1 else len(data)
+    expected_len = values_2d.shape[1] if values_2d.ndim > 1 else len(values_2d)
     assert (
         len(xx) == expected_len
-    ), f"xx length ({len(xx)}) must match data length ({expected_len})"
+    ), f"xx length ({len(xx)}) must match values_2d length ({expected_len})"
 
-    if data.ndim == 1:
-        central = data
+    if values_2d.ndim == 1:
+        central = values_2d
         error = np.zeros_like(central)
     else:
-        central = np.nanmean(data, axis=0)
-        error = np.nanstd(data, axis=0) * sd
+        central = np.nanmean(values_2d, axis=0)
+        error = np.nanstd(values_2d, axis=0) * sd
 
     y_lower = central - error
     y_upper = central + error
-    n_samples = data.shape[0] if data.ndim > 1 else 1
 
     if "label" in kwargs and kwargs["label"]:
-        kwargs["label"] = f"{kwargs['label']} (n={n_samples})"
+        n_str = _format_sample_size(values_2d)
+        kwargs["label"] = f"{kwargs['label']} ($n$={n_str})"
 
     return scitex_plt_plot_shaded_line(axis, xx, y_lower, central, y_upper, **kwargs)
 
 
-def plot_mean_ci(axis, data, xx=None, perc=95, **kwargs):
+def stx_mean_ci(axis, values_2d, xx=None, perc=95, **kwargs):
     """
     Plot mean line with confidence interval shading.
-    
+
     Parameters
     ----------
     axis : matplotlib.axes.Axes or scitex.plt._subplots.AxisWrapper
         The axis to plot on
-    data : array-like
-        Data to plot, can be 1D or 2D. If 2D, mean and percentiles are calculated across the first dimension
-    xx : array-like, optional
-        X coordinates for the data. If None, will use np.arange(len(data))
+    values_2d : array-like, shape (n_samples, n_points) or (n_points,)
+        2D array where mean and percentiles are calculated across axis=0 (samples).
+        Can also be 1D for a single line without shading.
+    xx : array-like, shape (n_points,), optional
+        X coordinates for the data. If None, will use np.arange(n_points)
     perc : float, optional
         Confidence interval percentage (0-100). Default is 95
     **kwargs
-        Additional keyword arguments passed to plot_shaded_line()
-        
+        Additional keyword arguments passed to stx_shaded_line()
+
     Returns
     -------
     axis : matplotlib.axes.Axes or scitex.plt._subplots.AxisWrapper
@@ -133,87 +162,86 @@ def plot_mean_ci(axis, data, xx=None, perc=95, **kwargs):
         perc, (int, float)
     ), f"perc must be a number, got {type(perc)}"
     assert 0 <= perc <= 100, f"perc must be between 0 and 100, got {perc}"
-    data = np.asarray(data)
-    assert data.ndim <= 2, f"Data must be 1D or 2D, got {data.ndim}D"
+    values_2d = np.asarray(values_2d)
+    assert values_2d.ndim <= 2, f"Data must be 1D or 2D, got {values_2d.ndim}D"
 
     if xx is None:
-        xx = np.arange(data.shape[1] if data.ndim > 1 else len(data))
+        xx = np.arange(values_2d.shape[1] if values_2d.ndim > 1 else len(values_2d))
     else:
         xx = np.asarray(xx)
 
-    expected_len = data.shape[1] if data.ndim > 1 else len(data)
+    expected_len = values_2d.shape[1] if values_2d.ndim > 1 else len(values_2d)
     assert (
         len(xx) == expected_len
-    ), f"xx length ({len(xx)}) must match data length ({expected_len})"
+    ), f"xx length ({len(xx)}) must match values_2d length ({expected_len})"
 
-    if data.ndim == 1:
-        central = data
+    if values_2d.ndim == 1:
+        central = values_2d
         y_lower = central
         y_upper = central
     else:
-        central = np.nanmean(data, axis=0)
+        central = np.nanmean(values_2d, axis=0)
         # Calculate CI bounds
         alpha = 1 - perc / 100
         y_lower_perc = alpha / 2 * 100
         y_upper_perc = (1 - alpha / 2) * 100
-        y_lower = np.nanpercentile(data, y_lower_perc, axis=0)
-        y_upper = np.nanpercentile(data, y_upper_perc, axis=0)
-
-    n_samples = data.shape[0] if data.ndim > 1 else 1
+        y_lower = np.nanpercentile(values_2d, y_lower_perc, axis=0)
+        y_upper = np.nanpercentile(values_2d, y_upper_perc, axis=0)
 
     if "label" in kwargs and kwargs["label"]:
-        kwargs["label"] = f"{kwargs['label']} (n={n_samples}, CI={perc}%)"
+        n_str = _format_sample_size(values_2d)
+        kwargs["label"] = f"{kwargs['label']} ($n$={n_str}, CI={perc}%)"
 
     return scitex_plt_plot_shaded_line(axis, xx, y_lower, central, y_upper, **kwargs)
 
 
-def plot_median_iqr(axis, data, xx=None, **kwargs):
+def stx_median_iqr(axis, values_2d, xx=None, **kwargs):
     """
     Plot median line with interquartile range shading.
-    
+
     Parameters
     ----------
     axis : matplotlib.axes.Axes or scitex.plt._subplots.AxisWrapper
         The axis to plot on
-    data : array-like
-        Data to plot, can be 1D or 2D. If 2D, median and IQR are calculated across the first dimension
-    xx : array-like, optional
-        X coordinates for the data. If None, will use np.arange(len(data))
+    values_2d : array-like, shape (n_samples, n_points) or (n_points,)
+        2D array where median and IQR are calculated across axis=0 (samples).
+        Can also be 1D for a single line without shading.
+    xx : array-like, shape (n_points,), optional
+        X coordinates for the data. If None, will use np.arange(n_points)
     **kwargs
-        Additional keyword arguments passed to plot_shaded_line()
-        
+        Additional keyword arguments passed to stx_shaded_line()
+
     Returns
     -------
     axis : matplotlib.axes.Axes or scitex.plt._subplots.AxisWrapper
         The axis with the plot
     """
     assert_valid_axis(axis, "First argument must be a matplotlib axis or scitex axis wrapper")
-    data = np.asarray(data)
-    assert data.ndim <= 2, f"Data must be 1D or 2D, got {data.ndim}D"
+    values_2d = np.asarray(values_2d)
+    assert values_2d.ndim <= 2, f"Data must be 1D or 2D, got {values_2d.ndim}D"
 
     if xx is None:
-        xx = np.arange(data.shape[1] if data.ndim > 1 else len(data))
+        xx = np.arange(values_2d.shape[1] if values_2d.ndim > 1 else len(values_2d))
     else:
         xx = np.asarray(xx)
 
-    expected_len = data.shape[1] if data.ndim > 1 else len(data)
+    expected_len = values_2d.shape[1] if values_2d.ndim > 1 else len(values_2d)
     assert (
         len(xx) == expected_len
-    ), f"xx length ({len(xx)}) must match data length ({expected_len})"
+    ), f"xx length ({len(xx)}) must match values_2d length ({expected_len})"
 
-    if data.ndim == 1:
-        central = data
+    if values_2d.ndim == 1:
+        central = values_2d
         y_lower = central
         y_upper = central
     else:
-        central = np.nanmedian(data, axis=0)
-        y_lower = np.nanpercentile(data, 25, axis=0)
-        y_upper = np.nanpercentile(data, 75, axis=0)
-
-    n_samples = data.shape[0] if data.ndim > 1 else 1
+        central = np.nanmedian(values_2d, axis=0)
+        y_lower = np.nanpercentile(values_2d, 25, axis=0)
+        y_upper = np.nanpercentile(values_2d, 75, axis=0)
 
     if "label" in kwargs and kwargs["label"]:
-        kwargs["label"] = f"{kwargs['label']} (n={n_samples}, IQR)"
+        n_str = _format_sample_size(values_2d)
+        kwargs["label"] = f"{kwargs['label']} ($n$={n_str}, IQR)"
 
     return scitex_plt_plot_shaded_line(axis, xx, y_lower, central, y_upper, **kwargs)
 

scitex/plt/ax/_plot/{_plot_conf_mat.py → _stx_conf_mat.py}

@@ -22,9 +22,9 @@ from scitex.plt.utils import assert_valid_axis
 from .._style._extend import extend as scitex_plt_extend
 
 
-def plot_conf_mat(
+def stx_conf_mat(
     axis: plt.Axes,
-    data: Union[np.ndarray, pd.DataFrame],
+    conf_mat_2d: Union[np.ndarray, pd.DataFrame],
     x_labels: Optional[List[str]] = None,
     y_labels: Optional[List[str]] = None,
     title: str = "Confusion Matrix",
@@ -43,8 +43,8 @@ def plot_conf_mat(
     ----------
     axis : plt.Axes or scitex.plt._subplots._AxisWrapper.AxisWrapper
         Matplotlib axes or scitex axis wrapper to plot on
-    data : Union[np.ndarray, pd.DataFrame]
-        Confusion matrix data
+    conf_mat_2d : Union[np.ndarray, pd.DataFrame], shape (n_classes, n_classes)
+        2D confusion matrix data (true labels × predicted labels)
     x_labels : Optional[List[str]], optional
         Labels for predicted classes
     y_labels : Optional[List[str]], optional
@@ -75,7 +75,7 @@ def plot_conf_mat(
     -------
     >>> data = np.array([[10, 2, 0], [1, 15, 3], [0, 2, 20]])
     >>> fig, ax = plt.subplots()
-    >>> ax, bacc = plot_conf_mat(ax, data, x_labels=['A','B','C'],
+    >>> ax, bacc = stx_conf_mat(ax, data, x_labels=['A','B','C'],
     ...                     y_labels=['X','Y','Z'], calc_bacc=True)
     >>> print(f"Balanced Accuracy: {bacc:.3f}")
     Balanced Accuracy: 0.889
@@ -83,14 +83,14 @@ def plot_conf_mat(
 
     assert_valid_axis(axis, "First argument must be a matplotlib axis or scitex axis wrapper")
 
-    if not isinstance(data, pd.DataFrame):
-        data = pd.DataFrame(data)
+    if not isinstance(conf_mat_2d, pd.DataFrame):
+        conf_mat_2d = pd.DataFrame(conf_mat_2d)
 
-    bacc_val = calc_bacc_from_conf_mat(data.values)
+    bacc_val = calc_bacc_from_conf_mat(conf_mat_2d.values)
     title = f"{title} (bACC = {bacc_val:.3f})"
 
     res = sns.heatmap(
-        data,
+        conf_mat_2d,
         ax=axis,
         cmap=cmap,
         annot=True,
@@ -115,7 +115,7 @@ def plot_conf_mat(
         axis.set_yticklabels(y_labels)
 
     axis = scitex_plt_extend(axis, x_extend_ratio, y_extend_ratio)
-    if data.shape[0] == data.shape[1]:
+    if conf_mat_2d.shape[0] == conf_mat_2d.shape[1]:
         axis.set_box_aspect(1)
         axis.set_xticklabels(
             axis.get_xticklabels(),

scitex/plt/ax/_plot/_stx_ecdf.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-01 14:00:00 (ywatanabe)"
+# File: ./src/scitex/plt/ax/_plot/_plot_ecdf.py
+
+"""Empirical Cumulative Distribution Function (ECDF) plotting."""
+
+import warnings
+from typing import Any, Tuple, Union
+
+import numpy as np
+import pandas as pd
+from matplotlib.axes import Axes
+
+from scitex.pd._force_df import force_df as scitex_pd_force_df
+from ....plt.utils import assert_valid_axis, mm_to_pt
+
+
+# Default line width (0.2mm for publication)
+DEFAULT_LINE_WIDTH_MM = 0.2
+
+
+def stx_ecdf(
+    axis: Union[Axes, "AxisWrapper"],
+    values_1d: np.ndarray,
+    **kwargs: Any,
+) -> Tuple[Union[Axes, "AxisWrapper"], pd.DataFrame]:
+    """Plot Empirical Cumulative Distribution Function (ECDF).
+
+    The ECDF shows the proportion of data points less than or equal to each
+    value, representing the empirical estimate of the cumulative distribution
+    function.
+
+    Parameters
+    ----------
+    axis : matplotlib.axes.Axes or AxisWrapper
+        Matplotlib axis or scitex axis wrapper to plot on.
+    values_1d : array-like, shape (n_samples,)
+        1D array of values to compute and plot ECDF for. NaN values are automatically ignored.
+    **kwargs : dict
+        Additional arguments passed to plot function.
+
+    Returns
+    -------
+    axis : matplotlib.axes.Axes or AxisWrapper
+        The axes with the ECDF plot.
+    df : pd.DataFrame
+        DataFrame containing ECDF data with columns:
+        - x: sorted data values
+        - y: cumulative percentages (0-100)
+        - n: total number of data points
+        - x_step, y_step: step plot coordinates
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> import scitex as stx
+    >>> data = np.random.randn(100)
+    >>> fig, ax = stx.plt.subplots()
+    >>> ax, df = stx.plt.ax.stx_ecdf(ax, data)
+    """
+    assert_valid_axis(axis, "First argument must be a matplotlib axis or scitex axis wrapper")
+
+    # Flatten and remove NaN values
+    values_1d = np.hstack(values_1d)
+
+    # Warnings
+    if np.isnan(values_1d).any():
+        warnings.warn("NaN value are ignored for ECDF plot.")
+    values_1d = values_1d[~np.isnan(values_1d)]
+    nn = len(values_1d)
+
+    # Sort the data and compute the ECDF values
+    data_sorted = np.sort(values_1d)
+    ecdf_perc = 100 * np.arange(1, len(data_sorted) + 1) / len(data_sorted)
+
+    # Create the pseudo x-axis for step plotting
+    x_step = np.repeat(data_sorted, 2)[1:]
+    y_step = np.repeat(ecdf_perc, 2)[:-1]
+
+    # Apply default linewidth if not specified
+    if 'linewidth' not in kwargs and 'lw' not in kwargs:
+        kwargs['linewidth'] = mm_to_pt(DEFAULT_LINE_WIDTH_MM)
+
+    # Add sample size to label if provided
+    if "label" in kwargs and kwargs["label"]:
+        kwargs["label"] = f"{kwargs['label']} ($n$={nn})"
+
+    # Plot the ECDF using steps (no markers - clean line only)
+    axis.plot(x_step, y_step, drawstyle="steps-post", **kwargs)
+
+    # Set ylim (xlim is auto-scaled based on data)
+    axis.set_ylim(0, 100)
+
+    # Create a DataFrame to hold the ECDF data
+    df = scitex_pd_force_df(
+        {
+            "x": data_sorted,
+            "y": ecdf_perc,
+            "n": nn,
+            "x_step": x_step,
+            "y_step": y_step,
+        }
+    )
+
+    return axis, df
+
+
+# EOF

scitex/plt/ax/_plot/{_plot_fillv.py → _stx_fillv.py}

@@ -14,7 +14,7 @@ import numpy as np
 from ....plt.utils import assert_valid_axis
 
 
-def plot_fillv(axes, starts, ends, color="red", alpha=0.2):
+def stx_fillv(axes, starts_1d, ends_1d, color="red", alpha=0.2):
     """
     Fill between specified start and end intervals on an axis or array of axes.
 
@@ -22,10 +22,10 @@ def plot_fillv(axes, starts, ends, color="red", alpha=0.2):
     ----------
     axes : matplotlib.axes.Axes or scitex.plt._subplots.AxisWrapper or numpy.ndarray of axes
         The axis object(s) to fill intervals on.
-    starts : array-like
-        Array-like of start positions.
-    ends : array-like
-        Array-like of end positions.
+    starts_1d : array-like, shape (n_regions,)
+        1D array of start x-positions for vertical fill regions.
+    ends_1d : array-like, shape (n_regions,)
+        1D array of end x-positions for vertical fill regions.
     color : str, optional
         The color to use for the filled regions. Default is "red".
     alpha : float, optional
@@ -43,8 +43,8 @@ def plot_fillv(axes, starts, ends, color="red", alpha=0.2):
 
     for ax in axes:
         assert_valid_axis(ax, "First argument must be a matplotlib axis or scitex axis wrapper")
-        for start, end in zip(starts, ends):
-            ax.axvspan(start, end, color=color, alpha=alpha)
+        for start, end in zip(starts_1d, ends_1d):
+            ax.axvspan(start, end, facecolor=color, edgecolor='none', alpha=alpha)
 
     if not is_axes:
         return axes[0]