bsplot 0.0.2__py3-none-any.whl

bsplot/style.py

@@ -0,0 +1,791 @@
+import os
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.ticker import FormatStrFormatter, FuncFormatter
+from bsplot import panels
+import bsplot  # Import your package to access its path
+from .colors import make_cycler_from_cmap
+
+
+def use(style="bss"):
+    """Apply one or more bsplot style modules.
+
+    Styles can be composed by separating modules with ``-``.
+    Modules are layered left-to-right, so later modules override earlier ones.
+
+    Examples
+    --------
+    >>> bsplot.style.use("black")               # single base style
+    >>> bsplot.style.use("black-transparent")    # base + module
+    >>> bsplot.style.use("tvbo-transparent")     # works with any base
+    """
+    styles_dir = os.path.join(os.path.dirname(bsplot.__file__), "styles")
+
+    def _style_path(name):
+        p = os.path.join(styles_dir, f"{name}.mplstyle")
+        if not os.path.exists(p):
+            available = sorted(
+                f.removesuffix(".mplstyle")
+                for f in os.listdir(styles_dir)
+                if f.endswith(".mplstyle")
+            )
+            raise ValueError(
+                f"Style module '{name}' not found. "
+                f"Available modules: {available}"
+            )
+        return p
+
+    # Split on "-" to get composable modules: "black-transparent" -> ["black", "transparent"]
+    modules = style.split("-")
+    paths = [_style_path(m) for m in modules]
+    plt.style.use(paths)
+
+    # Turn off legacy layout flags that can conflict
+    plt.rcParams["figure.constrained_layout.use"] = False
+    plt.rcParams["figure.autolayout"] = False
+
+    if modules[0] == "black":
+        plt.rcParams["axes.prop_cycle"]._left[0] = {"color": "white"}
+
+
+def format(obj, **kwargs):
+    """Intelligently format matplotlib objects based on their type.
+
+    This is a convenience function that dispatches to the appropriate formatter:
+    - Figure -> format_fig()
+    - Axes with label '<colorbar>' -> format_colorbar()
+    - Axes -> format_ax()
+    - list/tuple of objects -> applies format() to each
+
+    Parameters
+    ----------
+    obj : Figure, Axes, or list/tuple of these
+        The matplotlib object(s) to format.
+    **kwargs
+        Additional arguments passed to the appropriate formatting function.
+        Common kwargs:
+        - tick_decimals: int | None | "smart" for axes tick formatting
+        - colorbar_decimals: int | None for colorbar tick formatting
+        - add_panel_numbers: "auto" | True | False (for figures only)
+        - n_ticks: int, number of ticks per axis
+        - shift_left_spine, shift_bottom_spine: float, spine offsets
+
+    Returns
+    -------
+    obj
+        The formatted object (for chaining).
+
+    Examples
+    --------
+    >>> fig, ax = plt.subplots()
+    >>> ax.plot([1, 2, 3])
+    >>> style.format(fig)  # Formats entire figure
+
+    >>> style.format(ax, n_ticks=5)  # Format single axes
+
+    >>> style.format([ax1, ax2], tick_decimals=2)  # Format multiple axes
+    """
+    import matplotlib.figure
+    import matplotlib.axes
+
+    # Handle lists/tuples of objects
+    if isinstance(obj, (list, tuple)):
+        for item in obj:
+            format(item, **kwargs)
+        return obj
+
+    # Handle Figure
+    if isinstance(obj, matplotlib.figure.Figure):
+        format_fig(obj, **kwargs)
+        return obj
+
+    # Handle Axes
+    if isinstance(obj, matplotlib.axes.Axes):
+        # Check if it's a colorbar
+        if obj.get_label() == "<colorbar>":
+            # Extract colorbar-specific kwargs
+            colorbar_kwargs = {}
+            if "colorbar_decimals" in kwargs:
+                colorbar_kwargs["colorbar_decimals"] = kwargs["colorbar_decimals"]
+            format_colorbar(obj, **colorbar_kwargs)
+        else:
+            # Filter out figure-only kwargs
+            ax_kwargs = {k: v for k, v in kwargs.items()
+                        if k not in ("add_panel_numbers", "colorbar_decimals")}
+            format_ax(obj, **ax_kwargs)
+        return obj
+
+    # If we get here, we don't know how to handle this type
+    raise TypeError(
+        f"Cannot format object of type {type(obj).__name__}. "
+        f"Expected Figure, Axes, or list/tuple of these."
+    )
+
+
+def format_fig(
+    fig, colorbar_decimals=None, tick_decimals=None, add_panel_numbers="auto", **kwargs
+):
+    """Format all axes in a figure.
+
+    Parameters (forwarded):
+    - tick_decimals: int | None | "smart" -> number of decimals for normal axes ticks.
+        If None or "smart", uses automatic detection based on data range.
+    - colorbar_decimals: int | None -> number of decimals for colorbar ticks.
+        If None, uses automatic detection based on data range.
+    - other kwargs are passed to format_ax/format_colorbar as appropriate
+    """
+    i = 1
+    for ax in fig.axes:
+        # Skip polar (and other non-rectilinear) axes – they lack standard spines
+        if ax.name != "rectilinear" and ax.axes.get_label() != "<colorbar>":
+            continue
+        if ax.axes.get_label() == "<colorbar>":
+            format_colorbar(ax, colorbar_decimals=colorbar_decimals)
+        else:
+            if "shift_left_spine" not in kwargs:
+                kwargs["shift_left_spine"] = -0.02
+            if "shift_bottom_spine" not in kwargs:
+                kwargs["shift_bottom_spine"] = -0.02
+            format_ax(
+                ax,
+                tick_decimals=tick_decimals,
+                **kwargs,
+            )
+            if add_panel_numbers != False and add_panel_numbers == "auto":
+                panels.add_panel_number(
+                    ax, ax.get_label(), x_shift=kwargs["shift_left_spine"], y_shift=0.02
+                )
+
+            elif add_panel_numbers == True:
+                panels.add_panel_number(
+                    ax, i, x_shift=kwargs["shift_left_spine"], y_shift=0.02
+                )
+            i += 1
+
+
+def format_all(**kwargs):
+    """Format every open matplotlib figure.
+
+    Convenience wrapper that calls :func:`format_fig` on each figure
+    returned by ``plt.get_fignums()``.
+
+    Parameters
+    ----------
+    **kwargs
+        Forwarded to :func:`format_fig` (e.g. ``tick_decimals``,
+        ``add_panel_numbers``, ``colorbar_decimals``).
+    """
+    for num in plt.get_fignums():
+        format_fig(plt.figure(num), **kwargs)
+
+
+def _has_string_ticklabels(ax, axis="x"):
+    """
+    Check if an axis has custom string-based (non-numeric) tick labels.
+    
+    Returns True if any tick label is a non-numeric string that cannot be
+    converted to a float. This is used to preserve user-set categorical labels
+    like '$Dice_L$', 'Category A', etc.
+    """
+    try:
+        if axis == "x":
+            labels = [t.get_text() for t in ax.get_xticklabels()]
+        else:
+            labels = [t.get_text() for t in ax.get_yticklabels()]
+
+        # Filter out empty labels (matplotlib default)
+        labels = [l for l in labels if l.strip()]
+
+        if not labels:
+            return False
+
+        # Check if any label is non-numeric
+        for label in labels:
+            # Strip common LaTeX wrappers for numeric check
+            # Also replace Unicode minus (U+2212) with ASCII hyphen
+            clean = label.replace('$', '').replace(',', '').replace('\u2212', '-').strip()
+            try:
+                float(clean)
+            except ValueError:
+                # Found a non-numeric label
+                return True
+        return False
+    except Exception:
+        return False
+
+
+def _nice_round(x, step, direction="down"):
+    """Round *x* to the nearest multiple of *step*.
+
+    ``"down"`` rounds toward −∞, ``"up"`` toward +∞.
+    """
+    if step == 0:
+        return x
+    if direction == "down":
+        return np.floor(x / step) * step
+    else:
+        return np.ceil(x / step) * step
+
+
+def _auto_round_step(span):
+    """Derive a small rounding granularity from *span*.
+
+    Returns a value from {1, 2, 5} × 10^n that is roughly 1/20th of
+    the span, keeping padding minimal.  Examples:
+
+    * span ≈ 250  → 10   (so 125 → 130)
+    * span ≈ 1.4  → 0.05
+    * span ≈ 30   → 1
+    """
+    if span <= 0:
+        return 1.0
+    target = span / 20.0
+    mag = 10 ** np.floor(np.log10(target))
+    residual = target / mag
+    if residual <= 1.5:
+        return mag
+    elif residual <= 3.5:
+        return 2.0 * mag
+    elif residual <= 7.5:
+        return 5.0 * mag
+    else:
+        return 10.0 * mag
+
+
+def format_ax(
+    ax,
+    x_datatype="continuous",
+    n_ticks=4,
+    box_aspect=None,
+    shift_left_spine=-0.02,
+    shift_bottom_spine=-0.02,
+    ylim=None,
+    xlim=None,
+    tick_decimals=None,
+    y_datatype=None,
+    datatype=None,
+    x_tick_decimals=None,
+    y_tick_decimals=None,
+    n_x_ticks=None,
+    n_y_ticks=None,
+    scientific=False,
+    round_step=None,
+):
+    """
+    Format matplotlib Axes:
+    - shifts spines
+    - enforces aspect ratio
+    - continuous: evenly spaced numeric ticks with optional rounding
+    - discrete: integer ticks (first, last, and evenly spaced in between)
+
+    Parameters:
+    - x_datatype: "continuous" | "discrete"
+    - y_datatype: "continuous" | "discrete" | None (defaults to x_datatype)
+    - datatype: "continuous" | "discrete" | None (if set, applies to both axes)
+    - n_ticks: maximum number of ticks per axis (endpoints included when possible)
+    - tick_decimals: int | "smart" | None -> default formatting for continuous ticks
+    - x_tick_decimals: int | "smart" | None -> override for x (falls back to tick_decimals)
+    - y_tick_decimals: int | "smart" | None -> override for y (falls back to tick_decimals)
+    - n_x_ticks: int | None -> override tick count for x-axis (falls back to n_ticks)
+    - n_y_ticks: int | None -> override tick count for y-axis (falls back to n_ticks)
+    - scientific: bool -> if True and smart formatting is selected, allow scientific
+      notation with a single axis-wide exponent; if False, never use scientific mode.
+    - round_step: float | None -> rounding granularity for the axis endpoints.
+      E.g. round_step=10 rounds -67 → -70, 87 → 90.
+      If None (default), the step is automatically derived from the data range.
+    
+    Note:
+    - Tick formatting is skipped for axes with string-based (categorical) tick labels.
+      This preserves custom labels like LaTeX strings or category names.
+    """
+    # If a single datatype is provided, apply to both axes (unless y_datatype explicitly set)
+    if datatype is not None:
+        x_datatype = datatype
+        if y_datatype is None:
+            y_datatype = datatype
+
+    if y_datatype is None:
+        y_datatype = x_datatype
+
+    # Polar / non-rectilinear axes lack standard spines; bail out early.
+    if ax.name != "rectilinear":
+        return
+
+    if ylim is not None:
+        ax.set_ylim(ylim)
+    if xlim is not None:
+        ax.set_xlim(xlim)
+
+    ax.spines["left"].set_position(("axes", shift_left_spine))
+    ax.spines["bottom"].set_position(("axes", shift_bottom_spine))
+
+    if box_aspect:
+        ax.set_box_aspect(box_aspect)
+
+    # Resolve per-axis decimals for continuous axes
+    _x_dec = x_tick_decimals if x_tick_decimals is not None else tick_decimals
+    _y_dec = y_tick_decimals if y_tick_decimals is not None else tick_decimals
+
+    # Resolve per-axis tick counts
+    _nx = n_x_ticks if n_x_ticks is not None else n_ticks
+    _ny = n_y_ticks if n_y_ticks is not None else n_ticks
+
+    # Helper to trim spines to tick range
+    def _update_spine_bounds(axis: str, ticks):
+        if ticks is None or len(ticks) < 2:
+            return
+        lo, hi = float(np.min(ticks)), float(np.max(ticks))
+        try:
+            if axis == "x":
+                ax.spines["bottom"].set_bounds(lo, hi)
+            else:
+                ax.spines["left"].set_bounds(lo, hi)
+        except Exception:
+            # set_bounds not available for some artists; ignore
+            pass
+
+    # Helpers
+    def _set_continuous(axis: str):
+        k = _nx if axis == "x" else _ny
+        k = max(2, int(k))  # ensure at least 2 ticks
+        if k == 0:
+            (ax.set_xticks([]) if axis == "x" else ax.set_yticks([]))
+            return
+        lo, hi = ax.get_xlim() if axis == "x" else ax.get_ylim()
+        a, b = min(lo, hi), max(lo, hi)
+        # Guard against degenerate or non-finite limits
+        if not np.isfinite(a) or not np.isfinite(b) or a == b:
+            center = a if np.isfinite(a) else (b if np.isfinite(b) else 0.0)
+            span = (
+                1.0 if not np.isfinite(a) or not np.isfinite(b) or a == b else (b - a)
+            )
+            a, b = center - span / 2.0, center + span / 2.0
+
+        # Round endpoints outward by a small amount so the axis starts
+        # and ends at a round number.  The rounding step is ~1/10th of
+        # the span by default (e.g. 125 → 130 for a 250-wide range).
+        step = round_step if round_step is not None else _auto_round_step(b - a)
+        a_nice = _nice_round(a, step, "down")
+        b_nice = _nice_round(b, step, "up")
+
+        ticks = np.linspace(a_nice, b_nice, k)
+        ticks[0], ticks[-1] = a_nice, b_nice  # keep endpoints exact
+        # Round intermediate ticks to the same step for clean labels
+        for i in range(1, len(ticks) - 1):
+            ticks[i] = np.round(ticks[i] / step) * step
+
+        dec = _x_dec if axis == "x" else _y_dec
+        if isinstance(dec, int):
+            rounded = np.round(ticks, dec)
+            if np.unique(rounded).size == rounded.size:
+                ticks = rounded
+
+        t_lo, t_hi = float(ticks[0]), float(ticks[-1])
+
+        if axis == "x":
+            ax.set_xlim(t_lo, t_hi)
+            ax.set_xticks(ticks.tolist())
+            if isinstance(dec, int):
+                if np.unique(np.round(ticks, dec)).size < 2:
+                    fmt, offset = make_smart_formatter(t_lo, t_hi, k, allow_sci=scientific)
+                    ax.xaxis.set_major_formatter(FuncFormatter(fmt))
+                    _apply_axis_offset(ax, "x", offset, pos="top")
+                else:
+                    ax.xaxis.set_major_formatter(FormatStrFormatter(f"%.{dec}f"))
+            else:
+                fmt, offset = make_smart_formatter(t_lo, t_hi, k, allow_sci=scientific)
+                ax.xaxis.set_major_formatter(FuncFormatter(fmt))
+                _apply_axis_offset(ax, "x", offset, pos="top")
+            _update_spine_bounds("x", ticks)
+        else:
+            ax.set_ylim(t_lo, t_hi)
+            ax.set_yticks(ticks.tolist())
+            if isinstance(dec, int):
+                if np.unique(np.round(ticks, dec)).size < 2:
+                    fmt, offset = make_smart_formatter(t_lo, t_hi, k, allow_sci=scientific)
+                    ax.yaxis.set_major_formatter(FuncFormatter(fmt))
+                    _apply_axis_offset(ax, "y", offset, pos="right")
+                else:
+                    ax.yaxis.set_major_formatter(FormatStrFormatter(f"%.{dec}f"))
+            else:
+                fmt, offset = make_smart_formatter(t_lo, t_hi, k, allow_sci=scientific)
+                ax.yaxis.set_major_formatter(FuncFormatter(fmt))
+                _apply_axis_offset(ax, "y", offset, pos="right")
+            _update_spine_bounds("y", ticks)
+
+    def _set_discrete(axis: str):
+        k_in = _nx if axis == "x" else _ny
+        if k_in == 0:
+            (ax.set_xticks([]) if axis == "x" else ax.set_yticks([]))
+            return
+        lo, hi = ax.get_xlim() if axis == "x" else ax.get_ylim()
+        a, b = min(lo, hi), max(lo, hi)
+        # For imshow-like limits [-0.5, N-0.5], integer indices are [0, N-1]
+        ia = int(np.round(a + 0.5))
+        ib = int(np.round(b - 0.5))
+        if ib < ia:
+            ib = ia
+        count = ib - ia + 1
+        k = max(2, min(int(k_in), count))
+        ticks = np.round(np.linspace(ia, ib, k)).astype(int)
+        ticks = np.unique(ticks)
+        if ticks.size < 2:
+            ticks = np.array([ia, ib], dtype=int)
+        else:
+            ticks[0] = ia
+            ticks[-1] = ib
+        if axis == "x":
+            ax.set_xticks(ticks.tolist())
+            ax.xaxis.set_major_formatter(FormatStrFormatter("%d"))
+            # Trim bottom spine to tick range
+            _update_spine_bounds("x", ticks)
+        else:
+            ax.set_yticks(ticks.tolist())
+            ax.yaxis.set_major_formatter(FormatStrFormatter("%d"))
+            # Trim left spine to tick range
+            _update_spine_bounds("y", ticks)
+
+    # Check for string-based tick labels before modifying ticks
+    x_has_string_labels = _has_string_ticklabels(ax, "x")
+    y_has_string_labels = _has_string_ticklabels(ax, "y")
+
+    # Apply per-axis (skip if string labels are present)
+    if not x_has_string_labels:
+        if x_datatype == "continuous":
+            _set_continuous("x")
+        elif x_datatype == "discrete":
+            _set_discrete("x")
+
+    if not y_has_string_labels:
+        if y_datatype == "continuous":
+            _set_continuous("y")
+        elif y_datatype == "discrete":
+            _set_discrete("y")
+
+
+def smart_format(x):
+    """Adaptive tick formatter:
+    - Uses scientific notation for very small/large values.
+    - Otherwise formats with up to 4 decimals and strips trailing zeros.
+    - Avoids negative zero.
+    """
+    # Normalize near-zero to 0
+    if abs(x) < 1e-12:
+        return "0"
+
+    m = abs(x)
+    # Extreme magnitudes -> scientific with 3 significant digits
+    if m >= 1e4 or m < 1e-3:
+        s = f"{x:.3g}"
+    else:
+        # Adaptive fixed-point decimals by magnitude
+        if m >= 100:
+            dec = 0
+        elif m >= 10:
+            dec = 1
+        elif m >= 1:
+            dec = 2
+        elif m >= 0.1:
+            dec = 3
+        else:
+            dec = 4
+        s = f"{x:.{dec}f}"
+        if "." in s:
+            s = s.rstrip("0").rstrip(".")
+    if s == "-0":
+        s = "0"
+    return s
+
+
+def make_smart_formatter(lo, hi, k=5, allow_sci=True):
+    """
+    Axis-consistent smart formatter:
+    - If scientific is chosen (and allowed), show mantissas as tick labels and a single 'e±NN'
+      as axis offset text (no mixed styles on the same axis).
+    - Else, fixed-point with decimals derived from tick step.
+    Returns (formatter_func, offset_text or None).
+    """
+    a, b = (min(lo, hi), max(lo, hi))
+    magnitude = max(abs(a), abs(b))
+    step = (b - a) / max(k - 1, 1) if k and k > 1 else (b - a)
+
+    use_sci = allow_sci and (
+        (magnitude >= 1e4)
+        or (0 < magnitude < 1e-3)
+        or (abs(step) >= 1e4)
+        or (0 < abs(step) < 1e-3)
+    )
+
+    if use_sci:
+        if magnitude == 0:
+            E = 0
+        else:
+            E = int(np.floor(np.log10(magnitude)))
+        scale = 10.0**E
+        step_scaled = abs(step) / scale if step != 0 else 0
+        # Build tick mantissas for uniqueness test
+        ticks = np.linspace(a, b, max(2, int(k))) if k and k > 1 else np.array([a, b])
+        mant_ticks = ticks / scale if scale != 0 else ticks
+
+        # Choose the minimal decimals (<=6) that yield unique rounded mantissas
+        dec = 6
+        for d in range(0, 7):
+            S = 10**d
+            ints = np.round(mant_ticks * S).astype(np.int64)
+            if np.unique(ints).size == ints.size:
+                dec = d
+                break
+
+        def fmt(v, _pos=None):
+            mant = v / scale
+            val = np.round(mant, dec)
+            s = f"{val:.{dec}f}"
+            if "." in s:
+                s = s.rstrip("0").rstrip(".")
+            return "0" if s == "-0" else s
+
+        sign = "-" if E < 0 else "+"
+        offset = f"e{sign}{abs(E):02d}"
+        return fmt, offset
+
+    # Fixed-point mode
+    # Fixed-point mode: choose minimal decimals so that all tick labels are unique
+    ticks = np.linspace(a, b, max(2, int(k))) if k and k > 1 else np.array([a, b])
+    dec = 6
+    for d in range(0, 7):
+        S = 10**d
+        ints = np.round(ticks * S).astype(np.int64)
+        if np.unique(ints).size == ints.size:
+            dec = d
+            break
+
+    def fmt(v, _pos=None):
+        val = np.round(v, dec)
+        s = f"{val:.{dec}f}"
+        if "." in s:
+            s = s.rstrip("0").rstrip(".")
+        return "0" if s == "-0" else s
+
+    return fmt, None
+
+
+def _apply_axis_offset(ax, axis, offset, pos="top"):
+    """
+    Apply an offset string to an axis in a version-safe way.
+    axis: "x" | "y"
+    pos: for x -> "top"/"bottom"; for y -> "left"/"right"
+    """
+    # Remove any previous manual label if no offset requested
+    if not offset:
+        tag = "_bss_offset_text_x" if axis == "x" else "_bss_offset_text_y"
+        prev = getattr(ax, tag, None)
+        if prev is not None:
+            try:
+                prev.remove()
+            except Exception:
+                pass
+            setattr(ax, tag, None)
+        return
+
+    axis_obj = ax.xaxis if axis == "x" else ax.yaxis
+    # Try native API if available
+    if hasattr(axis_obj, "set_offset_position"):
+        try:
+            axis_obj.set_offset_position(pos)
+            axis_obj.offsetText.set_visible(True)
+            axis_obj.offsetText.set_text(offset)
+            return
+        except Exception:
+            pass
+
+    # Fallback: draw our own text
+    tag = "_bss_offset_text_x" if axis == "x" else "_bss_offset_text_y"
+    prev = getattr(ax, tag, None)
+    if prev is not None:
+        try:
+            prev.remove()
+        except Exception:
+            pass
+
+    if axis == "x":
+        # top or bottom placement in axes coords
+        y = 1.02 if pos == "top" else -0.08
+        txt = ax.text(1.0, y, offset, transform=ax.transAxes, ha="right", va="bottom")
+    else:
+        # y-axis: place at top tick, on the requested side of the axis
+        if pos == "right":
+            # slightly inside the axes so it's to the right of the y-axis line/ticks
+            txt = ax.text(
+                0.01, 1.0, offset, transform=ax.transAxes, ha="left", va="top"
+            )
+        else:
+            txt = ax.text(
+                -0.02, 1.0, offset, transform=ax.transAxes, ha="right", va="top"
+            )
+    setattr(ax, tag, txt)
+
+
+def format_colorbar(ax, colorbar_decimals=None):
+    for spine in ax.spines.values():
+        spine.set_visible(False)
+    orientation = (
+        "vertical"
+        if ax.get_position().width < ax.get_position().height
+        else "horizontal"
+    )
+
+    # Try to get the actual data range from the colorbar's mappable
+    # This is more reliable than axis limits which may not be set yet
+    mappable = getattr(ax, 'mappable', None) if hasattr(ax, 'mappable') else None
+    if mappable is None:
+        # Try to find mappable from images or collections
+        for child in ax.get_children():
+            if hasattr(child, 'get_clim'):
+                mappable = child
+                break
+
+    def _safe_limits(val_tuple, fallback_tuple):
+        """Safely convert limits to floats, with fallback."""
+        try:
+            vmin, vmax = val_tuple
+            vmin, vmax = float(vmin), float(vmax)
+            if np.isfinite(vmin) and np.isfinite(vmax) and vmin != vmax:
+                return vmin, vmax
+        except (TypeError, ValueError):
+            pass
+        try:
+            vmin, vmax = fallback_tuple
+            vmin, vmax = float(vmin), float(vmax)
+            if np.isfinite(vmin) and np.isfinite(vmax) and vmin != vmax:
+                return vmin, vmax
+        except (TypeError, ValueError):
+            pass
+        return None, None
+
+    if orientation == "vertical":
+        clim = mappable.get_clim() if mappable is not None and hasattr(mappable, 'get_clim') else (None, None)
+        vmin, vmax = _safe_limits(clim, ax.get_ylim())
+
+        # Skip formatting if limits are invalid
+        if vmin is None or vmax is None:
+            return
+
+        ticks = [vmin, 0 if vmin < 0 and vmax > 0 else (vmin + vmax) / 2, vmax]
+        ax.set_yticks(ticks)
+        if colorbar_decimals is not None:
+            # Increase decimals if all ticks round to zero (i.e., would be shown as 0,0,0)
+            dec = int(colorbar_decimals)
+            max_dec = 8
+
+            def all_round_to_zero(vals, d):
+                return all(round(float(v), d) == 0.0 for v in vals)
+
+            while dec < max_dec and all_round_to_zero(ticks, dec):
+                dec += 1
+            ax.yaxis.set_major_formatter(FormatStrFormatter(f"%.{dec}f"))
+            _apply_axis_offset(ax, "y", None)
+        else:
+            fmt, offset = make_smart_formatter(vmin, vmax, k=3)
+            ax.yaxis.set_major_formatter(FuncFormatter(fmt))
+            _apply_axis_offset(ax, "y", offset, pos="left")
+    else:
+        clim = mappable.get_clim() if mappable is not None and hasattr(mappable, 'get_clim') else (None, None)
+        vmin, vmax = _safe_limits(clim, ax.get_xlim())
+
+        # Skip formatting if limits are invalid
+        if vmin is None or vmax is None:
+            return
+
+        ticks = [vmin, 0 if vmin < 0 and vmax > 0 else (vmin + vmax) / 2, vmax]
+        ax.set_xticks(ticks)
+        if colorbar_decimals is not None:
+            # Increase decimals if all ticks round to zero (i.e., would be shown as 0,0,0)
+            dec = int(colorbar_decimals)
+            max_dec = 8
+
+            def all_round_to_zero(vals, d):
+                return all(round(float(v), d) == 0.0 for v in vals)
+
+            while dec < max_dec and all_round_to_zero(ticks, dec):
+                dec += 1
+            ax.xaxis.set_major_formatter(FormatStrFormatter(f"%.{dec}f"))
+            _apply_axis_offset(ax, "x", None)
+        else:
+            fmt, offset = make_smart_formatter(vmin, vmax, k=3)
+            ax.xaxis.set_major_formatter(FuncFormatter(fmt))
+            _apply_axis_offset(ax, "x", offset, pos="top")
+
+    # Fully disable clipping on tick marks so extreme ticks are visible
+    for tick in ax.yaxis.get_major_ticks() + ax.xaxis.get_major_ticks():
+        for line in [tick.tick1line, tick.tick2line]:
+            line.set_clip_on(False)
+            line.set_clip_box(None)
+            line.set_clip_path(None)
+
+
+def arrowed_spines(ax=None, arrow_length=1, labels=("", ""), arrowprops=None):
+    xlabel, ylabel = labels
+    if ax is None:
+        ax = plt.gca()
+    if arrowprops is None:
+        arrowprops = dict(arrowstyle="<|-", facecolor="black", lw=1)
+
+    for i, spine in enumerate(["left", "bottom"]):
+        # Set up the annotation parameters
+        t = ax.spines[spine].get_transform()
+        xy, xycoords = [1, 0], ("axes fraction", t)
+        xytext, textcoords = [arrow_length, 0], ("offset points", t)
+        ha, va = "left", "bottom"
+
+        # If axis is reversed, draw the arrow the other way
+        top, bottom = ax.spines[spine].axis.get_view_interval()
+        if top > bottom:
+            xy[0] = 0
+            xytext[0] *= -1
+            ha, va = "right", "top"
+
+        if spine == "bottom":
+            xarrow = ax.annotate(
+                xlabel,
+                xy,
+                xycoords=xycoords,
+                xytext=xytext,
+                textcoords=textcoords,
+                ha=ha,
+                va="center",
+                arrowprops=arrowprops,
+            )
+        else:
+            yarrow = ax.annotate(
+                ylabel,
+                xy[::-1],
+                xycoords=xycoords[::-1],
+                xytext=xytext[::-1],
+                textcoords=textcoords[::-1],
+                ha="center",
+                va=va,
+                arrowprops=arrowprops,
+            )
+    return xarrow, yarrow
+
+
+def set_color_cycle_from_cmap(
+    cmap="viridis", n=8, start=0.0, stop=1.0, endpoint=True, reverse=False, to_hex=False
+):
+    """
+    Update Matplotlib rcParams to use a color cycle sampled from a continuous colormap.
+
+    Example:
+        set_color_cycle_from_cmap("viridis", n=6)
+    """
+    cyc = make_cycler_from_cmap(
+        cmap=cmap,
+        n=n,
+        start=start,
+        stop=stop,
+        endpoint=endpoint,
+        reverse=reverse,
+        to_hex=to_hex,
+    )
+    plt.rcParams["axes.prop_cycle"] = cyc