Deprecate mlab.stride_windows.

The functionality is directly provided by numpy>=1.20 (it will be a
while before we can rely on that version of numpy, but we can still
deprecate stride_windows as public API in the meantime, as we don't want
to encourage users to rely on mlab for that).

Author: anntzer

doc/api/next_api_changes/deprecations/ZZZZZ-AL.rst

@@ -0,0 +1,4 @@
+``mlab.stride_windows``
+~~~~~~~~~~~~~~~~~~~~~~~
+... is deprecated.  Use ``np.lib.stride_tricks.sliding_window_view`` instead
+(or ``np.lib.stride_tricks.as_strided`` on numpy<1.20).

lib/matplotlib/mlab.py

@@ -215,6 +215,7 @@ def detrend_linear(y):
     return y - (b*x + a)
 
 
+@_api.deprecated("3.6")
 def stride_windows(x, n, noverlap=None, axis=0):
     """
     Get all windows of x with length n as a single array,
@@ -246,6 +247,18 @@ def stride_windows(x, n, noverlap=None, axis=0):
     """
     if noverlap is None:
         noverlap = 0
+    if np.ndim(x) != 1:
+        raise ValueError('only 1-dimensional arrays can be used')
+    return _stride_windows(x, n, noverlap, axis)
+
+
+def _stride_windows(x, n, noverlap=0, axis=0):
+    # np>=1.20 provides sliding_window_view, and we only ever use axis=0.
+    if hasattr(np.lib.stride_tricks, "sliding_window_view") and axis == 0:
+        if noverlap >= n:
+            raise ValueError('noverlap must be less than n')
+        return np.lib.stride_tricks.sliding_window_view(
+            x, n, axis=0)[::n - noverlap].T
 
     if noverlap >= n:
         raise ValueError('noverlap must be less than n')
@@ -254,8 +267,6 @@ def stride_windows(x, n, noverlap=None, axis=0):
 
     x = np.asarray(x)
 
-    if x.ndim != 1:
-        raise ValueError('only 1-dimensional arrays can be used')
     if n == 1 and noverlap == 0:
         if axis == 0:
             return x[np.newaxis]
@@ -370,15 +381,15 @@ def _spectral_helper(x, y=None, NFFT=None, Fs=None, detrend_func=None,
         raise ValueError(
             "The window length must match the data's first dimension")
 
-    result = stride_windows(x, NFFT, noverlap, axis=0)
+    result = _stride_windows(x, NFFT, noverlap)
     result = detrend(result, detrend_func, axis=0)
     result = result * window.reshape((-1, 1))
     result = np.fft.fft(result, n=pad_to, axis=0)[:numFreqs, :]
     freqs = np.fft.fftfreq(pad_to, 1/Fs)[:numFreqs]
 
     if not same_data:
         # if same_data is False, mode must be 'psd'
-        resultY = stride_windows(y, NFFT, noverlap)
+        resultY = _stride_windows(y, NFFT, noverlap)
         resultY = detrend(resultY, detrend_func, axis=0)
         resultY = resultY * window.reshape((-1, 1))
         resultY = np.fft.fft(resultY, n=pad_to, axis=0)[:numFreqs, :]

lib/matplotlib/tests/test_mlab.py

@@ -3,7 +3,7 @@
 import numpy as np
 import pytest
 
-import matplotlib.mlab as mlab
+from matplotlib import mlab, _api
 
 
 class TestStride:
@@ -13,6 +13,11 @@ def get_base(self, x):
             y = y.base
         return y
 
+    @pytest.fixture(autouse=True)
+    def stride_is_deprecated(self):
+        with _api.suppress_matplotlib_deprecation_warning():
+            yield
+
     def calc_window_target(self, x, NFFT, noverlap=0, axis=0):
         """
         This is an adaptation of the original window extraction algorithm.