Force origin='upper' in pyplot.specgram (#17897)

kate-perkins · dstansby · theodorju · web-flow · commit 7a4df1afabdf · 2020-07-15T18:17:52.000-04:00
* Force origin='upper' in specgram function

Specify origin='upper' in call to imshow within specgram to override rcparams setting for origin without changing rcparams itself. Delete origin from kwargs so there are not two occurrences of the origin parameter in the call to imshow (this also means the origin kwarg cannot be changed by the caller).

* DOC: indicate that origin is force set to upper

* Adding test for issue 17878

* DOC: Change rcParam from 'origin' to 'image.origin'

* TST: try changing origin in specgram call

* Document behavior change for specgram

* Document api behavior change

* Raise exception if origin kwarg passed to specgram

This ensures the origin kwarg is not silently ignored if passed to pyplot.specgram.

* TST: passing origin kwarg to specgram should fail

The function pyplot.specgram should raise a TypeError if origin is passed as a keyword argument.

* DOC: Remove note that origin='upper' in specgram

This note referenced the call to imshow inside of specgram, which might confuse users who do not know the implementation of specgram.

* TST: change from pytest xfail to pytest raises

Passing origin as a keyword argument should raise a type error, so test_specgram_origin_kwarg should raise an exception. Therefore, raises is a more precise check than xfail.

Co-authored-by: David Stansby &lt;dstansby@gmail.com&gt;
Co-authored-by: Theodor Athanasiadis &lt;theodorathanasiadis@gmail.com&gt;
Co-authored-by: Tim Hoffmann &lt;2836374+timhoffm@users.noreply.github.com&gt;
diff --git a/doc/api/next_api_changes/behavior/17897-KLP.rst b/doc/api/next_api_changes/behavior/17897-KLP.rst
@@ -0,0 +1,11 @@
+pyplot.specgram always uses origin='upper'
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Previously if ``image.origin`` was set to something other than 'upper' or if the 
+``origin`` keyword argument was passed with a value other than 'upper', the spectrogram 
+itself would flip, but the axes would remain oriented for an origin value of 'upper', so 
+that the resulting plot was incorrectly labelled.
+
+Now, the ``origin`` keyword argument is not supported and the ``image.origin`` rcParam is 
+ignored. The function matplotlib.pyplot.specgram is forced to use ``origin='upper'``, so 
+that the axes are correct for the plotted spectrogram.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -7464,7 +7464,8 @@ def specgram(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
 
         **kwargs
             Additional keyword arguments are passed on to `~.axes.Axes.imshow`
-            which makes the specgram image.
+            which makes the specgram image. The origin keyword argument
+            is not supported.
 
         Returns
         -------
@@ -7548,8 +7549,13 @@ def specgram(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
         xmin, xmax = xextent
         freqs += Fc
         extent = xmin, xmax, freqs[0], freqs[-1]
+
+        if 'origin' in kwargs:
+            raise TypeError("specgram() got an unexpected keyword argument "
+                            "'origin'")
+
         im = self.imshow(Z, cmap, extent=extent, vmin=vmin, vmax=vmax,
-                         **kwargs)
+                         origin='upper', **kwargs)
         self.axis('auto')
 
         return spec, freqs, t, im
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -4104,6 +4104,33 @@ def test_specgram_fs_none():
     assert xmin == 32 and xmax == 96
 
 
+@check_figures_equal(extensions=["png"])
+def test_specgram_origin_rcparam(fig_test, fig_ref):
+    """Test specgram ignores image.origin rcParam and uses origin 'upper'."""
+    t = np.arange(500)
+    signal = np.sin(t)
+
+    plt.rcParams["image.origin"] = 'upper'
+
+    # Reference: First graph using default origin in imshow (upper),
+    fig_ref.subplots().specgram(signal)
+
+    # Try to overwrite the setting trying to flip the specgram
+    plt.rcParams["image.origin"] = 'lower'
+
+    # Test: origin='lower' should be ignored
+    fig_test.subplots().specgram(signal)
+
+
+def test_specgram_origin_kwarg():
+    """Ensure passing origin as a kwarg raises a TypeError."""
+    t = np.arange(500)
+    signal = np.sin(t)
+
+    with pytest.raises(TypeError):
+        plt.specgram(signal, origin='lower')
+
+
 @image_comparison(
     ["psd_freqs.png", "csd_freqs.png", "psd_noise.png", "csd_noise.png"],
     remove_text=True, tol=0.002)
