mne.time_frequency.tfr_morlet#

mne.time_frequency.tfr_morlet(inst, freqs, n_cycles, use_fft=False, return_itc=True, decim=1, n_jobs=None, picks=None, zero_mean=True, average=True, output='power', verbose=None)[source]#

Compute Time-Frequency Representation (TFR) using Morlet wavelets.

Same computation as tfr_array_morlet, but operates on Epochs or Evoked objects instead of NumPy arrays.

Parameters

instEpochs | Evoked

The epochs or evoked object.

freqsarray of float, shape (n_freqs,)

The frequencies of interest in Hz.

n_cyclesint | array of int, shape (n_freqs,)

Number of cycles in the wavelet, either a fixed number or one per frequency. The number of cycles n_cycles and the frequencies of interest freqs define the temporal window length. See notes for additional information about the relationship between those arguments and about time and frequency smoothing.

use_fftbool, default False

The fft based convolution or not.

return_itcbool, default True

Return inter-trial coherence (ITC) as well as averaged power. Must be False for evoked data.

decimint | slice, default 1

To reduce memory usage, decimation factor after time-frequency decomposition.

if int, returns tfr[..., ::decim].
if slice, returns tfr[..., decim].

Note

Decimation is done after convolutions and may create aliasing artifacts.

n_jobsint | None

The number of jobs to run in parallel. If -1, it is set to the number of CPU cores. Requires the joblib package. None (default) is a marker for ‘unset’ that will be interpreted as n_jobs=1 (sequential execution) unless the call is performed under a joblib.parallel_config context manager that sets another value for n_jobs.

picksarray_like of int | None, default None

The indices of the channels to decompose. If None, all available good data channels are decomposed.

zero_meanbool, default True

Make sure the wavelet has a mean of zero.

New in v0.13.0.

averagebool, default True

If False return an EpochsTFR containing separate TFRs for each epoch. If True return an AverageTFR containing the average of all TFRs across epochs.

Note

Using average=True is functionally equivalent to using average=False followed by EpochsTFR.average(), but is more memory efficient.

New in v0.13.0.

outputstr

Can be "power" (default) or "complex". If "complex", then average must be False.

New in v0.15.0.

verbosebool | str | int | None

Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

Returns

powerAverageTFR | EpochsTFR: The averaged or single-trial power.
itcAverageTFR | EpochsTFR: The inter-trial coherence (ITC). Only returned if return_itc is True.

See also

mne.time_frequency.tfr_array_morlet
mne.time_frequency.tfr_multitaper
mne.time_frequency.tfr_array_multitaper
mne.time_frequency.tfr_stockwell
mne.time_frequency.tfr_array_stockwell

Notes

The Morlet wavelets follow the formulation in 1.

In spectrotemporal analysis (as with traditional fourier methods), the temporal and spectral resolution are interrelated: longer temporal windows allow more precise frequency estimates; shorter temporal windows “smear” frequency estimates while providing more precise timing information.

Time-frequency representations are computed using a sliding temporal window. Either the temporal window has a fixed length independent of frequency, or the temporal window decreases in length with increased frequency.

https://www.fieldtriptoolbox.org/assets/img/tutorial/timefrequencyanalysis/figure1.png

Figure: Time and frequency smoothing. (a) For a fixed length temporal window the time and frequency smoothing remains fixed. (b) For temporal windows that decrease with frequency, the temporal smoothing decreases and the frequency smoothing increases with frequency. Source: FieldTrip tutorial: Time-frequency analysis using Hanning window, multitapers and wavelets.

In MNE-Python, the temporal window length is defined by the arguments freqs and n_cycles, respectively defining the frequencies of interest and the number of cycles: \(T = \frac{\mathtt{n\_cycles}}{\mathtt{freqs}}\)

A fixed number of cycles for all frequencies will yield a temporal window which decreases with frequency. For example, freqs=np.arange(1, 6, 2) and n_cycles=2 yields T=array([2., 0.7, 0.4]).

To use a temporal window with fixed length, the number of cycles has to be defined based on the frequency. For example, freqs=np.arange(1, 6, 2) and n_cycles=freqs / 2 yields T=array([0.5, 0.5, 0.5]).

Convolution of a signal with a Morlet wavelet will impose temporal smoothing that is determined by the duration of the wavelet. In MNE-Python, the duration of the wavelet is determined by the sigma parameter, which gives the standard deviation of the wavelet’s Gaussian envelope (our wavelets extend to ±5 standard deviations to ensure values very close to zero at the endpoints). Some authors (e.g., 2) recommend specifying and reporting wavelet duration in terms of the full-width half-maximum (FWHM) of the wavelet’s Gaussian envelope. The FWHM is related to sigma by the following identity: \(\mathrm{FWHM} = \sigma \times 2 \sqrt{2 \ln{2}}\) (or the equivalent in Python code: fwhm = sigma * 2 * np.sqrt(2 * np.log(2))). If sigma is not provided, it is computed from n_cycles as \(\frac{\mathtt{n\_cycles}}{2 \pi f}\) where \(f\) is the frequency of the wavelet oscillation (given by freqs). Thus when sigma=None the FWHM will be given by

\[\mathrm{FWHM} = \frac{\mathtt{n\_cycles} \times \sqrt{2 \ln{2}}}{\pi \times f}\]

(cf. eq. 4 in 2). To create wavelets with a chosen FWHM, one can compute:

n_cycles = desired_fwhm * np.pi * np.array(freqs) / np.sqrt(2 * np.log(2))

to get an array of values for n_cycles that yield the desired FWHM at each frequency in freqs. If you want different FWHM values at each frequency, do the same computation with desired_fwhm as an array of the same shape as freqs.

See mne.time_frequency.morlet() for more information about the Morlet wavelet.

References

1: Catherine Tallon-Baudry, Olivier Bertrand, Claude Delpuech, and Jacques Pernier. Oscillatory Gamma-Band (30–70 Hz) Activity Induced by a Visual Search Task in Humans. Journal of Neuroscience, pages 722–734, 1997. doi:10.1523/JNEUROSCI.17-02-00722.1997.
2(1,2): Michael X Cohen. A better way to define and describe Morlet wavelets for time-frequency analysis. NeuroImage, 199:81–86, 2019. doi:10.1016/j.neuroimage.2019.05.048.