Skip to content

Minor docstring updates on spectral plot functions #10834

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 21, 2018
Merged

Minor docstring updates on spectral plot functions #10834

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 43 additions & 40 deletions lib/matplotlib/axes/_axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
-----
Expand All @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I can't run the tests anymore because of this math call. (SyntaxError: invalid escape sequence \s). What do I do to not get this to happen?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

my bad, see #10877

conjugate of :math:`y`.

Parameters
----------
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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
----------------
Expand Down Expand Up @@ -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
Expand All @@ -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
----------------
Expand Down Expand Up @@ -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
Expand All @@ -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
----------------
Expand Down Expand Up @@ -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
Expand All @@ -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
----------------
Expand Down Expand Up @@ -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
Expand All @@ -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
-------
Expand Down
10 changes: 5 additions & 5 deletions lib/matplotlib/mlab.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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),
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.
Expand Down