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
objectsUsage 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 : detrending 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 transformPerform frequency analysis on timeseries 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 prepend and/or append to each trial
prepadlength : number of samples to prepend to each trial
postpadlength : number of samples to append to each trial
mtmconvol()
(Multi)tapered sliding window Fourier transformPerform timefrequency analysis on timeseries trial data based on a sliding window shorttime 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 datapoints.
toi : timepoints 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 nonorthogonal) wavelet transformPerform timefrequency analysis on timeseries trial data using a nonorthogonal continuous wavelet transform.
wav : one of
availableWavelets
toi : timepoints 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 realvalued 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 nonempty Syncopy
AnalogData
objectmethod (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 (arraylike 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 (arraylike (floats [fmin, fmax]) or None or "all") – Frequencywindow
[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 orfoilim = "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 methodspecific 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 samplecount of the longest (selected) trial in data. Conversely, timefrequency analysis methods (‘mtmconvol’ and ‘wavelet’), only perform padding if necessary, i.e., if timewindow centroids are chosen too close to trial boundaries for the entire window to cover available datapoints. If pad is False, then no padding is performed. Then in case ofmethod = 'mtmfft'
all trials have to have approximately the same length (up to the next even samplecount), ifmethod = 'mtmconvol'
ormethod = 'wavelet'
, windowcentroids have to keep sufficient distance from trial boundaries. For more details on the padding methods ‘absolute’, ‘relative’, ‘maxlen’ and ‘nextpow2’ seesyncopy.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 prepend 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 detrending data in the time domain prior to spectral analysis. A value of 0 corresponds to subtracting the mean (“demeaning”),
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 detrending 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 multitapering (Hz). Note that smoothing frequency specifications are onesided, i.e., 4 Hz smoothing means plusminus 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 arraylike or "all") – Mandatory input for timefrequency 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 timewindows 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 realvalued 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 realvalued 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 newSpectralData
object is to be created, or an emptySpectralData
objectparallel (None or bool) – If None (recommended), processing is automatically performed in parallel (i.e., concurrently across trials/channelgroups), 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) – Inplace selection of subset of input data for processing. Please refer tosyncopy.selectdata()
for further usage details.
 Returns
spec – (Time)frequency spectrum of input data
 Return type
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 multichannel time series data
syncopy.specest.mtmconvol.mtmconvol()
timefrequency analysis of multichannel time series data with a sliding window FFT
syncopy.specest.wavelet.wavelet()
timefrequency analysis of multichannel time series data using a wavelet transform
numpy.fft.fft()
NumPy’s reference FFT implementation
scipy.signal.stft()
SciPy’s Short Time Fourier Transform