From a226f82365802124f95a3f610473c80a8229b848 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Tue, 19 Nov 2019 00:19:10 +0100 Subject: [PATCH] Templatize spectral helpers. I think the repetition is large enough to be worth it. This does make these functions all refer to themselves as well in the See Also section, but that seems benign enough. --- lib/matplotlib/mlab.py | 219 +++++++++++------------------------------ 1 file changed, 57 insertions(+), 162 deletions(-) diff --git a/lib/matplotlib/mlab.py b/lib/matplotlib/mlab.py index ad54e94231a9..a361f2a3cf77 100644 --- a/lib/matplotlib/mlab.py +++ b/lib/matplotlib/mlab.py @@ -54,6 +54,7 @@ """ import csv +import functools from numbers import Number import numpy as np @@ -584,13 +585,13 @@ def _spectral_helper(x, y=None, NFFT=None, Fs=None, detrend_func=None, return result, freqs, t -def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None, - sides=None): - ''' +def _single_spectrum_helper( + mode, x, Fs=None, window=None, pad_to=None, sides=None): + """ This is a helper function that implements the commonality between the complex, magnitude, angle, and phase spectrums. It is *NOT* meant to be used outside of mlab and may change at any time. - ''' + """ cbook._check_in_list(['complex', 'magnitude', 'angle', 'phase'], mode=mode) if pad_to is None: @@ -792,166 +793,60 @@ def csd(x, y, NFFT=None, Fs=None, detrend=None, window=None, return Pxy, freqs -@docstring.dedent_interpd -def 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 - ---------- - x : 1-D array or sequence - Array or sequence containing the data - - %(Spectral)s - - %(Single_Spectrum)s - - Returns - ------- - spectrum : 1-D array - The values for the complex spectrum (complex valued) - - freqs : 1-D array - The frequencies corresponding to the elements in *spectrum* - - See Also - -------- - magnitude_spectrum - Returns the absolute value of this function. - angle_spectrum - Returns the angle of this function. - phase_spectrum - Returns the phase (unwrapped angle) of this function. - specgram - Can return the complex spectrum of segments within the signal. - """ - return _single_spectrum_helper(x=x, Fs=Fs, window=window, pad_to=pad_to, - sides=sides, mode='complex') - - -@docstring.dedent_interpd -def 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 - ---------- - x : 1-D array or sequence - Array or sequence containing the data - - %(Spectral)s - - %(Single_Spectrum)s - - Returns - ------- - spectrum : 1-D array - The values for the magnitude spectrum (real valued) - - freqs : 1-D array - The frequencies corresponding to the elements in *spectrum* - - See Also - -------- - psd - Returns the power spectral density. - complex_spectrum - This function returns the absolute value of `complex_spectrum`. - angle_spectrum - Returns the angles of the corresponding frequencies. - phase_spectrum - Returns the phase (unwrapped angle) of the corresponding frequencies. - specgram - Can return the complex spectrum of segments within the signal. - """ - return _single_spectrum_helper(x=x, Fs=Fs, window=window, pad_to=pad_to, - sides=sides, mode='magnitude') - - -@docstring.dedent_interpd -def 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 - ---------- - x : 1-D array or sequence - Array or sequence containing the data - - %(Spectral)s - - %(Single_Spectrum)s - - Returns - ------- - spectrum : 1-D array - The values for the angle spectrum in radians (real valued) - - freqs : 1-D array - The frequencies corresponding to the elements in *spectrum* - - See Also - -------- - complex_spectrum - This function returns the angle value of `complex_spectrum`. - magnitude_spectrum - Returns the magnitudes of the corresponding frequencies. - phase_spectrum - Returns the phase (unwrapped angle) of the corresponding frequencies. - specgram - Can return the complex spectrum of segments within the signal. - """ - return _single_spectrum_helper(x=x, Fs=Fs, window=window, pad_to=pad_to, - sides=sides, mode='angle') - - -@docstring.dedent_interpd -def phase_spectrum(x, Fs=None, window=None, pad_to=None, - sides=None): - """ - Compute the phase of the frequency spectrum (unwrapped angle spectrum) of - *x*. Data is padded to a length of *pad_to* and the windowing function - *window* is applied to the signal. - - Parameters - ---------- - x : 1-D array or sequence - Array or sequence containing the data - - %(Spectral)s - - %(Single_Spectrum)s +_single_spectrum_docs = """\ +Compute the {quantity} of *x*. +Data is padded to a length of *pad_to* and the windowing function *window* is +applied to the signal. + +Parameters +---------- +x : 1-D array or sequence + Array or sequence containing the data + +{Spectral} + +{Single_Spectrum} + +Returns +------- +spectrum : 1-D array + The {quantity}. +freqs : 1-D array + The frequencies corresponding to the elements in *spectrum*. + +See Also +-------- +psd + Returns the power spectral density. +complex_spectrum + Returns the complex-valued frequency spectrum. +magnitude_spectrum + Returns the absolute value of the `complex_spectrum`. +angle_spectrum + Returns the angle of the `complex_spectrum`. +phase_spectrum + Returns the phase (unwrapped angle) of the `complex_spectrum`. +specgram + Can return the complex spectrum of segments within the signal. +""" - Returns - ------- - spectrum : 1-D array - The values for the phase spectrum in radians (real valued) - freqs : 1-D array - The frequencies corresponding to the elements in *spectrum* - - See Also - -------- - complex_spectrum - This function returns the phase value of `complex_spectrum`. - magnitude_spectrum - Returns the magnitudes of the corresponding frequencies. - angle_spectrum - Returns the angle (wrapped phase) of the corresponding frequencies. - specgram - Can return the complex spectrum of segments within the signal. - """ - return _single_spectrum_helper(x=x, Fs=Fs, window=window, pad_to=pad_to, - sides=sides, mode='phase') +complex_spectrum = functools.partial(_single_spectrum_helper, "complex") +complex_spectrum.__doc__ = _single_spectrum_docs.format( + quantity="complex-valued frequency spectrum", + **docstring.interpd.params) +magnitude_spectrum = functools.partial(_single_spectrum_helper, "magnitude") +magnitude_spectrum.__doc__ = _single_spectrum_docs.format( + quantity="magnitude (absolute value) of the frequency spectrum", + **docstring.interpd.params) +angle_spectrum = functools.partial(_single_spectrum_helper, "angle") +angle_spectrum.__doc__ = _single_spectrum_docs.format( + quantity="angle of the frequency spectrum (wrapped phase spectrum)", + **docstring.interpd.params) +phase_spectrum = functools.partial(_single_spectrum_helper, "phase") +phase_spectrum.__doc__ = _single_spectrum_docs.format( + quantity="phase of the frequency spectrum (unwrapped phase spectrum)", + **docstring.interpd.params) @docstring.dedent_interpd