Merge pull request matplotlib#13987 from anntzer/mlab

API: Deprecate mlab.{apply_window,stride_repeat}.

Author: tacaswell

doc/api/next_api_changes/2019-04-18-AL.rst

@@ -0,0 +1,4 @@
+Deprecations
+````````````
+
+``mlab.apply_window`` and ``mlab.stride_repeat`` are deprecated.

lib/matplotlib/mlab.py

@@ -84,6 +84,7 @@ def window_none(x):
     return x
 
 
+@cbook.deprecated("3.2")
 def apply_window(x, window, axis=0, return_window=None):
     '''
     Apply the given window to the given 1D or 2D array along the given axis.
@@ -376,6 +377,7 @@ def stride_windows(x, n, noverlap=None, axis=0):
     return np.lib.stride_tricks.as_strided(x, shape=shape, strides=strides)
 
 
+@cbook.deprecated("3.2")
 def stride_repeat(x, n, axis=0):
     '''
     Repeat the values in an array in a memory-efficient manner.  Array x is
@@ -520,29 +522,34 @@ def _spectral_helper(x, y=None, NFFT=None, Fs=None, detrend_func=None,
             numFreqs = pad_to//2 + 1
         scaling_factor = 2.
 
+    if not np.iterable(window):
+        window = window(np.ones(NFFT, x.dtype))
+    if len(window) != NFFT:
+        raise ValueError(
+            "The window length must match the data's first dimension")
+
     result = stride_windows(x, NFFT, noverlap, axis=0)
     result = detrend(result, detrend_func, axis=0)
-    result, windowVals = apply_window(result, window, axis=0,
-                                      return_window=True)
+    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 = detrend(resultY, detrend_func, axis=0)
-        resultY = apply_window(resultY, window, axis=0)
+        resultY = resultY * window.reshape((-1, 1))
         resultY = np.fft.fft(resultY, n=pad_to, axis=0)[:numFreqs, :]
         result = np.conj(result) * resultY
     elif mode == 'psd':
         result = np.conj(result) * result
     elif mode == 'magnitude':
-        result = np.abs(result) / np.abs(windowVals).sum()
+        result = np.abs(result) / np.abs(window).sum()
     elif mode == 'angle' or mode == 'phase':
         # we unwrap the phase later to handle the onesided vs. twosided case
         result = np.angle(result)
     elif mode == 'complex':
-        result /= np.abs(windowVals).sum()
+        result /= np.abs(window).sum()
 
     if mode == 'psd':
 
@@ -566,10 +573,10 @@ def _spectral_helper(x, y=None, NFFT=None, Fs=None, detrend_func=None,
             result /= Fs
             # Scale the spectrum by the norm of the window to compensate for
             # windowing loss; see Bendat & Piersol Sec 11.5.2.
-            result /= (np.abs(windowVals)**2).sum()
+            result /= (np.abs(window)**2).sum()
         else:
             # In this case, preserve power in the segment, not amplitude
-            result /= np.abs(windowVals).sum()**2
+            result /= np.abs(window).sum()**2
 
     t = np.arange(NFFT/2, len(x) - NFFT/2 + 1, NFFT - noverlap)/Fs
 

lib/matplotlib/tests/test_mlab.py

@@ -18,6 +18,11 @@
 '''
 
 
+def _stride_repeat(*args, **kwargs):
+    with pytest.warns(MatplotlibDeprecationWarning):
+        return mlab.stride_repeat(*args, **kwargs)
+
+
 class TestStride(object):
     def get_base(self, x):
         y = x
@@ -61,26 +66,26 @@ def test_stride_windows_invalid_params(self, n, noverlap):
     def test_stride_repeat_invalid_input_shape(self, shape):
         x = np.arange(np.prod(shape)).reshape(shape)
         with pytest.raises(ValueError):
-            mlab.stride_repeat(x, 5)
+            _stride_repeat(x, 5)
 
     @pytest.mark.parametrize('axis', [-1, 2],
                              ids=['axis less than 0',
                                   'axis greater than input shape'])
     def test_stride_repeat_invalid_axis(self, axis):
         x = np.array(0)
         with pytest.raises(ValueError):
-            mlab.stride_repeat(x, 5, axis=axis)
+            _stride_repeat(x, 5, axis=axis)
 
     def test_stride_repeat_n_lt_1_ValueError(self):
         x = np.arange(10)
         with pytest.raises(ValueError):
-            mlab.stride_repeat(x, 0)
+            _stride_repeat(x, 0)
 
     @pytest.mark.parametrize('axis', [0, 1], ids=['axis0', 'axis1'])
     @pytest.mark.parametrize('n', [1, 5], ids=['n1', 'n5'])
     def test_stride_repeat(self, n, axis):
         x = np.arange(10)
-        y = mlab.stride_repeat(x, n, axis=axis)
+        y = _stride_repeat(x, n, axis=axis)
 
         expected_shape = [10, 10]
         expected_shape[axis] = n
@@ -137,7 +142,7 @@ def test_stride_ensure_integer_type(self):
         # even previous to #3845 could not find any problematic
         # configuration however, let's be sure it's not accidentally
         # introduced
-        y_strided = mlab.stride_repeat(y, n=33.815)
+        y_strided = _stride_repeat(y, n=33.815)
         assert_array_equal(y_strided, 0.3)
 
 
@@ -187,6 +192,11 @@ def test_csv2rec_dates(tempcsv, input, kwargs):
     assert_array_equal(array['a'].tolist(), expected)
 
 
+def _apply_window(*args, **kwargs):
+    with pytest.warns(MatplotlibDeprecationWarning):
+        return mlab.apply_window(*args, **kwargs)
+
+
 class TestWindow(object):
     def setup(self):
         np.random.seed(0)
@@ -238,31 +248,31 @@ def test_apply_window_1D_axis1_ValueError(self):
         x = self.sig_rand
         window = mlab.window_hanning
         with pytest.raises(ValueError):
-            mlab.apply_window(x, window, axis=1, return_window=False)
+            _apply_window(x, window, axis=1, return_window=False)
 
     def test_apply_window_1D_els_wrongsize_ValueError(self):
         x = self.sig_rand
         window = mlab.window_hanning(np.ones(x.shape[0]-1))
         with pytest.raises(ValueError):
-            mlab.apply_window(x, window)
+            _apply_window(x, window)
 
     def test_apply_window_0D_ValueError(self):
         x = np.array(0)
         window = mlab.window_hanning
         with pytest.raises(ValueError):
-            mlab.apply_window(x, window, axis=1, return_window=False)
+            _apply_window(x, window, axis=1, return_window=False)
 
     def test_apply_window_3D_ValueError(self):
         x = self.sig_rand[np.newaxis][np.newaxis]
         window = mlab.window_hanning
         with pytest.raises(ValueError):
-            mlab.apply_window(x, window, axis=1, return_window=False)
+            _apply_window(x, window, axis=1, return_window=False)
 
     def test_apply_window_hanning_1D(self):
         x = self.sig_rand
         window = mlab.window_hanning
         window1 = mlab.window_hanning(np.ones(x.shape[0]))
-        y, window2 = mlab.apply_window(x, window, return_window=True)
+        y, window2 = _apply_window(x, window, return_window=True)
         yt = window(x)
         assert yt.shape == y.shape
         assert x.shape == y.shape
@@ -272,7 +282,7 @@ def test_apply_window_hanning_1D(self):
     def test_apply_window_hanning_1D_axis0(self):
         x = self.sig_rand
         window = mlab.window_hanning
-        y = mlab.apply_window(x, window, axis=0, return_window=False)
+        y = _apply_window(x, window, axis=0, return_window=False)
         yt = window(x)
         assert yt.shape == y.shape
         assert x.shape == y.shape
@@ -282,7 +292,7 @@ def test_apply_window_hanning_els_1D_axis0(self):
         x = self.sig_rand
         window = mlab.window_hanning(np.ones(x.shape[0]))
         window1 = mlab.window_hanning
-        y = mlab.apply_window(x, window, axis=0, return_window=False)
+        y = _apply_window(x, window, axis=0, return_window=False)
         yt = window1(x)
         assert yt.shape == y.shape
         assert x.shape == y.shape
@@ -291,7 +301,7 @@ def test_apply_window_hanning_els_1D_axis0(self):
     def test_apply_window_hanning_2D_axis0(self):
         x = np.random.standard_normal([1000, 10]) + 100.
         window = mlab.window_hanning
-        y = mlab.apply_window(x, window, axis=0, return_window=False)
+        y = _apply_window(x, window, axis=0, return_window=False)
         yt = np.zeros_like(x)
         for i in range(x.shape[1]):
             yt[:, i] = window(x[:, i])
@@ -303,7 +313,7 @@ def test_apply_window_hanning_els1_2D_axis0(self):
         x = np.random.standard_normal([1000, 10]) + 100.
         window = mlab.window_hanning(np.ones(x.shape[0]))
         window1 = mlab.window_hanning
-        y = mlab.apply_window(x, window, axis=0, return_window=False)
+        y = _apply_window(x, window, axis=0, return_window=False)
         yt = np.zeros_like(x)
         for i in range(x.shape[1]):
             yt[:, i] = window1(x[:, i])
@@ -315,7 +325,7 @@ def test_apply_window_hanning_els2_2D_axis0(self):
         x = np.random.standard_normal([1000, 10]) + 100.
         window = mlab.window_hanning
         window1 = mlab.window_hanning(np.ones(x.shape[0]))
-        y, window2 = mlab.apply_window(x, window, axis=0, return_window=True)
+        y, window2 = _apply_window(x, window, axis=0, return_window=True)
         yt = np.zeros_like(x)
         for i in range(x.shape[1]):
             yt[:, i] = window1*x[:, i]
@@ -328,8 +338,8 @@ def test_apply_window_hanning_els3_2D_axis0(self):
         x = np.random.standard_normal([1000, 10]) + 100.
         window = mlab.window_hanning
         window1 = mlab.window_hanning(np.ones(x.shape[0]))
-        y, window2 = mlab.apply_window(x, window, axis=0, return_window=True)
-        yt = mlab.apply_window(x, window1, axis=0, return_window=False)
+        y, window2 = _apply_window(x, window, axis=0, return_window=True)
+        yt = _apply_window(x, window1, axis=0, return_window=False)
         assert yt.shape == y.shape
         assert x.shape == y.shape
         assert_allclose(yt, y, atol=1e-06)
@@ -338,7 +348,7 @@ def test_apply_window_hanning_els3_2D_axis0(self):
     def test_apply_window_hanning_2D_axis1(self):
         x = np.random.standard_normal([10, 1000]) + 100.
         window = mlab.window_hanning
-        y = mlab.apply_window(x, window, axis=1, return_window=False)
+        y = _apply_window(x, window, axis=1, return_window=False)
         yt = np.zeros_like(x)
         for i in range(x.shape[0]):
             yt[i, :] = window(x[i, :])
@@ -350,7 +360,7 @@ def test_apply_window_hanning_2D__els1_axis1(self):
         x = np.random.standard_normal([10, 1000]) + 100.
         window = mlab.window_hanning(np.ones(x.shape[1]))
         window1 = mlab.window_hanning
-        y = mlab.apply_window(x, window, axis=1, return_window=False)
+        y = _apply_window(x, window, axis=1, return_window=False)
         yt = np.zeros_like(x)
         for i in range(x.shape[0]):
             yt[i, :] = window1(x[i, :])
@@ -362,7 +372,7 @@ def test_apply_window_hanning_2D_els2_axis1(self):
         x = np.random.standard_normal([10, 1000]) + 100.
         window = mlab.window_hanning
         window1 = mlab.window_hanning(np.ones(x.shape[1]))
-        y, window2 = mlab.apply_window(x, window, axis=1, return_window=True)
+        y, window2 = _apply_window(x, window, axis=1, return_window=True)
         yt = np.zeros_like(x)
         for i in range(x.shape[0]):
             yt[i, :] = window1 * x[i, :]
@@ -375,8 +385,8 @@ def test_apply_window_hanning_2D_els3_axis1(self):
         x = np.random.standard_normal([10, 1000]) + 100.
         window = mlab.window_hanning
         window1 = mlab.window_hanning(np.ones(x.shape[1]))
-        y = mlab.apply_window(x, window, axis=1, return_window=False)
-        yt = mlab.apply_window(x, window1, axis=1, return_window=False)
+        y = _apply_window(x, window, axis=1, return_window=False)
+        yt = _apply_window(x, window1, axis=1, return_window=False)
         assert yt.shape == y.shape
         assert x.shape == y.shape
         assert_allclose(yt, y, atol=1e-06)
@@ -385,7 +395,7 @@ def test_apply_window_stride_windows_hanning_2D_n13_noverlapn3_axis0(self):
         x = self.sig_rand
         window = mlab.window_hanning
         yi = mlab.stride_windows(x, n=13, noverlap=2, axis=0)
-        y = mlab.apply_window(yi, window, axis=0, return_window=False)
+        y = _apply_window(yi, window, axis=0, return_window=False)
         yt = self.check_window_apply_repeat(x, window, 13, 2)
         assert yt.shape == y.shape
         assert x.shape != y.shape
@@ -395,45 +405,45 @@ def test_apply_window_hanning_2D_stack_axis1(self):
         ydata = np.arange(32)
         ydata1 = ydata+5
         ydata2 = ydata+3.3
-        ycontrol1 = mlab.apply_window(ydata1, mlab.window_hanning)
+        ycontrol1 = _apply_window(ydata1, mlab.window_hanning)
         ycontrol2 = mlab.window_hanning(ydata2)
         ydata = np.vstack([ydata1, ydata2])
         ycontrol = np.vstack([ycontrol1, ycontrol2])
         ydata = np.tile(ydata, (20, 1))
         ycontrol = np.tile(ycontrol, (20, 1))
-        result = mlab.apply_window(ydata, mlab.window_hanning, axis=1,
-                                   return_window=False)
+        result = _apply_window(ydata, mlab.window_hanning, axis=1,
+                               return_window=False)
         assert_allclose(ycontrol, result, atol=1e-08)
 
     def test_apply_window_hanning_2D_stack_windows_axis1(self):
         ydata = np.arange(32)
         ydata1 = ydata+5
         ydata2 = ydata+3.3
-        ycontrol1 = mlab.apply_window(ydata1, mlab.window_hanning)
+        ycontrol1 = _apply_window(ydata1, mlab.window_hanning)
         ycontrol2 = mlab.window_hanning(ydata2)
         ydata = np.vstack([ydata1, ydata2])
         ycontrol = np.vstack([ycontrol1, ycontrol2])
         ydata = np.tile(ydata, (20, 1))
         ycontrol = np.tile(ycontrol, (20, 1))
-        result = mlab.apply_window(ydata, mlab.window_hanning, axis=1,
-                                   return_window=False)
+        result = _apply_window(ydata, mlab.window_hanning, axis=1,
+                               return_window=False)
         assert_allclose(ycontrol, result, atol=1e-08)
 
     def test_apply_window_hanning_2D_stack_windows_axis1_unflatten(self):
         n = 32
         ydata = np.arange(n)
         ydata1 = ydata+5
         ydata2 = ydata+3.3
-        ycontrol1 = mlab.apply_window(ydata1, mlab.window_hanning)
+        ycontrol1 = _apply_window(ydata1, mlab.window_hanning)
         ycontrol2 = mlab.window_hanning(ydata2)
         ydata = np.vstack([ydata1, ydata2])
         ycontrol = np.vstack([ycontrol1, ycontrol2])
         ydata = np.tile(ydata, (20, 1))
         ycontrol = np.tile(ycontrol, (20, 1))
         ydata = ydata.flatten()
         ydata1 = mlab.stride_windows(ydata, 32, noverlap=0, axis=0)
-        result = mlab.apply_window(ydata1, mlab.window_hanning, axis=0,
-                                   return_window=False)
+        result = _apply_window(ydata1, mlab.window_hanning, axis=0,
+                               return_window=False)
         assert_allclose(ycontrol.T, result, atol=1e-08)
 
 
@@ -1541,9 +1551,9 @@ def test_psd_window_hanning(self):
         ydata = np.arange(self.NFFT_density)
         ydata1 = ydata+5
         ydata2 = ydata+3.3
-        ycontrol1, windowVals = mlab.apply_window(ydata1,
-                                                  mlab.window_hanning,
-                                                  return_window=True)
+        ycontrol1, windowVals = _apply_window(ydata1,
+                                              mlab.window_hanning,
+                                              return_window=True)
         ycontrol2 = mlab.window_hanning(ydata2)
         ydata = np.vstack([ydata1, ydata2])
         ycontrol = np.vstack([ycontrol1, ycontrol2])
@@ -1587,9 +1597,9 @@ def test_psd_window_hanning_detrend_linear(self):
         ydata2 = ydata+3.3
         ycontrol1 = ycontrol
         ycontrol2 = ycontrol
-        ycontrol1, windowVals = mlab.apply_window(ycontrol1,
-                                                  mlab.window_hanning,
-                                                  return_window=True)
+        ycontrol1, windowVals = _apply_window(ycontrol1,
+                                              mlab.window_hanning,
+                                              return_window=True)
         ycontrol2 = mlab.window_hanning(ycontrol2)
         ydata = np.vstack([ydata1, ydata2])
         ycontrol = np.vstack([ycontrol1, ycontrol2])