Merge pull request matplotlib#2522 from toddrjen/spectrum

Add additional spectrum-related plots and improve underlying structure

Author: mdboom

CHANGELOG

@@ -1,3 +1,19 @@
+2013-10-06 Add stride-based functions to mlab for easy creation of 2D arrays
+           with less memory.
+
+2013-10-06 Improve window and detrend functions in mlab, particulart support for
+           2D arrays.
+
+2013-10-06 Improve performance of all spectrum-related mlab functions and plots.
+
+2013-10-06 Added support for magnitude, phase, and angle spectrums to
+           axes.specgram, and support for magnitude, phase, angle, and complex
+           spectrums to mlab-specgram.
+
+2013-10-06 Added magnitude_spectrum, angle_spectrum, and phase_spectrum plots,
+           as well as magnitude_spectrum, angle_spectrum, phase_spectrum,
+           and complex_spectrum functions to mlab
+
 2013-07-12 Added support for datetime axes to 2d plots. Axis values are passed
            through Axes.convert_xunits/Axes.convert_yunits before being used by
            contour/contourf, pcolormesh and pcolor.

boilerplate.py

@@ -98,6 +98,7 @@ def boilerplate_gen():
     # name.
     _plotcommands = (
         'acorr',
+        'angle_spectrum',
         'arrow',
         'axhline',
         'axhspan',
@@ -123,8 +124,10 @@ def boilerplate_gen():
         'hlines',
         'imshow',
         'loglog',
+        'magnitude_spectrum',
         'pcolor',
         'pcolormesh',
+        'phase_spectrum',
         'pie',
         'plot',
         'plot_date',

doc/api/api_changes.rst

@@ -76,6 +76,28 @@ original location:
     - `xycoords` -> set the units of the point location
     - `set_position()` -> `Annotation` only set location of annotation
 
+* NFFT being even is now enforced in `matplotlib.mlab.specgram`,
+  `matplotlib.mlab.psd`,  `matplotlib.mlab.csd`,
+  `matplotlib.mlab.cohere`, `matplotlib.mlab.cohere_pairs`,
+  `matplotlib.pyplot.specgram`, `matplotlib.pyplot.psd`,
+  `matplotlib.pyplot.csd`, and `matplotlib.pyplot.cohere`.  This was
+  listed as a requirement but was not actually checked.
+
+* `matplotlib.mlab.specgram`, `matplotlib.mlab.psd`,  `matplotlib.mlab.csd`,
+  `matplotlib.mlab.cohere`, `matplotlib.mlab.cohere_pairs`,
+  `matplotlib.pyplot.specgram`, `matplotlib.pyplot.psd`,
+  `matplotlib.pyplot.csd`, and `matplotlib.pyplot.cohere` now raise
+  ValueError where they previously raised AssertionError.
+
+* For `matplotlib.mlab.psd`,  `matplotlib.mlab.csd`,
+  `matplotlib.mlab.cohere`, `matplotlib.mlab.cohere_pairs`,
+  `matplotlib.pyplot.specgram`, `matplotlib.pyplot.psd`,
+  `matplotlib.pyplot.csd`, and `matplotlib.pyplot.cohere`, in cases
+  where a shape (n, 1) array is returned, this is now converted to a (n, )
+  array.  Previously, (n, m) arrays were averaged to an (n, ) array, but
+  (n, 1) arrays were returend unchanged.  This change makes the dimensions
+  consistent in both cases.
+
 
 .. _changes_in_1_3:
 

doc/users/whats_new.rst

@@ -32,6 +32,36 @@ Andrew Dawson added support for datetime axes to
 :func:`~matplotlib.pyplot.contour`, :func:`~matplotlib.pyplot.contourf`, 
 :func:`~matplotlib.pyplot.pcolormesh` and :func:`~matplotlib.pyplot.pcolor`. 
 
+Support for additional spectrum types
+`````````````````````````````````````
+Todd Jennings added support for new types of frequency spectrum plots:
+:func:`~matplotlib.pyplot.magnitude_spectrum`,
+:func:`~matplotlib.pyplot.phase_spectrum`, and
+:func:`~matplotlib.pyplot.angle_spectrum`, as well as corresponding functions
+in mlab.
+
+He also added these spectrum types to :func:`~matplotlib.pyplot.specgram`,
+as well as adding support for linear scaling there (in addition to the
+existing dB scaling). Support for additional spectrum types was also added to
+:func:`~matplotlib.mlab.specgram`.
+
+He also increased the performance for all of these functions and plot types.
+
+Support for detrending and windowing 2D arrays in mlab
+``````````````````````````````````````````````````````
+Todd Jennings added support for 2D arrays in the 
+:func:`~matplotlib.mlab.detrend_mean`, :func:`~matplotlib.mlab.detrend_none`,
+and :func:`~matplotlib.mlab.detrend`, as well as adding 
+:func:`~matplotlib.mlab.apply_window` which support windowing 2D arrays.
+
+Support for strides in mlab
+```````````````````````````
+Todd Jennings added some functions to mlab to make it easier to use numpy
+strides to create memory-efficient 2D arrays.  This includes
+:func:`~matplotlib.mlab.stride_repeat`, which repeats an array to create a 2D
+array, and :func:`~matplotlib.mlab.stride_windows`, which uses a moving window
+to create a 2D array from a 1D array.
+
 
 Date handling
 -------------

examples/pylab_examples/spectrum_demo.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python
+# python
+
+from pylab import *
+
+dt = 0.01
+Fs = 1/dt
+t = arange(0, 10, dt)
+nse = randn(len(t))
+r = exp(-t/0.05)
+
+cnse = convolve(nse, r)*dt
+cnse = cnse[:len(t)]
+s = 0.1*sin(2*pi*t) + cnse
+
+subplot(3, 2, 1)
+plot(t, s)
+
+subplot(3, 2, 3)
+magnitude_spectrum(s, Fs=Fs)
+
+subplot(3, 2, 4)
+magnitude_spectrum(s, Fs=Fs, scale='dB')
+
+subplot(3, 2, 5)
+angle_spectrum(s, Fs=Fs)
+
+subplot(3, 2, 6)
+phase_spectrum(s, Fs=Fs)
+
+show()