matplotlib.mlab — Matplotlib 3.10.1 documentation (original) (raw)
Numerical Python functions written for compatibility with MATLAB commands with the same names. Most numerical Python functions can be found in the NumPy and SciPy libraries. What remains here is code for performing spectral computations and kernel density estimations.
Spectral functions#
Coherence (normalized cross spectral density)
Cross spectral density using Welch's average periodogram
Remove the mean or best fit line from an array
Power spectral density using Welch's average periodogram
Spectrogram (spectrum over segments of time)
Return the complex-valued frequency spectrum of a signal
Return the magnitude of the frequency spectrum of a signal
Return the angle (wrapped phase) of the frequency spectrum of a signal
Return the phase (unwrapped angle) of the frequency spectrum of a signal
Remove the mean from a line.
Remove the best fit line from a line.
Return the original line.
class matplotlib.mlab.GaussianKDE(dataset, bw_method=None)[source]#
Bases: object
Representation of a kernel-density estimate using Gaussian kernels.
Parameters:
datasetarray-like
Datapoints to estimate from. In case of univariate data this is a 1-D array, otherwise a 2D array with shape (# of dims, # of data).
bw_method{'scott', 'silverman'} or float or callable, optional
The method used to calculate the estimator bandwidth. If a float, this will be used directly as kde.factor. If a callable, it should take a GaussianKDE instance as only parameter and return a float. If None (default), 'scott' is used.
Attributes:
datasetndarray
The dataset passed to the constructor.
dimint
Number of dimensions.
num_dpint
Number of datapoints.
factorfloat
The bandwidth factor, obtained from kde.covariance_factor, with which the covariance matrix is multiplied.
covariancendarray
The covariance matrix of dataset, scaled by the calculated bandwidth (kde.factor).
inv_covndarray
The inverse of covariance.
Methods
Evaluate the estimated pdf on a set of points.
Parameters:
points(# of dimensions, # of points)-array
Alternatively, a (# of dimensions,) vector can be passed in and treated as a single point.
Returns:
(# of points,)-array
The values at each point.
Raises:
ValueErrorif the dimensionality of the input points is different
than the dimensionality of the KDE.
matplotlib.mlab.angle_spectrum(x, Fs=None, window=None, pad_to=None, sides=None)#
Compute the angle of the frequency spectrum (wrapped phase spectrum) of x. Data is padded to a length of pad_to and the windowing function window is applied to the signal.
Parameters:
x1-D array or sequence
Array or sequence containing the data
Fsfloat, default: 2
The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time unit.
windowcallable or ndarray, default: window_hanning
A function or a vector of length NFFT. To create window vectors seewindow_hanning, window_none, numpy.blackman, numpy.hamming,numpy.bartlett, scipy.signal, scipy.signal.get_window, etc. 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.
sides{'default', 'onesided', 'twosided'}, optional
Which sides of the spectrum to return. 'default' is one-sided for real data and two-sided for complex data. 'onesided' forces the return of a one-sided spectrum, while 'twosided' forces two-sided.
pad_toint, optional
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), 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 the length of the input signal (i.e. no padding).
Returns:
spectrum1-D array
The angle of the frequency spectrum (wrapped phase spectrum).
freqs1-D array
The frequencies corresponding to the elements in spectrum.
See also
Returns the power spectral density.
Returns the complex-valued frequency spectrum.
Returns the absolute value of the complex_spectrum.
Returns the angle of the complex_spectrum.
Returns the phase (unwrapped angle) of the complex_spectrum.
Can return the complex spectrum of segments within the signal.
matplotlib.mlab.cohere(x, y, NFFT=256, Fs=2, detrend=<function detrend_none>, window=<function window_hanning>, noverlap=0, pad_to=None, sides='default', scale_by_freq=None)[source]#
The coherence between x and y. Coherence is the normalized cross spectral density:
\[C_{xy} = \frac{|P_{xy}|^2}{P_{xx}P_{yy}}\]
Parameters:
x, y
Array or sequence containing the data
Fsfloat, default: 2
The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time unit.
windowcallable or ndarray, default: window_hanning
A function or a vector of length NFFT. To create window vectors seewindow_hanning, window_none, numpy.blackman, numpy.hamming,numpy.bartlett, scipy.signal, scipy.signal.get_window, etc. 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.
sides{'default', 'onesided', 'twosided'}, optional
Which sides of the spectrum to return. 'default' is one-sided for real data and two-sided for complex data. 'onesided' forces the return of a one-sided spectrum, while 'twosided' forces two-sided.
pad_toint, optional
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 the actual resolution of the spectrum (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
NFFTint, default: 256
The number of data points used in each block for the FFT. A power 2 is most efficient. This should NOT be used to get zero padding, or the scaling of the result will be incorrect; use pad_to for this instead.
detrend{'none', 'mean', 'linear'} or callable, default: 'none'
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 it is a function. The mlabmodule defines detrend_none, detrend_mean, and detrend_linear, but you can use a custom function as well. You can also use a string to choose one of the functions: 'none' calls detrend_none. 'mean' callsdetrend_mean. 'linear' calls detrend_linear.
scale_by_freqbool, default: True
Whether the resulting density values should be scaled by the scaling frequency, which gives density in units of 1/Hz. This allows for integration over the returned frequency values. The default is True for MATLAB compatibility.
noverlapint, default: 0 (no overlap)
The number of points of overlap between segments.
Returns:
Cxy1-D array
The coherence vector.
freqs1-D array
The frequencies for the elements in Cxy.
See also
For information about the methods used to compute \(P_{xy}\), \(P_{xx}\) and \(P_{yy}\).
matplotlib.mlab.complex_spectrum(x, Fs=None, window=None, pad_to=None, sides=None)#
Compute the complex-valued frequency spectrum of x. Data is padded to a length of pad_to and the windowing function window is applied to the signal.
Parameters:
x1-D array or sequence
Array or sequence containing the data
Fsfloat, default: 2
The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time unit.
windowcallable or ndarray, default: window_hanning
A function or a vector of length NFFT. To create window vectors seewindow_hanning, window_none, numpy.blackman, numpy.hamming,numpy.bartlett, scipy.signal, scipy.signal.get_window, etc. 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.
sides{'default', 'onesided', 'twosided'}, optional
Which sides of the spectrum to return. 'default' is one-sided for real data and two-sided for complex data. 'onesided' forces the return of a one-sided spectrum, while 'twosided' forces two-sided.
pad_toint, optional
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), 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 the length of the input signal (i.e. no padding).
Returns:
spectrum1-D array
The complex-valued frequency spectrum.
freqs1-D array
The frequencies corresponding to the elements in spectrum.
See also
Returns the power spectral density.
Returns the complex-valued frequency spectrum.
Returns the absolute value of the complex_spectrum.
Returns the angle of the complex_spectrum.
Returns the phase (unwrapped angle) of the complex_spectrum.
Can return the complex spectrum of segments within the signal.
matplotlib.mlab.csd(x, y, NFFT=None, Fs=None, detrend=None, window=None, noverlap=None, pad_to=None, sides=None, scale_by_freq=None)[source]#
Compute the cross-spectral density.
The cross spectral density \(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. noverlap gives the length of the overlap between segments. The product of the direct FFTs of x and y are averaged over each segment to compute \(P_{xy}\), with a scaling to correct for power loss due to windowing.
If len(x) < NFFT or len(y) < NFFT, they will be zero padded to NFFT.
Parameters:
x, y1-D arrays or sequences
Arrays or sequences containing the data
Fsfloat, default: 2
The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time unit.
windowcallable or ndarray, default: window_hanning
A function or a vector of length NFFT. To create window vectors seewindow_hanning, window_none, numpy.blackman, numpy.hamming,numpy.bartlett, scipy.signal, scipy.signal.get_window, etc. 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.
sides{'default', 'onesided', 'twosided'}, optional
Which sides of the spectrum to return. 'default' is one-sided for real data and two-sided for complex data. 'onesided' forces the return of a one-sided spectrum, while 'twosided' forces two-sided.
pad_toint, optional
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 the actual resolution of the spectrum (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
NFFTint, default: 256
The number of data points used in each block for the FFT. A power 2 is most efficient. This should NOT be used to get zero padding, or the scaling of the result will be incorrect; use pad_to for this instead.
detrend{'none', 'mean', 'linear'} or callable, default: 'none'
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 it is a function. The mlabmodule defines detrend_none, detrend_mean, and detrend_linear, but you can use a custom function as well. You can also use a string to choose one of the functions: 'none' calls detrend_none. 'mean' callsdetrend_mean. 'linear' calls detrend_linear.
scale_by_freqbool, default: True
Whether the resulting density values should be scaled by the scaling frequency, which gives density in units of 1/Hz. This allows for integration over the returned frequency values. The default is True for MATLAB compatibility.
noverlapint, default: 0 (no overlap)
The number of points of overlap between segments.
Returns:
Pxy1-D array
The values for the cross spectrum \(P_{xy}\) before scaling (real valued)
freqs1-D array
The frequencies corresponding to the elements in Pxy
See also
equivalent to setting y = x.
References
Bendat & Piersol -- Random Data: Analysis and Measurement Procedures, John Wiley & Sons (1986)
matplotlib.mlab.detrend(x, key=None, axis=None)[source]#
Return x with its trend removed.
Parameters:
xarray or sequence
Array or sequence containing the data.
key{'default', 'constant', 'mean', 'linear', 'none'} or function
The detrending algorithm to use. 'default', 'mean', and 'constant' are the same as detrend_mean. 'linear' is the same as detrend_linear. 'none' is the same as detrend_none. The default is 'mean'. See the corresponding functions for more details regarding the algorithms. Can also be a function that carries out the detrend operation.
axisint
The axis along which to do the detrending.
See also
Implementation of the 'mean' algorithm.
Implementation of the 'linear' algorithm.
Implementation of the 'none' algorithm.
matplotlib.mlab.detrend_linear(y)[source]#
Return x minus best fit line; 'linear' detrending.
Parameters:
y0-D or 1-D array or sequence
Array or sequence containing the data
See also
Another detrend algorithm.
Another detrend algorithm.
A wrapper around all the detrend algorithms.
matplotlib.mlab.detrend_mean(x, axis=None)[source]#
Return x minus the mean(x).
Parameters:
xarray or sequence
Array or sequence containing the data Can have any dimensionality
axisint
The axis along which to take the mean. See numpy.mean for a description of this argument.
See also
Another detrend algorithm.
Another detrend algorithm.
A wrapper around all the detrend algorithms.
matplotlib.mlab.detrend_none(x, axis=None)[source]#
Return x: no detrending.
Parameters:
xany object
An object containing the data
axisint
This parameter is ignored. It is included for compatibility with detrend_mean
See also
Another detrend algorithm.
Another detrend algorithm.
A wrapper around all the detrend algorithms.
matplotlib.mlab.magnitude_spectrum(x, Fs=None, window=None, pad_to=None, sides=None)#
Compute the magnitude (absolute value) of the frequency spectrum of x. Data is padded to a length of pad_to and the windowing function window is applied to the signal.
Parameters:
x1-D array or sequence
Array or sequence containing the data
Fsfloat, default: 2
The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time unit.
windowcallable or ndarray, default: window_hanning
A function or a vector of length NFFT. To create window vectors seewindow_hanning, window_none, numpy.blackman, numpy.hamming,numpy.bartlett, scipy.signal, scipy.signal.get_window, etc. 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.
sides{'default', 'onesided', 'twosided'}, optional
Which sides of the spectrum to return. 'default' is one-sided for real data and two-sided for complex data. 'onesided' forces the return of a one-sided spectrum, while 'twosided' forces two-sided.
pad_toint, optional
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), 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 the length of the input signal (i.e. no padding).
Returns:
spectrum1-D array
The magnitude (absolute value) of the frequency spectrum.
freqs1-D array
The frequencies corresponding to the elements in spectrum.
See also
Returns the power spectral density.
Returns the complex-valued frequency spectrum.
Returns the absolute value of the complex_spectrum.
Returns the angle of the complex_spectrum.
Returns the phase (unwrapped angle) of the complex_spectrum.
Can return the complex spectrum of segments within the signal.
matplotlib.mlab.phase_spectrum(x, Fs=None, window=None, pad_to=None, sides=None)#
Compute the phase of the frequency spectrum (unwrapped phase spectrum) of x. Data is padded to a length of pad_to and the windowing function window is applied to the signal.
Parameters:
x1-D array or sequence
Array or sequence containing the data
Fsfloat, default: 2
The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time unit.
windowcallable or ndarray, default: window_hanning
A function or a vector of length NFFT. To create window vectors seewindow_hanning, window_none, numpy.blackman, numpy.hamming,numpy.bartlett, scipy.signal, scipy.signal.get_window, etc. 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.
sides{'default', 'onesided', 'twosided'}, optional
Which sides of the spectrum to return. 'default' is one-sided for real data and two-sided for complex data. 'onesided' forces the return of a one-sided spectrum, while 'twosided' forces two-sided.
pad_toint, optional
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), 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 the length of the input signal (i.e. no padding).
Returns:
spectrum1-D array
The phase of the frequency spectrum (unwrapped phase spectrum).
freqs1-D array
The frequencies corresponding to the elements in spectrum.
See also
Returns the power spectral density.
Returns the complex-valued frequency spectrum.
Returns the absolute value of the complex_spectrum.
Returns the angle of the complex_spectrum.
Returns the phase (unwrapped angle) of the complex_spectrum.
Can return the complex spectrum of segments within the signal.
matplotlib.mlab.psd(x, NFFT=None, Fs=None, detrend=None, window=None, noverlap=None, pad_to=None, sides=None, scale_by_freq=None)[source]#
Compute the power spectral density.
The power spectral density \(P_{xx}\) 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 the overlap between segments. The \(|\mathrm{fft}(i)|^2\)of each segment \(i\) are averaged to compute \(P_{xx}\).
If len(x) < NFFT, it will be zero padded to NFFT.
Parameters:
x1-D array or sequence
Array or sequence containing the data
Fsfloat, default: 2
The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time unit.
windowcallable or ndarray, default: window_hanning
A function or a vector of length NFFT. To create window vectors seewindow_hanning, window_none, numpy.blackman, numpy.hamming,numpy.bartlett, scipy.signal, scipy.signal.get_window, etc. 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.
sides{'default', 'onesided', 'twosided'}, optional
Which sides of the spectrum to return. 'default' is one-sided for real data and two-sided for complex data. 'onesided' forces the return of a one-sided spectrum, while 'twosided' forces two-sided.
pad_toint, optional
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 the actual resolution of the spectrum (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
NFFTint, default: 256
The number of data points used in each block for the FFT. A power 2 is most efficient. This should NOT be used to get zero padding, or the scaling of the result will be incorrect; use pad_to for this instead.
detrend{'none', 'mean', 'linear'} or callable, default: 'none'
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 it is a function. The mlabmodule defines detrend_none, detrend_mean, and detrend_linear, but you can use a custom function as well. You can also use a string to choose one of the functions: 'none' calls detrend_none. 'mean' callsdetrend_mean. 'linear' calls detrend_linear.
scale_by_freqbool, default: True
Whether the resulting density values should be scaled by the scaling frequency, which gives density in units of 1/Hz. This allows for integration over the returned frequency values. The default is True for MATLAB compatibility.
noverlapint, default: 0 (no overlap)
The number of points of overlap between segments.
Returns:
Pxx1-D array
The values for the power spectrum \(P_{xx}\) (real valued)
freqs1-D array
The frequencies corresponding to the elements in Pxx
See also
specgram differs in the default overlap; in not returning the mean of the segment periodograms; and in returning the times of the segments.
returns the magnitude spectrum.
returns the spectral density between two signals.
References
Bendat & Piersol -- Random Data: Analysis and Measurement Procedures, John Wiley & Sons (1986)
matplotlib.mlab.specgram(x, NFFT=None, Fs=None, detrend=None, window=None, noverlap=None, pad_to=None, sides=None, scale_by_freq=None, mode=None)[source]#
Compute a spectrogram.
Compute and plot a spectrogram of data in x. Data are split into_NFFT_ length segments and the spectrum of each section is computed. The windowing function window is applied to each segment, and the amount of overlap of each segment is specified with noverlap.
Parameters:
xarray-like
1-D array or sequence.
Fsfloat, default: 2
The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time unit.
windowcallable or ndarray, default: window_hanning
A function or a vector of length NFFT. To create window vectors seewindow_hanning, window_none, numpy.blackman, numpy.hamming,numpy.bartlett, scipy.signal, scipy.signal.get_window, etc. 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.
sides{'default', 'onesided', 'twosided'}, optional
Which sides of the spectrum to return. 'default' is one-sided for real data and two-sided for complex data. 'onesided' forces the return of a one-sided spectrum, while 'twosided' forces two-sided.
pad_toint, optional
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 the actual resolution of the spectrum (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
NFFTint, default: 256
The number of data points used in each block for the FFT. A power 2 is most efficient. This should NOT be used to get zero padding, or the scaling of the result will be incorrect; use pad_to for this instead.
detrend{'none', 'mean', 'linear'} or callable, default: 'none'
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 it is a function. The mlabmodule defines detrend_none, detrend_mean, and detrend_linear, but you can use a custom function as well. You can also use a string to choose one of the functions: 'none' calls detrend_none. 'mean' callsdetrend_mean. 'linear' calls detrend_linear.
scale_by_freqbool, default: True
Whether the resulting density values should be scaled by the scaling frequency, which gives density in units of 1/Hz. This allows for integration over the returned frequency values. The default is True for MATLAB compatibility.
noverlapint, default: 128
The number of points of overlap between blocks.
modestr, default: 'psd'
What sort of spectrum to use:
'psd'
Returns 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.
Returns:
spectrumarray-like
2D array, columns are the periodograms of successive segments.
freqsarray-like
1-D array, frequencies corresponding to the rows in spectrum.
tarray-like
1-D array, the times corresponding to midpoints of segments (i.e the columns in spectrum).
See also
differs in the overlap and in the return values.
similar, but with complex valued frequencies.
similar single segment when mode is 'magnitude'.
similar to single segment when mode is 'angle'.
similar to single segment when mode is 'phase'.
Notes
detrend and scale_by_freq only apply when mode is set to 'psd'.
matplotlib.mlab.window_hanning(x)[source]#
Return x times the Hanning (or Hann) window of len(x).
See also
Another window algorithm.
matplotlib.mlab.window_none(x)[source]#
No window function; simply return x.
See also
Another window algorithm.