matplotlib/matplotlib · error · ValueError

axis(={axis}) out of bounds

Error message

axis(={axis}) out of bounds

What it means

mlab.detrend(x, key=callable, axis=...) applies a custom detrending function along the given axis. Before calling it, matplotlib checks the axis against the array's dimensionality: when axis is not None and axis + 1 exceeds x.ndim, for example axis=1 on a 1-D array, ValueError is raised.

Source

Thrown at lib/matplotlib/mlab.py:115

    axis : int
        The axis along which to do the detrending.

    See Also
    --------
    detrend_mean : Implementation of the 'mean' algorithm.
    detrend_linear : Implementation of the 'linear' algorithm.
    detrend_none : Implementation of the 'none' algorithm.
    """
    if key is None or key in ['constant', 'mean', 'default']:
        return detrend(x, key=detrend_mean, axis=axis)
    elif key == 'linear':
        return detrend(x, key=detrend_linear, axis=axis)
    elif key == 'none':
        return detrend(x, key=detrend_none, axis=axis)
    elif callable(key):
        x = np.asarray(x)
        if axis is not None and axis + 1 > x.ndim:
            raise ValueError(f'axis(={axis}) out of bounds')
        if (axis is None and x.ndim == 0) or (not axis and x.ndim == 1):
            return key(x)
        # try to use the 'axis' argument if the function supports it,
        # otherwise use apply_along_axis to do it
        try:
            return key(x, axis=axis)
        except TypeError:
            return np.apply_along_axis(key, axis=axis, arr=x)
    else:
        raise ValueError(
            f"Unknown value for key: {key!r}, must be one of: 'default', "
            f"'constant', 'mean', 'linear', or a function")


def detrend_mean(x, axis=None):
    """
    Return *x* minus the mean(*x*).

View on GitHub (pinned to b379c1b69e)

Solutions

1. Pass axis=None (or 0) for 1-D input
2. Derive the axis from the data: axis = None if np.ndim(x) == 1 else axis
3. Use np.atleast_2d(x) if the callable genuinely needs to run along axis 1

Example fix

import numpy as np
# before
out = mlab.detrend(x, key=custom_detrend, axis=1)  # x is 1-D -> ValueError
# after
out = mlab.detrend(x, key=custom_detrend, axis=None if np.ndim(x) == 1 else 1)

import numpy as np
if axis is not None and axis >= np.ndim(x):
    axis = None if np.ndim(x) == 1 else np.ndim(x) - 1
out = mlab.detrend(x, key=fn, axis=axis)

try:
    out = mlab.detrend(x, key=fn, axis=axis)
except ValueError as err:
    if 'out of bounds' in str(err):
        out = mlab.detrend(x, key=fn, axis=None)
    else:
        raise

When it happens

Trigger: mlab.detrend(x_1d, key=my_func, axis=1); a fixed axis=1 from a 2-D pipeline reused on 1-D input; axis values inherited from psd/spectrogram-style kwargs where the per-segment data is 1-D.

Common situations: Shared preprocessing helpers serving both single-channel (1-D) and multi-channel (2-D) data with one hardcoded axis; downgrading batch code to single traces without adjusting the axis.

Related errors

• axis(=%s) out of bounds
• Unknown value for key: {key!r}, must be one of: 'default', '
• y cannot have ndim > 1
• noverlap must be less than NFFT
• x and y must be equal if mode is not 'psd'

AI-assisted analysis of matplotlib/matplotlib@b379c1b69e (2026-08-21). Data as JSON: /api/errors/6ee0e0f4580f1e9d. Report an issue: GitHub.