{"record":{"id":"6ee0e0f4580f1e9d","repo":"matplotlib/matplotlib","slug":"axis-axis-out-of-bounds","errorCode":null,"errorMessage":"axis(={axis}) out of bounds","messagePattern":"axis\\(=(.+?)\\) out of bounds","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"lib/matplotlib/mlab.py","lineNumber":115,"sourceCode":"    axis : int\n        The axis along which to do the detrending.\n\n    See Also\n    --------\n    detrend_mean : Implementation of the 'mean' algorithm.\n    detrend_linear : Implementation of the 'linear' algorithm.\n    detrend_none : Implementation of the 'none' algorithm.\n    \"\"\"\n    if key is None or key in ['constant', 'mean', 'default']:\n        return detrend(x, key=detrend_mean, axis=axis)\n    elif key == 'linear':\n        return detrend(x, key=detrend_linear, axis=axis)\n    elif key == 'none':\n        return detrend(x, key=detrend_none, axis=axis)\n    elif callable(key):\n        x = np.asarray(x)\n        if axis is not None and axis + 1 > x.ndim:\n            raise ValueError(f'axis(={axis}) out of bounds')\n        if (axis is None and x.ndim == 0) or (not axis and x.ndim == 1):\n            return key(x)\n        # try to use the 'axis' argument if the function supports it,\n        # otherwise use apply_along_axis to do it\n        try:\n            return key(x, axis=axis)\n        except TypeError:\n            return np.apply_along_axis(key, axis=axis, arr=x)\n    else:\n        raise ValueError(\n            f\"Unknown value for key: {key!r}, must be one of: 'default', \"\n            f\"'constant', 'mean', 'linear', or a function\")\n\n\ndef detrend_mean(x, axis=None):\n    \"\"\"\n    Return *x* minus the mean(*x*).\n","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/matplotlib/matplotlib/blob/b379c1b69e012b142c0f496a52bcb30513802d72/lib/matplotlib/mlab.py#L97-L133","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass axis=None (or 0) for 1-D input","Derive the axis from the data: axis = None if np.ndim(x) == 1 else axis","Use np.atleast_2d(x) if the callable genuinely needs to run along axis 1"],"exampleFix":"import numpy as np\n# before\nout = mlab.detrend(x, key=custom_detrend, axis=1)  # x is 1-D -> ValueError\n# after\nout = mlab.detrend(x, key=custom_detrend, axis=None if np.ndim(x) == 1 else 1)","handlingStrategy":"validation","validationCode":"import numpy as np\nif axis is not None and axis >= np.ndim(x):\n    axis = None if np.ndim(x) == 1 else np.ndim(x) - 1\nout = mlab.detrend(x, key=fn, axis=axis)","typeGuard":null,"tryCatchPattern":"try:\n    out = mlab.detrend(x, key=fn, axis=axis)\nexcept ValueError as err:\n    if 'out of bounds' in str(err):\n        out = mlab.detrend(x, key=fn, axis=None)\n    else:\n        raise","preventionTips":["Never hardcode an axis in helpers that accept variable-rank arrays; compute it from x.ndim","Validate axis against np.ndim(x) at function entry"],"tags":["matplotlib","mlab","detrend","numpy-axis"],"backgroundTag":"axis-out-of-bounds","analyzedSha":"b379c1b69e012b142c0f496a52bcb30513802d72","analyzedAt":"2026-08-21T23:31:55.468Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}