mne_connectivity.spectral_connectivity_time#

mne_connectivity.spectral_connectivity_time(data, freqs, method='coh', average=False, indices=None, sfreq=None, fmin=None, fmax=None, fskip=0, faverage=False, sm_times=0, sm_freqs=1, sm_kernel='hanning', padding=0, mode='cwt_morlet', mt_bandwidth=None, n_cycles=7, decim=1, n_jobs=1, verbose=None)[source]#

Compute time-frequency-domain connectivity measures.

This function computes spectral connectivity over time from epoched data. The data may consist of a single epoch.

The connectivity method(s) are specified using the method parameter. All methods are based on time-resolved estimates of the cross- and power spectral densities (CSD/PSD) Sxy and Sxx, Syy.

Parameters

data : array_like, shape (n_epochs, n_signals, n_times) | Epochs

The data from which to compute connectivity.

freqs : array_like

Array of frequencies of interest for time-frequency decomposition. Only the frequencies within the range specified by fmin and fmax are used.

method : str | list of str

Connectivity measure(s) to compute. These can be ['coh', 'plv', 'ciplv', 'pli', 'wpli']. These are: * ‘coh’ : Coherence * ‘plv’ : Phase-Locking Value (PLV) * ‘ciplv’ : Corrected imaginary Phase-Locking Value * ‘pli’ : Phase-Lag Index * ‘wpli’ : Weighted Phase-Lag Index

average : bool

Average connectivity scores over epochs. If True, output will be an instance of SpectralConnectivity, otherwise EpochSpectralConnectivity.

indices : tuple of array_like | None

Two arrays with indices of connections for which to compute connectivity. I.e. it is a (n_pairs, 2) array essentially. If None, all connections are computed.

sfreq : float

The sampling frequency. Required if data is not Epochs.

fmin : float | tuple of float | None

The lower frequency of interest. Multiple bands are defined using a tuple, e.g., (8., 20.) for two bands with 8 Hz and 20 Hz lower bounds. If None, the lowest frequency in freqs is used.

fmax : float | tuple of float | None

The upper frequency of interest. Multiple bands are defined using a tuple, e.g. (13., 30.) for two band with 13 Hz and 30 Hz upper bounds. If None, the highest frequency in freqs is used.

fskip : int

Omit every (fskip + 1)-th frequency bin to decimate in frequency domain.

faverage : bool

Average connectivity scores for each frequency band. If True, the output freqs will be an array of the median frequencies of each band.

sm_times : float

Amount of time to consider for the temporal smoothing in seconds. If zero, no temporal smoothing is applied.

sm_freqs : int

Number of points for frequency smoothing. By default, 1 is used which is equivalent to no smoothing.

sm_kernel : {‘square’, ‘hanning’}

Smoothing kernel type. Choose either ‘square’ or ‘hanning’.

padding : float

Amount of time to consider as padding at the beginning and end of each epoch in seconds. See Notes for more information.

mode : str

Time-frequency decomposition method. Can be either: ‘multitaper’, or ‘cwt_morlet’. See mne.time_frequency.tfr_array_multitaper() and mne.time_frequency.tfr_array_morlet() for reference.

mt_bandwidth : float | None

Product between the temporal window length (in seconds) and the full frequency bandwidth (in Hz). This product can be seen as the surface of the window on the time/frequency plane and controls the frequency bandwidth (thus the frequency resolution) and the number of good tapers. See mne.time_frequency.tfr_array_multitaper() documentation.

n_cycles : float | array_like of float

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 cwt_freqs define the temporal window length. For details, see mne.time_frequency.tfr_array_morlet() documentation.

decim : int

To reduce memory usage, decimation factor after time-frequency decomposition. Returns tfr[…, ::decim].

n_jobs : int

Number of connections to compute in parallel. Memory mapping must be activated. Please see the Notes section for details.

verbose : bool, str, int, or None

If not None, override default verbose level (see mne.verbose() for more info). If used, it should be passed as a keyword-argument only.

Returns

con : instance of Connectivity | list

Computed connectivity measure(s). An instance of EpochSpectralConnectivity, SpectralConnectivity or a list of instances corresponding to connectivity measures if several connectivity measures are specified. The shape of each connectivity dataset is (n_epochs, n_signals, n_signals, n_freqs) when indices is None and (n_epochs, n_nodes, n_nodes, n_freqs) when indices is specified and n_nodes = len(indices[0]).

See also

mne_connectivity.spectral_connectivity_epochs
mne_connectivity.SpectralConnectivity
mne_connectivity.EpochSpectralConnectivity

Notes

Please note that the interpretation of the measures in this function depends on the data and underlying assumptions and does not necessarily reflect a causal relationship between brain regions.

The connectivity measures are computed over time within each epoch and optionally averaged over epochs. High connectivity values indicate that the phase coupling (interpreted as estimated connectivity) differences between signals stay consistent over time.

The spectral densities can be estimated using a multitaper method with digital prolate spheroidal sequence (DPSS) windows, or a continuous wavelet transform using Morlet wavelets. The spectral estimation mode is specified using the mode parameter.

When using the multitaper spectral estimation method, the cross-spectral density is computed separately for each taper and aggregated using a weighted average, where the weights correspond to the concentration ratios between the DPSS windows.

Spectral estimation using multitaper or Morlet wavelets introduces edge effects that depend on the length of the wavelet. To remove edge effects, the parameter padding can be used to prune the edges of the signal. Please see the documentation of mne.time_frequency.tfr_array_multitaper() and mne.time_frequency.tfr_array_morlet() for details on wavelet length (i.e., time window length).

By default, the connectivity between all signals is computed (only connections corresponding to the lower-triangular part of the connectivity matrix). If one is only interested in the connectivity between some signals, the indices parameter can be used. For example, to compute the connectivity between the signal with index 0 and signals 2, 3, 4 (a total of 3 connections), one can use the following:

indices = (np.array([0, 0, 0]),    # row indices
           np.array([2, 3, 4]))    # col indices

con = spectral_connectivity_time(data, method='coh',
                                 indices=indices, ...)

In this case con.get_data().shape = (3, n_freqs). The connectivity scores are in the same order as defined indices.

Supported Connectivity Measures

The connectivity method(s) is specified using the method parameter. The following methods are supported (note: E[] denotes average over epochs). Multiple measures can be computed at once by using a list/tuple, e.g., ['coh', 'pli'] to compute coherence and PLI.

‘coh’ : Coherence given by:
         | E[Sxy] |
C = ---------------------
    sqrt(E[Sxx] * E[Syy])
‘plv’ : Phase-Locking Value (PLV) 1 given by:
PLV = |E[Sxy/|Sxy|]|
‘ciplv’ : Corrected imaginary PLV (icPLV) 2 given by:
                 |E[Im(Sxy/|Sxy|)]|
ciPLV = ------------------------------------
         sqrt(1 - |E[real(Sxy/|Sxy|)]| ** 2)
‘pli’ : Phase Lag Index (PLI) 3 given by:
PLI = |E[sign(Im(Sxy))]|
‘wpli’ : Weighted Phase Lag Index (WPLI) 4 given by:
          |E[Im(Sxy)]|
WPLI = ------------------
          E[|Im(Sxy)|]

Parallel computation can be activated by setting the n_jobs parameter. Under the hood, this utilizes the joblib library. For effective parallelization, you should activate memory mapping in MNE-Python by setting MNE_MEMMAP_MIN_SIZE and MNE_CACHE_DIR. Activating memory mapping will make joblib store arrays greater than the minimum size on disc, and forego direct RAM access for more efficient processing. For example, in your code, run

mne.set_config(‘MNE_MEMMAP_MIN_SIZE’, ‘10M’) mne.set_config(‘MNE_CACHE_DIR’, ‘/dev/shm’)

When MNE_MEMMAP_MIN_SIZE=None, the underlying joblib implementation results in pickling and unpickling the whole array each time a pair of indices is accessed, which is slow, compared to memory mapping the array.

This function is based on the frites.conn.conn_spec implementation in Frites.

New in version 0.3.

References

1: Jean-Philippe Lachaux, Eugenio Rodriguez, Jacques Martinerie, and Francisco J. Varela. Measuring phase synchrony in brain signals. Human Brain Mapping, 8(4):194–208, 1999. doi:10.1002/(SICI)1097-0193(1999)8:4<194::AID-HBM4>3.0.CO;2-C.
2: Ernesto Pereda Ricardo Bruña, Fernando Maestú. Phase locking value revisited: teaching new tricks to an old dog. Journal of Neural Engineering, 15(5):056011, 2018. doi:10.1088/1741-2552/aacfe4.
3: Cornelis J. Stam, Guido Nolte, and Andreas Daffertshofer. Phase lag index: assessment of functional connectivity from multi channel EEG and MEG with diminished bias from common sources. Human Brain Mapping, 28(11):1178–1193, 2007. doi:10.1002/hbm.20346.
4: Martin Vinck, Robert Oostenveld, Marijn van Wingerden, Franscesco Battaglia, and Cyriel M.A. Pennartz. An improved index of phase-synchronization for electrophysiological data in the presence of volume-conduction, noise and sample-size bias. NeuroImage, 55(4):1548–1565, 2011. doi:10.1016/j.neuroimage.2011.01.055.