Short-Time Fourier Transforms#

sails.stft.periodogram(x, average='mean', nperseg=None, noverlap=None, window_type='hann', detrend='constant', nfft=None, axis=-1, return_onesided=True, mode='psd', scaling='density', fs=1.0, fmin=None, fmax=None, return_config=False, verbose=None)[source]#

Compute Periodogram by averaging across windows in a STFT.

Parameters:

x (array_like) – Time series of measurement values
average ({ 'mean', 'median', 'median_bias' }, optional) – Method to use when averaging periodograms. Defaults to ‘mean’.
nperseg (int) – Length of each segment. Defaults to None, but if window is str or tuple, is set to 256, and if window is array_like, is set to the length of the window.
noverlap (int) – Number of samples that successive sliding windows should overlap.
window_type (str or tuple or array_like, optional) – Desired window to use. If window is a string or tuple, it is passed to scipy.signal.windows.get_window to generate the window values, which are DFT-even by default. See scipy.signal.windows for a list of windows and required parameters. If window is array_like it will be used directly as the window and its length must be nperseg. Defaults to a Hann window.
detrend (str or function or False, optional) – Specifies how to detrend each segment. If detrend is a string, it is passed as the type argument to the detrend function. If it is a function, it takes a segment and returns a detrended segment. If detrend is False, no detrending is done. Defaults to ‘constant’.’
nfft (int) – Length of the FFT to use (Default value = 256)
axis (int) – Axis of input array along which the computation is performed. (Default value = -1)
return_onesided (bool, optional) – If True, return a one-sided spectrum for real data. If False return a two-sided spectrum. Defaults to True, but for complex data, a two-sided spectrum is always returned.
mode ({'psd', 'magnitude', 'angle', 'phase', 'complex'}) – Which type of spectrum to return (Default value = ‘psd’)
scaling ({ 'density', 'spectrum' }) – Selects between computing the power spectral density (‘density’) where Pxx has units of V**2/Hz and computing the power spectrum (‘spectrum’) where Pxx has units of V**2, if x is measured in V and fs is measured in Hz. Defaults to ‘density’
fs (float) – Sampling rate of the data
fmin ({float, None}) – Smallest frequency in desired range (left hand boundary)
fmax ({float, None}) – Largest frequency in desired range (right hand boundary)’
return_config (bool) – Indicate whether parameter configuration object should be returned alongside result (Default value = False)
verbose ({None, 'DEBUG', 'INFO', 'WARNING', 'CRITICAL'}) – String indicating the level of detail to be printed to the screen during computation.’

Returns:

freqs (ndarray) – Array of sample frequencies.
t (ndarray) – Array of times corresponding to each data segment
result (ndarray) – Array of output data, contents dependent on mode kwarg.
config (PeriodogramConfig, optional) – Configuration object containing all parameters used to compute spectrum, optionally returned based on value of return_config.

sails.stft.sw_periodogram(x, nperseg=None, noverlap=None, window_type='hann', detrend='constant', nfft=None, axis=-1, return_onesided=True, mode='psd', scaling='density', fs=1.0, fmin=None, fmax=None, return_config=False, verbose=None)[source]#

Compute Periodogram by averaging across windows in a STFT.

Parameters:

x (array_like) – Time series of measurement values
nperseg (int) – Length of each segment. Defaults to None, but if window is str or tuple, is set to 256, and if window is array_like, is set to the length of the window.
noverlap (int) – Number of samples that successive sliding windows should overlap.
window_type (str or tuple or array_like, optional) – Desired window to use. If window is a string or tuple, it is passed to scipy.signal.windows.get_window to generate the window values, which are DFT-even by default. See scipy.signal.windows for a list of windows and required parameters. If window is array_like it will be used directly as the window and its length must be nperseg. Defaults to a Hann window.
detrend (str or function or False, optional) – Specifies how to detrend each segment. If detrend is a string, it is passed as the type argument to the detrend function. If it is a function, it takes a segment and returns a detrended segment. If detrend is False, no detrending is done. Defaults to ‘constant’.’
nfft (int) – Length of the FFT to use (Default value = 256)
axis (int) – Axis of input array along which the computation is performed. (Default value = -1)
return_onesided (bool, optional) – If True, return a one-sided spectrum for real data. If False return a two-sided spectrum. Defaults to True, but for complex data, a two-sided spectrum is always returned.
mode ({'psd', 'magnitude', 'angle', 'phase', 'complex'}) – Which type of spectrum to return (Default value = ‘psd’)
scaling ({ 'density', 'spectrum' }) – Selects between computing the power spectral density (‘density’) where Pxx has units of V**2/Hz and computing the power spectrum (‘spectrum’) where Pxx has units of V**2, if x is measured in V and fs is measured in Hz. Defaults to ‘density’
fs (float) – Sampling rate of the data
fmin ({float, None}) – Smallest frequency in desired range (left hand boundary)
fmax ({float, None}) – Largest frequency in desired range (right hand boundary)’
return_config (bool) – Indicate whether parameter configuration object should be returned alongside result (Default value = False)
verbose ({None, 'DEBUG', 'INFO', 'WARNING', 'CRITICAL'}) – String indicating the level of detail to be printed to the screen during computation.’

Returns:

freqs (ndarray) – Array of sample frequencies.
t (ndarray) – Array of times corresponding to each data segment
result (ndarray) – Array of output data, contents dependent on mode kwarg.
config (PeriodogramConfig, optional) – Configuration object containing all parameters used to compute spectrum, optionally returned based on value of return_config.

sails.stft.multitaper(x, average='mean', num_tapers='auto', freq_resolution=1, time_bandwidth=5, apply_tapers='broadcast', nperseg=None, noverlap=None, window_type='hann', detrend='constant', nfft=None, axis=-1, return_onesided=True, mode='psd', scaling='density', fs=1.0, fmin=None, fmax=None, return_config=False, verbose=None)[source]#

Compute a multi-tapered power spectrum averaged across windows in a STFT.

Parameters:

x (array_like) – Time series of measurement values
average ({ 'mean', 'median', 'median_bias' }, optional) – Method to use when averaging periodograms. Defaults to ‘mean’.
num_tapers ({int, 'auto'}) – The number of tapers to use if set to an integer value, if set to ‘auto’ then the number of tapers is automatically computed from freq_resolution and time_bandwidth (Default value = ‘auto’)
freq_resolution (int) – Required frequency resolution of the tapers used if num_tapers is set to auto (Default value = 1)
time_bandwidth (int) – Required time bandwidth value of the tapers used if num_tapers is set to auto (Default value = 5)
apply_tapers ({'broadcast', 'loop}) – Flag indicating whether to compute each taper in one-shot by broadcasting or to iterate through each in a loop. Broadcasting is probably faster but more memory intensive. (Default value = ‘broadcast’)’
nperseg (int) – Length of each segment. Defaults to None, but if window is str or tuple, is set to 256, and if window is array_like, is set to the length of the window.
noverlap (int) – Number of samples that successive sliding windows should overlap.
window_type (str or tuple or array_like, optional) – Desired window to use. If window is a string or tuple, it is passed to scipy.signal.windows.get_window to generate the window values, which are DFT-even by default. See scipy.signal.windows for a list of windows and required parameters. If window is array_like it will be used directly as the window and its length must be nperseg. Defaults to a Hann window.
detrend (str or function or False, optional) – Specifies how to detrend each segment. If detrend is a string, it is passed as the type argument to the detrend function. If it is a function, it takes a segment and returns a detrended segment. If detrend is False, no detrending is done. Defaults to ‘constant’.’
nfft (int) – Length of the FFT to use (Default value = 256)
axis (int) – Axis of input array along which the computation is performed. (Default value = -1)
return_onesided (bool, optional) – If True, return a one-sided spectrum for real data. If False return a two-sided spectrum. Defaults to True, but for complex data, a two-sided spectrum is always returned.
mode ({'psd', 'magnitude', 'angle', 'phase', 'complex'}) – Which type of spectrum to return (Default value = ‘psd’)
scaling ({ 'density', 'spectrum' }) – Selects between computing the power spectral density (‘density’) where Pxx has units of V**2/Hz and computing the power spectrum (‘spectrum’) where Pxx has units of V**2, if x is measured in V and fs is measured in Hz. Defaults to ‘density’
fs (float) – Sampling rate of the data
fmin ({float, None}) – Smallest frequency in desired range (left hand boundary)
fmax ({float, None}) – Largest frequency in desired range (right hand boundary)’
return_config (bool) – Indicate whether parameter configuration object should be returned alongside result (Default value = False)
verbose ({None, 'DEBUG', 'INFO', 'WARNING', 'CRITICAL'}) – String indicating the level of detail to be printed to the screen during computation.’

Returns:

freqs (ndarray) – Array of sample frequencies.
t (ndarray) – Array of times corresponding to each data segment
result (ndarray) – Array of output data, contents dependent on mode kwarg.
config (MultiTaperConfig, optional) – Configuration object containing all parameters used to compute spectrum, optionally returned based on value of return_config.

sails.stft.sw_multitaper(x, num_tapers='auto', freq_resolution=1, time_bandwidth=5, apply_tapers='broadcast', nperseg=None, noverlap=None, window_type='hann', detrend='constant', nfft=None, axis=-1, return_onesided=True, mode='psd', scaling='density', fs=1.0, fmin=None, fmax=None, return_config=False, verbose=None)[source]#

Compute a multi-tapered power spectrum across windows in a STFT.

Parameters:

x (array_like) – Time series of measurement values
num_tapers ({int, 'auto'}) – The number of tapers to use if set to an integer value, if set to ‘auto’ then the number of tapers is automatically computed from freq_resolution and time_bandwidth (Default value = ‘auto’)
freq_resolution (int) – Required frequency resolution of the tapers used if num_tapers is set to auto (Default value = 1)
time_bandwidth (int) – Required time bandwidth value of the tapers used if num_tapers is set to auto (Default value = 5)
apply_tapers ({'broadcast', 'loop}) – Flag indicating whether to compute each taper in one-shot by broadcasting or to iterate through each in a loop. Broadcasting is probably faster but more memory intensive. (Default value = ‘broadcast’)’
nperseg (int) – Length of each segment. Defaults to None, but if window is str or tuple, is set to 256, and if window is array_like, is set to the length of the window.
noverlap (int) – Number of samples that successive sliding windows should overlap.
window_type (str or tuple or array_like, optional) – Desired window to use. If window is a string or tuple, it is passed to scipy.signal.windows.get_window to generate the window values, which are DFT-even by default. See scipy.signal.windows for a list of windows and required parameters. If window is array_like it will be used directly as the window and its length must be nperseg. Defaults to a Hann window.
detrend (str or function or False, optional) – Specifies how to detrend each segment. If detrend is a string, it is passed as the type argument to the detrend function. If it is a function, it takes a segment and returns a detrended segment. If detrend is False, no detrending is done. Defaults to ‘constant’.’
nfft (int) – Length of the FFT to use (Default value = 256)
axis (int) – Axis of input array along which the computation is performed. (Default value = -1)
return_onesided (bool, optional) – If True, return a one-sided spectrum for real data. If False return a two-sided spectrum. Defaults to True, but for complex data, a two-sided spectrum is always returned.
mode ({'psd', 'magnitude', 'angle', 'phase', 'complex'}) – Which type of spectrum to return (Default value = ‘psd’)
scaling ({ 'density', 'spectrum' }) – Selects between computing the power spectral density (‘density’) where Pxx has units of V**2/Hz and computing the power spectrum (‘spectrum’) where Pxx has units of V**2, if x is measured in V and fs is measured in Hz. Defaults to ‘density’
fs (float) – Sampling rate of the data
fmin ({float, None}) – Smallest frequency in desired range (left hand boundary)
fmax ({float, None}) – Largest frequency in desired range (right hand boundary)’
return_config (bool) – Indicate whether parameter configuration object should be returned alongside result (Default value = False)
verbose ({None, 'DEBUG', 'INFO', 'WARNING', 'CRITICAL'}) – String indicating the level of detail to be printed to the screen during computation.’

Returns:

freqs (ndarray) – Array of sample frequencies.
t (ndarray) – Array of times corresponding to each data segment
result (ndarray) – Array of output data, contents dependent on mode kwarg.
config (MultiTaperConfig, optional) – Configuration object containing all parameters used to compute spectrum, optionally returned based on value of return_config.

sails.stft.glm_periodogram(X, reg_categorical=None, reg_ztrans=None, reg_unitmax=None, contrasts=None, fit_method='pinv', fit_intercept=True, nperseg=None, noverlap=None, window_type='hann', detrend='constant', nfft=None, axis=-1, return_onesided=True, mode='psd', scaling='density', fs=1.0, fmin=None, fmax=None, verbose=None)[source]#

Compute a Power Spectrum with a General Linear Model.

Parameters:

X (array_like) – Time series of measurement values
reg_categorical (dict or None) – Dictionary of covariate time series to be added as binary regessors. (Default value = None)
reg_ztrans (dict or None) – Dictionary of covariate time series to be added as z-standardised regessors. (Default value = None)
reg_unitmax (dict or None) – Dictionary of confound time series to be added as positive-valued unitmax regessors. (Default value = None)
contrasts (dict or None) – Dictionary of contrasts to be computed in the model. (Default value = None, will add a simple contrast for each regressor)
fit_method ({'pinv', 'lstsq', 'glmtools', sklearn estimator instance}) – Specifies how the GLM parameters will be estimated. * pinv uses the design matrix psuedo-inverse method * lstsq uses np.linalg.lstsq. * glmtools uses the OLSModel from the glmtools package. * A parametrised instance of a sklearn estimator is used if specified here. (Default value = ‘pinv’)
fit_intercept (bool) – Specifies whether a constant valued ‘intercept’ regressor is included in the model. (Default value = True)
nperseg (int) – Length of each segment. Defaults to None, but if window is str or tuple, is set to 256, and if window is array_like, is set to the length of the window.
noverlap (int) – Number of samples that successive sliding windows should overlap.
window_type (str or tuple or array_like, optional) – Desired window to use. If window is a string or tuple, it is passed to scipy.signal.windows.get_window to generate the window values, which are DFT-even by default. See scipy.signal.windows for a list of windows and required parameters. If window is array_like it will be used directly as the window and its length must be nperseg. Defaults to a Hann window.
detrend (str or function or False, optional) – Specifies how to detrend each segment. If detrend is a string, it is passed as the type argument to the detrend function. If it is a function, it takes a segment and returns a detrended segment. If detrend is False, no detrending is done. Defaults to ‘constant’.’
nfft (int) – Length of the FFT to use (Default value = 256)
axis (int) – Axis of input array along which the computation is performed. (Default value = -1)
return_onesided (bool, optional) – If True, return a one-sided spectrum for real data. If False return a two-sided spectrum. Defaults to True, but for complex data, a two-sided spectrum is always returned.
mode ({'psd', 'magnitude', 'angle', 'phase', 'complex'}) – Which type of spectrum to return (Default value = ‘psd’)
scaling ({ 'density', 'spectrum' }) – Selects between computing the power spectral density (‘density’) where Pxx has units of V**2/Hz and computing the power spectrum (‘spectrum’) where Pxx has units of V**2, if x is measured in V and fs is measured in Hz. Defaults to ‘density’
fs (float) – Sampling rate of the data
fmin ({float, None}) – Smallest frequency in desired range (left hand boundary)
fmax ({float, None}) – Largest frequency in desired range (right hand boundary)’
verbose ({None, 'DEBUG', 'INFO', 'WARNING', 'CRITICAL'}) – String indicating the level of detail to be printed to the screen during computation.’

Returns:

GLMSpectrumResult – Object containing the fitted GLM Periodogram

Return type:

object