Merge pull request matplotlib#10834 from timhoffm/doc-axes-spectral

Minor docstring updates on spectral plot functions

Author: anntzer

lib/matplotlib/axes/_axes.py

@@ -1633,7 +1633,7 @@ def acorr(self, x, **kwargs):
             If ``True``, `Axes.vlines` is used to plot the vertical lines from
             the origin to the acorr. Otherwise, `Axes.plot` is used.
 
-        maxlags : integer, optional, default: 10
+        maxlags : int, optional, default: 10
             Number of lags to show. If ``None``, will return all
             ``2 * len(x) - 1`` lags.
 
@@ -1654,10 +1654,10 @@ def acorr(self, x, **kwargs):
 
         Other Parameters
         ----------------
-        linestyle : `~matplotlib.lines.Line2D` prop, optional, default: None
+        linestyle : `.Line2D` property, optional, default: None
             Only used if usevlines is ``False``.
 
-        marker : string, optional, default: 'o'
+        marker : str, optional, default: 'o'
 
         Notes
         -----
@@ -1674,7 +1674,9 @@ def xcorr(self, x, y, normed=True, detrend=mlab.detrend_none,
         """
         Plot the cross correlation between *x* and *y*.
 
-        The correlation with lag k is defined as sum_n x[n+k] * conj(y[n]).
+        The correlation with lag k is defined as
+        :math:`\sum_n x[n+k] \cdot y^*[n]`, where :math:`y^*` is the complex
+        conjugate of :math:`y`.
 
         Parameters
         ----------
@@ -1716,7 +1718,7 @@ def xcorr(self, x, y, normed=True, detrend=mlab.detrend_none,
 
         Other Parameters
         ----------------
-        linestyle : `~matplotlib.lines.Line2D` property, optional
+        linestyle : `.Line2D` property, optional
             Only used if usevlines is ``False``.
 
         marker : string, optional
@@ -6685,11 +6687,11 @@ def psd(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
 
         %(PSD)s
 
-        noverlap : integer
+        noverlap : int
             The number of points of overlap between segments.
             The default value is 0 (no overlap).
 
-        Fc : integer
+        Fc : int
             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
@@ -6703,10 +6705,10 @@ def psd(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
         -------
         Pxx : 1-D array
             The values for the power spectrum `P_{xx}` before scaling
-            (real valued)
+            (real valued).
 
         freqs : 1-D array
-            The frequencies corresponding to the elements in *Pxx*
+            The frequencies corresponding to the elements in *Pxx*.
 
         line : a :class:`~matplotlib.lines.Line2D` instance
             The line created by this function.
@@ -6807,17 +6809,17 @@ def csd(self, x, y, NFFT=None, Fs=None, Fc=None, detrend=None,
         Parameters
         ----------
         x, y : 1-D arrays or sequences
-            Arrays or sequences containing the data
+            Arrays or sequences containing the data.
 
         %(Spectral)s
 
         %(PSD)s
 
-        noverlap : integer
+        noverlap : int
             The number of points of overlap between segments.
             The default value is 0 (no overlap).
 
-        Fc : integer
+        Fc : int
             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
@@ -6831,10 +6833,10 @@ def csd(self, x, y, NFFT=None, Fs=None, Fc=None, detrend=None,
         -------
         Pxy : 1-D array
             The values for the cross spectrum `P_{xy}` before scaling
-            (complex valued)
+            (complex valued).
 
         freqs : 1-D array
-            The frequencies corresponding to the elements in *Pxy*
+            The frequencies corresponding to the elements in *Pxy*.
 
         line : a :class:`~matplotlib.lines.Line2D` instance
             The line created by this function.
@@ -6913,18 +6915,18 @@ def magnitude_spectrum(self, x, Fs=None, Fc=None, window=None,
         Parameters
         ----------
         x : 1-D array or sequence
-            Array or sequence containing the data
+            Array or sequence containing the data.
 
         %(Spectral)s
 
         %(Single_Spectrum)s
 
-        scale : [ 'default' | 'linear' | 'dB' ]
+        scale : {'default', 'linear', 'dB'}
             The scaling of the values in the *spec*.  'linear' is no scaling.
             'dB' returns the values in dB scale, i.e., the dB amplitude
             (20 * log10). 'default' is 'linear'.
 
-        Fc : integer
+        Fc : int
             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
@@ -6933,13 +6935,13 @@ def magnitude_spectrum(self, x, Fs=None, Fc=None, window=None,
         Returns
         -------
         spectrum : 1-D array
-            The values for the magnitude spectrum before scaling (real valued)
+            The values for the magnitude spectrum before scaling (real valued).
 
         freqs : 1-D array
-            The frequencies corresponding to the elements in *spectrum*
+            The frequencies corresponding to the elements in *spectrum*.
 
         line : a :class:`~matplotlib.lines.Line2D` instance
-            The line created by this function
+            The line created by this function.
 
         Other Parameters
         ----------------
@@ -7018,13 +7020,13 @@ def angle_spectrum(self, x, Fs=None, Fc=None, window=None,
         Parameters
         ----------
         x : 1-D array or sequence
-            Array or sequence containing the data
+            Array or sequence containing the data.
 
         %(Spectral)s
 
         %(Single_Spectrum)s
 
-        Fc : integer
+        Fc : int
             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
@@ -7033,13 +7035,13 @@ def angle_spectrum(self, x, Fs=None, Fc=None, window=None,
         Returns
         -------
         spectrum : 1-D array
-            The values for the angle spectrum in radians (real valued)
+            The values for the angle spectrum in radians (real valued).
 
         freqs : 1-D array
-            The frequencies corresponding to the elements in *spectrum*
+            The frequencies corresponding to the elements in *spectrum*.
 
         line : a :class:`~matplotlib.lines.Line2D` instance
-            The line created by this function
+            The line created by this function.
 
         Other Parameters
         ----------------
@@ -7109,7 +7111,7 @@ def phase_spectrum(self, x, Fs=None, Fc=None, window=None,
 
         %(Single_Spectrum)s
 
-        Fc : integer
+        Fc : int
             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
@@ -7118,13 +7120,13 @@ def phase_spectrum(self, x, Fs=None, Fc=None, window=None,
         Returns
         -------
         spectrum : 1-D array
-            The values for the phase spectrum in radians (real valued)
+            The values for the phase spectrum in radians (real valued).
 
         freqs : 1-D array
-            The frequencies corresponding to the elements in *spectrum*
+            The frequencies corresponding to the elements in *spectrum*.
 
         line : a :class:`~matplotlib.lines.Line2D` instance
-            The line created by this function
+            The line created by this function.
 
         Other Parameters
         ----------------
@@ -7189,11 +7191,11 @@ def cohere(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
 
         %(PSD)s
 
-        noverlap : integer
+        noverlap : int
             The number of points of overlap between blocks.  The
             default value is 0 (no overlap).
 
-        Fc : integer
+        Fc : int
             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
@@ -7202,10 +7204,11 @@ def cohere(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
 
         Returns
         -------
-        The return value is a tuple (*Cxy*, *f*), where *f* are the
-        frequencies of the coherence vector.
+        Cxy : 1-D array
+            The coherence vector.
 
-        kwargs are applied to the lines.
+        freqs : 1-D array
+            The frequencies for the elements in *Cxy*.
 
         Other Parameters
         ----------------
@@ -7268,26 +7271,26 @@ def specgram(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
 
         %(PSD)s
 
-        mode : [ 'default' | 'psd' | 'magnitude' | 'angle' | 'phase' ]
+        mode : {'default', 'psd', 'magnitude', 'angle', 'phase'}
             What sort of spectrum to use.  Default is 'psd', which takes
             the power spectral density.  'complex' returns the complex-valued
             frequency spectrum.  'magnitude' returns the magnitude spectrum.
             'angle' returns the phase spectrum without unwrapping.  'phase'
             returns the phase spectrum with unwrapping.
 
-        noverlap : integer
+        noverlap : int
             The number of points of overlap between blocks.  The
             default value is 128.
 
-        scale : [ 'default' | 'linear' | 'dB' ]
+        scale : {'default', 'linear', 'dB'}
             The scaling of the values in the *spec*.  'linear' is no scaling.
             'dB' returns the values in dB scale.  When *mode* is 'psd',
             this is dB power (10 * log10).  Otherwise this is dB amplitude
             (20 * log10). 'default' is 'dB' if *mode* is 'psd' or
             'magnitude' and 'linear' otherwise.  This must be 'linear'
             if *mode* is 'angle' or 'phase'.
 
-        Fc : integer
+        Fc : int
             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
@@ -7297,15 +7300,15 @@ def specgram(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
             A :class:`matplotlib.colors.Colormap` instance; if *None*, use
             default determined by rc
 
-        xextent : [None | (xmin, xmax)]
+        xextent : *None* or (xmin, xmax)
             The image extent along the x-axis. The default sets *xmin* to the
             left border of the first bin (*spectrum* column) and *xmax* to the
             right border of the last bin. Note that for *noverlap>0* the width
             of the bins is smaller than those of the segments.
 
         **kwargs :
             Additional kwargs are passed on to imshow which makes the
-            specgram image
+            specgram image.
 
         Returns
         -------

lib/matplotlib/mlab.py

@@ -810,7 +810,7 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None,
         argument, it must take a data segment as an argument and
         return the windowed version of the segment.
 
-    sides : [ 'default' | 'onesided' | 'twosided' ]
+    sides : {'default', 'onesided', 'twosided'}
         Specifies which sides of the spectrum to return.  Default gives the
         default behavior, which returns one-sided for real data and both
         for complex data.  'onesided' forces the return of a one-sided
@@ -819,7 +819,7 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None,
 
 
 docstring.interpd.update(Single_Spectrum=cbook.dedent("""
-    pad_to : integer
+    pad_to : int
         The number of points to which the data segment is padded when
         performing the FFT.  While not increasing the actual resolution of
         the spectrum (the minimum distance between resolvable peaks),
@@ -831,7 +831,7 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None,
 
 
 docstring.interpd.update(PSD=cbook.dedent("""
-    pad_to : integer
+    pad_to : int
         The number of points to which the data segment is padded when
         performing the FFT.  This can be different from *NFFT*, which
         specifies the number of data points used.  While not increasing
@@ -841,7 +841,7 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None,
         in the call to fft(). The default is None, which sets *pad_to*
         equal to *NFFT*
 
-    NFFT : integer
+    NFFT : int
         The number of data points used in each block for the FFT.
         A power 2 is most efficient.  The default value is 256.
         This should *NOT* be used to get zero padding, or the scaling of the
@@ -861,7 +861,7 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None,
         :func:`~matplotlib.pylab.detrend_linear`.  'none' calls
         :func:`~matplotlib.pylab.detrend_none`.
 
-    scale_by_freq : boolean, optional
+    scale_by_freq : bool, optional
         Specifies whether the resulting density values should be scaled
         by the scaling frequency, which gives density in units of Hz^-1.
         This allows for integration over the returned frequency values.