Update the axes.csd() to match the new options added to mlab.csd(). Move some of the docs from axes.psd() to the common place in mlab.

dopplershift · dopplershift · commit 10e73c36b3e3 · 2008-11-11T19:28:38.000Z
svn path=/trunk/matplotlib/; revision=6393
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,3 +1,7 @@
+2008-11-11 Update the axes.csd() to match the new options added to
+           mlab.csd().  Move some of the docs from axes.psd() to  
+           the common place in mlab. - RM
+
 2008-11-11 Update the mlab.csd() to match the new options added to
            mlab.psd().  Factor out the keyword argument docs so that
            they can be shared between the two functions. - RM
diff --git a/lib/matplotlib/axes.py b/lib/matplotlib/axes.py
@@ -6531,9 +6531,10 @@ def psd(self, x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
         call signature::
 
           psd(x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
-              window=mlab.window_hanning, noverlap=0, **kwargs)
+              window=mlab.window_hanning, noverlap=0, pad_to=None,
+              sides='default', **kwargs)
 
-        The power spectral density by Welches average periodogram
+        The power spectral density by Welch's average periodogram
         method.  The vector *x* is divided into *NFFT* length
         segments.  Each segment is detrended by function *detrend* and
         windowed by function *window*.  *noverlap* gives the length of
@@ -6542,41 +6543,14 @@ def psd(self, x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
         scaling to correct for power loss due to windowing.  *Fs* is the
         sampling frequency.
 
-        Keyword arguments:
-
-          *NFFT*: integer
-            The length of the fft segment, must be a power of 2
-
-          *Fs*: integer
-            The sampling frequency.
+        %(PSD)s
 
           *Fc*: integer
             The center frequency of *x* (defaults to 0), which offsets
             the x extents of the plot to reflect the frequency range used
             when a signal is acquired and then filtered and downsampled to
             baseband.
 
-          *detrend*:
-            The function applied to each segment before fft-ing,
-            designed to remove the mean or linear trend.  Unlike in
-            matlab, where the *detrend* parameter is a vector, in
-            matplotlib is it a function.  The :mod:`~matplotlib.pylab`
-            module defines :func:`~matplotlib.pylab.detrend_none`,
-            :func:`~matplotlib.pylab.detrend_mean`, and
-            :func:`~matplotlib.pylab.detrend_linear`, but you can use
-            a custom function as well.
-
-          *window*:
-            The function used to window the segments.  *window* is a
-            function, unlike in matlab where it is a vector.
-            :mod:`~matplotlib.pylab` defines
-            :func:`~matplotlib.pylab.window_none`, and
-            :func:`~matplotlib.pylab.window_hanning`, but you can use
-            a custom function as well.
-
-          *noverlap*: integer
-            Gives the length of the overlap between segments.
-
         Returns the tuple (*Pxx*, *freqs*).
 
         For plotting, the power is plotted as
@@ -6615,17 +6589,24 @@ def psd(self, x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
         self.set_yticks(ticks)
 
         return pxx, freqs
-    psd.__doc__ = cbook.dedent(psd.__doc__) % martist.kwdocd
+
+    psd_doc_dict = dict()
+    psd_doc_dict.update(martist.kwdocd)
+    psd_doc_dict.update(mlab.kwdocd)
+    psd_doc_dict['PSD'] = cbook.dedent(psd_doc_dict['PSD'])
+    psd.__doc__ = cbook.dedent(psd.__doc__) % psd_doc_dict
 
     def csd(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
-            window=mlab.window_hanning, noverlap=0, **kwargs):
+            window=mlab.window_hanning, noverlap=0, pad_to=None,
+            sides='default', **kwargs):
         """
         call signature::
 
           csd(x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
-              window=window_hanning, noverlap=0, **kwargs)
+              window=mlab.window_hanning, noverlap=0, pad_to=None,
+              sides='default', **kwargs)
 
-        The cross spectral density :math:`P_{xy}` by Welches average
+        The cross spectral density :math:`P_{xy}` by Welch's average
         periodogram method.  The vectors *x* and *y* are divided into
         *NFFT* length segments.  Each segment is detrended by function
         *detrend* and windowed by function *window*.  The product of
@@ -6637,6 +6618,14 @@ def csd(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
         (complex valued), and :math:`10\log_{10}|P_{xy}|` is
         plotted.
 
+        %(PSD)s
+
+          *Fc*: integer
+            The center frequency of *x* (defaults to 0), which offsets
+            the x extents of the plot to reflect the frequency range used
+            when a signal is acquired and then filtered and downsampled to
+            baseband.
+
         References:
           Bendat & Piersol -- Random Data: Analysis and Measurement
           Procedures, John Wiley & Sons (1986)
@@ -6654,7 +6643,8 @@ def csd(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
                 For a description of the optional parameters.
         """
         if not self._hold: self.cla()
-        pxy, freqs = mlab.csd(x, y, NFFT, Fs, detrend, window, noverlap)
+        pxy, freqs = mlab.csd(x, y, NFFT, Fs, detrend, window, noverlap,
+            pad_to, sides)
         pxy.shape = len(freqs),
         # pxy is complex
         freqs += Fc
@@ -6672,7 +6662,8 @@ def csd(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
         self.set_yticks(ticks)
 
         return pxy, freqs
-    csd.__doc__ = cbook.dedent(csd.__doc__) % martist.kwdocd
+    csd.__doc__ = cbook.dedent(csd.__doc__) % psd_doc_dict
+    del psd_doc_dict #So that this does not become an Axes attribute
 
     def cohere(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
                window=mlab.window_hanning, noverlap=0, **kwargs):
diff --git a/lib/matplotlib/mlab.py b/lib/matplotlib/mlab.py
@@ -310,48 +310,55 @@ def psd(x, NFFT=256, Fs=2, detrend=detrend_none,
 #Split out these keyword docs so that they can be used elsewhere
 kwdocd = dict()
 kwdocd['PSD'] ="""
-    *NFFT*
-        The number of data points used in each block for the FFT.
-        Must be even; a power 2 is most efficient.  The default value is 256.
-
-    *Fs*
-        The sampling frequency (samples per time unit).  It is used
-        to calculate the Fourier frequencies, freqs, in cycles per time
-        unit. The default value is 2.
-
-    *detrend*
-        Any callable function (unlike in matlab where it is a vector).
-        For examples, see :func:`detrend`, :func:`detrend_none`, and
-        :func:`detrend_mean`.  The default is :func:`detrend_none`.
-
-    *window*
-        A function or a vector of length *NFFT*. To create window
-        vectors see :func:`window_hanning`, :func:`window_none`,
-        :func:`numpy.blackman`, :func:`numpy.hamming`,
-        :func:`numpy.bartlett`, :func:`scipy.signal`,
-        :func:`scipy.signal.get_window`, etc. The default is
-        :func:`window_hanning`.  If a function is passed as the
-        argument, it must take a data segment as an argument and
-        return the windowed version of the segment.
-
-    *noverlap*
-        The number of points of overlap between blocks.  The default value
-        is 0 (no overlap).
-
-    *pad_to*
-        The number of points to which the data segment is padd when
-        performing the FFT.  This can be different from *NFFT*, which
-        specifies the number of data points used.  While not increasing
-        the actual resolution of the psd (the minimum distance between
-        resolvable peaks), this can give more points in the plot,
-        allowing for more detail. This corresponds to the *n* parameter
-        in the call to fft(). The default is None, which sets *pad_to*
-        equal to *NFFT*
-
-    *sides* [ 'default' | 'onesided' | 'twosided' ]
-        Specifies which sides of the PSD to return.  Default gives the
-        default behavior, which returns one-sided for real data and both
-        for complex data.  'one' forces the return of a one-sided PSD, while
+    Keyword arguments:
+
+      *NFFT*: integer
+          The number of data points used in each block for the FFT.
+          Must be even; a power 2 is most efficient.  The default value is 256.
+
+      *Fs*: scalar
+          The sampling frequency (samples per time unit).  It is used
+          to calculate the Fourier frequencies, freqs, in cycles per time
+          unit. The default value is 2.
+
+      *detrend*: callable
+          The function applied to each segment before fft-ing,
+          designed to remove the mean or linear trend.  Unlike in
+          matlab, where the *detrend* parameter is a vector, in
+          matplotlib is it a function.  The :mod:`~matplotlib.pylab`
+          module defines :func:`~matplotlib.pylab.detrend_none`,
+          :func:`~matplotlib.pylab.detrend_mean`, and
+          :func:`~matplotlib.pylab.detrend_linear`, but you can use
+          a custom function as well.
+
+      *window*: callable or ndarray
+          A function or a vector of length *NFFT*. To create window
+          vectors see :func:`window_hanning`, :func:`window_none`,
+          :func:`numpy.blackman`, :func:`numpy.hamming`,
+          :func:`numpy.bartlett`, :func:`scipy.signal`,
+          :func:`scipy.signal.get_window`, etc. The default is
+          :func:`window_hanning`.  If a function is passed as the
+          argument, it must take a data segment as an argument and
+          return the windowed version of the segment.
+
+      *noverlap*: integer
+          The number of points of overlap between blocks.  The default value
+          is 0 (no overlap).
+
+      *pad_to*: integer
+          The number of points to which the data segment is padd when
+          performing the FFT.  This can be different from *NFFT*, which
+          specifies the number of data points used.  While not increasing
+          the actual resolution of the psd (the minimum distance between
+          resolvable peaks), this can give more points in the plot,
+          allowing for more detail. This corresponds to the *n* parameter
+          in the call to fft(). The default is None, which sets *pad_to*
+          equal to *NFFT*
+
+      *sides*: [ 'default' | 'onesided' | 'twosided' ]
+          Specifies which sides of the PSD to return.  Default gives the
+          default behavior, which returns one-sided for real data and both
+          for complex data.  'one' forces the return of a one-sided PSD, while
         'both' forces two-sided.
 """
 psd.__doc__ = psd.__doc__ % kwdocd
