freqanalysis

syncopy.freqanalysis(data, method='mtmfft', output='fourier', keeptrials=True, foi=None, foilim=None, pad=None, padtype='zero', padlength=None, prepadlength=None, postpadlength=None, polyremoval=None, taper='hann', tapsmofrq=None, keeptapers=False, toi=None, t_ftimwin=None, wav='Morlet', width=6, order=None, out=None, parallel=None, select=None, **kwargs)[source]

Perform (time-)frequency analysis of Syncopy AnalogData objects

Usage Summary

Options available in all analysis methods:

  • output : one of availableOutputs; return power spectra, complex Fourier spectra or absolute values.

  • foi/foilim : frequencies of interest; either array of frequencies or frequency window (not both)

  • keeptrials : return individual trials or grand average

  • polyremoval : de-trending method to use (0 = mean, 1 = linear, 2 = quadratic, 3 = cubic, etc.)

List of available analysis methods and respective distinct options:

mtmfft()(Multi-)tapered Fourier transform

Perform frequency analysis on time-series trial data using either a single taper window (Hanning) or many tapers based on the discrete prolate spheroidal sequence (DPSS) that maximize energy concentration in the main lobe.

  • taper : one of availableTapers

  • tapsmofrq : spectral smoothing box for tapers (in Hz)

  • keeptapers : return individual tapers or average

  • pad : padding method to use (None, True, False, ‘absolute’, ‘relative’, ‘maxlen’ or ‘nextpow2’). If None, then ‘nextpow2’ is selected by default.

  • padtype : values to pad data with (‘zero’, ‘nan’, ‘mean’, ‘localmean’, ‘edge’ or ‘mirror’)

  • padlength : number of samples to pre-pend and/or append to each trial

  • prepadlength : number of samples to pre-pend to each trial

  • postpadlength : number of samples to append to each trial

mtmconvol()(Multi-)tapered sliding window Fourier transform

Perform time-frequency analysis on time-series trial data based on a sliding window short-time Fourier transform using either a single Hanning taper or multiple DPSS tapers.

  • taper : one of availableTapers

  • tapsmofrq : spectral smoothing box for tapers (in Hz)

  • keeptapers : return individual tapers or average

  • pad : flag indicating, whether or not to pad trials. If None, trials are padded only if sliding window centroids are too close to trial boundaries for the entire window to cover available data-points.

  • toi : time-points of interest; can be either an array representing analysis window centroids (in sec), a scalar between 0 and 1 encoding the percentage of overlap between adjacent windows or “all” to center a window on every sample in the data.

  • t_ftimwin : sliding window length (in sec)

wavelet()(Continuous non-orthogonal) wavelet transform

Perform time-frequency analysis on time-series trial data using a non-orthogonal continuous wavelet transform.

  • wav : one of availableWavelets

  • toi : time-points of interest; can be either an array representing time points (in sec) to center wavelets on or “all” to center a wavelet on every sample in the data.

  • width : Nondimensional frequency constant of Morlet wavelet function (>= 6)

  • order : Order of Paul wavelet function (>= 4) or derivative order of real-valued DOG wavelets (2 = mexican hat)

Full documentation below

The parameters listed below can be provided as is or a via a cfg configuration ‘structure’, see Notes for details.

Parameters
  • data (~syncopy.AnalogData) – A non-empty Syncopy AnalogData object

  • method (str) – Spectral estimation method, one of availableMethods (see below).

  • output (str) – Output of spectral estimation. One of availableOutputs (see below); use ‘pow’ for power spectrum (numpy.float32), ‘fourier’ for complex Fourier coefficients (numpy.complex128) or ‘abs’ for absolute values (numpy.float32).

  • keeptrials (bool) – If True spectral estimates of individual trials are returned, otherwise results are averaged across trials.

  • foi (array-like or None) – Frequencies of interest (Hz) for output. If desired frequencies cannot be matched exactly, the closest possible frequencies are used. If foi is None or foi = "all", all attainable frequencies (i.e., zero to Nyquist / 2) are selected.

  • foilim (array-like (floats [fmin, fmax]) or None or "all") – Frequency-window [fmin, fmax] (in Hz) of interest. Window specifications must be sorted (e.g., [90, 70] is invalid) and not NaN but may be unbounded (e.g., [-np.inf, 60.5] is valid). Edges fmin and fmax are included in the selection. If foilim is None or foilim = "all", all frequencies are selected.

  • pad (str or None or bool) – One of None, True, False, ‘absolute’, ‘relative’, ‘maxlen’ or ‘nextpow2’. If pad is None or pad = True, then method-specific defaults are chosen. Specifically, if method is ‘mtmfft’ then pad is set to ‘nextpow2’ so that all trials in data are padded to the next power of two higher than the sample-count of the longest (selected) trial in data. Conversely, time-frequency analysis methods (‘mtmconvol’ and ‘wavelet’), only perform padding if necessary, i.e., if time-window centroids are chosen too close to trial boundaries for the entire window to cover available data-points. If pad is False, then no padding is performed. Then in case of method = 'mtmfft' all trials have to have approximately the same length (up to the next even sample-count), if method = 'mtmconvol' or method = 'wavelet', window-centroids have to keep sufficient distance from trial boundaries. For more details on the padding methods ‘absolute’, ‘relative’, ‘maxlen’ and ‘nextpow2’ see syncopy.padding().

  • padtype (str) – Values to be used for padding. Can be ‘zero’, ‘nan’, ‘mean’, ‘localmean’, ‘edge’ or ‘mirror’. See syncopy.padding() for more information.

  • padlength (None, bool or positive int) – Only valid if method is ‘mtmfft’ and pad is ‘absolute’ or ‘relative’. Number of samples to pad data with. See syncopy.padding() for more information.

  • prepadlength (None or bool or int) – Only valid if method is ‘mtmfft’ and pad is ‘relative’. Number of samples to pre-pend to each trial. See syncopy.padding() for more information.

  • postpadlength (None or bool or int) – Only valid if method is ‘mtmfft’ and pad is ‘relative’. Number of samples to append to each trial. See syncopy.padding() for more information.

  • polyremoval (int or None) – FIXME: Not implemented yet Order of polynomial used for de-trending data in the time domain prior to spectral analysis. A value of 0 corresponds to subtracting the mean (“de-meaning”), polyremoval = 1 removes linear trends (subtracting the least squares fit of a linear polynomial), polyremoval = N for N > 1 subtracts a polynomial of order N (N = 2 quadratic, N = 3 cubic etc.). If polyremoval is None, no de-trending is performed.

  • taper (str) – Only valid if method is ‘mtmfft’ or ‘mtmconvol’. Windowing function, one of availableTapers (see below).

  • tapsmofrq (float) – Only valid if method is ‘mtmfft’ or ‘mtmconvol’. The amount of spectral smoothing through multi-tapering (Hz). Note that smoothing frequency specifications are one-sided, i.e., 4 Hz smoothing means plus-minus 4 Hz, i.e., a 8 Hz smoothing box.

  • keeptapers (bool) – Only valid if method is ‘mtmfft’ or ‘mtmconvol’. If True, return spectral estimates for each taper, otherwise results are averaged across tapers.

  • toi (float or array-like or "all") – Mandatory input for time-frequency analysis methods (method is either “mtmconvol” or “wavelet”). If toi is scalar, it must be a value between 0 and 1 indicating the percentage of overlap between time-windows specified by t_ftimwin (only valid if method is ‘mtmconvol’, invalid for ‘wavelet’). If toi is an array it explicitly selects the centroids of analysis windows (in seconds). If toi is “all”, analysis windows are centered on all samples in the data.

  • t_ftimwin (positive float) – Only valid if method is ‘mtmconvol’. Sliding window length (in seconds).

  • wav (str) – Only valid if method is ‘wavelet’. Wavelet function to use, one of availableWavelets (see below).

  • width (positive float) – Only valid if method is ‘wavelet’ and wav is ‘Morlet’. Nondimensional frequency constant of Morlet wavelet function. This number should be >= 6, which corresponds to 6 cycles within the analysis window to ensure sufficient spectral sampling.

  • order (positive int) – Only valid if method is ‘wavelet’ and wav is ‘Paul’ or ‘DOG’. Order of the wavelet function. If wav is ‘Paul’, order should be chosen >= 4 to ensure that the analysis window contains at least a single oscillation. At an order of 40, the Paul wavelet exhibits about the same number of cycles as the Morlet wavelet with a width of 6. All other supported wavelets functions are real-valued derivatives of Gaussians (DOGs). Hence, if wav is ‘DOG’, order represents the derivative order. The special case of a second order DOG yields a function known as “Mexican Hat”, “Marr” or “Ricker” wavelet, which can be selected alternatively by setting wav to ‘Mexican_hat’, ‘Marr’ or ‘Ricker’. Note: A real-valued wavelet function encodes only information about peaks and discontinuities in the signal and does not provide any information about amplitude or phase.

  • out (None or SpectralData object) – None if a new SpectralData object is to be created, or an empty SpectralData object

  • parallel (None or bool) – If None (recommended), processing is automatically performed in parallel (i.e., concurrently across trials/channel-groups), provided a dask parallel processing client is running and available. Parallel processing can be manually disabled by setting parallel to False. If parallel is True but no parallel processing client is running, computing will be performed sequentially.

  • select (dict or StructDict or str) – In-place selection of subset of input data for processing. Please refer to syncopy.selectdata() for further usage details.

Returns

spec – (Time-)frequency spectrum of input data

Return type

SpectralData

Notes

This function can be either called providing its input arguments directly or via a cfg configuration ‘structure’. For instance, the following function calls are equivalent

>>> spy.freqanalysis(data, method=...)
>>> cfg = spy.StructDict()
>>> cfg.method = ...
>>> spy.freqanalysis(cfg, data)
>>> cfg.data = data
>>> spy.freqanalysis(cfg)

Please refer to Syncopy for FieldTrip Users for further details.

Coming soon…

Examples

Coming soon…

syncopy.specest.freqanalysis.availableMethods = ('mtmfft', 'mtmconvol', 'wavelet')

available spectral estimation methods of freqanalysis()

syncopy.specest.freqanalysis.availableOutputs = ('pow', 'fourier', 'abs')

available outputs of freqanalysis()

syncopy.specest.freqanalysis.availableTapers = ('hann', 'dpss')

available tapers of freqanalysis()

syncopy.specest.freqanalysis.availableWavelets = ('Morlet', 'Paul', 'DOG', 'Ricker', 'Marr', 'Mexican_hat')

available wavelet functions of freqanalysis()

See also

syncopy.specest.mtmfft.mtmfft()

(multi-)tapered Fourier transform of multi-channel time series data

syncopy.specest.mtmconvol.mtmconvol()

time-frequency analysis of multi-channel time series data with a sliding window FFT

syncopy.specest.wavelet.wavelet()

time-frequency analysis of multi-channel time series data using a wavelet transform

numpy.fft.fft()

NumPy’s reference FFT implementation

scipy.signal.stft()

SciPy’s Short Time Fourier Transform