mne_connectivity.phase_slope_index_time#

mne_connectivity.phase_slope_index_time(data, freqs=None, indices='lower', sfreq=None, *, mode='cwt_morlet', average=False, fmin=None, fmax=None, fdecim=1, sm_times=0.0, sm_freqs=1, sm_kernel='hanning', padding=0.0, mt_bandwidth=4.0, n_cycles=7.0, decim=1, n_jobs=1, verbose=None)[source]#

Compute the Phase Slope Index (PSI) connectivity measure over time.

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

The PSI is an effective connectivity measure, i.e., a measure which can give an indication of the direction of the information flow (causality). For two time series, one computes the PSI between the first and the second time series as follows:

indices = (np.array([0]), np.array([1]))
psi = phase_slope_index_time(data, indices=indices, ...)

A positive value means that time series 0 is ahead of time series 1 and a negative value means the opposite.

The PSI is computed from the coherency (see spectral_connectivity_time()), details can be found in [1].

Parameters:
dataarray_like, shape (n_epochs, n_signals, n_times) | Epochs | EpochsTFR

The data from which to compute connectivity. Can be epoched time series data as an array-like or mne.Epochs object, or Fourier coefficients for each epoch as an mne.time_frequency.EpochsTFR object. If time series data, the spectral information will be computed according to the spectral estimation mode (see the mode parameter). If an mne.time_frequency.EpochsTFR object, existing spectral information will be used and the mode parameter will be ignored.

Changed in version 0.8: Fourier coefficients stored in an mne.time_frequency.EpochsTFR object can also be passed in as data. Storing multitaper weights in mne.time_frequency.EpochsTFR objects requires mne >= 1.10.

freqsarray_like | None

Array-like of frequencies of interest for time-frequency decomposition. Only the frequencies within the range specified by fmin and fmax are used. If data is an array-like or mne.Epochs object, the frequencies must be specified. If data is an mne.time_frequency.EpochsTFR object, data.freqs is used and this parameter is ignored.

indicestuple of array_like | 'lower' | 'upper' | 'all'

The indices of channels to compute connectivity between. If a tuple, then must contain two array-likes, where the first array represents the channel indices of the seeds, and the second array represents the channel indices of the targets. See the notes section for more information. If 'lower', compute the lower-triangular part of the connectivity matrix. If 'upper', compute the upper-triangular part of the connectivity matrix. If 'all', compute all connections. Default is 'lower'.

sfreqfloat | None

The sampling frequency. Required if data is not an mne.Epochs or mne.time_frequency.EpochsTFR object.

mode'multitaper' | 'cwt_morlet'

Time-frequency decomposition method ('cwt_morlet' default). See mne.time_frequency.tfr_array_multitaper() and mne.time_frequency.tfr_array_morlet() for reference. Ignored if data is an mne.time_frequency.EpochsTFR object.

averagebool

Average connectivity scores over epochs. If True, output will be an instance of SpectralConnectivity, or EpochSpectralConnectivity if False (default).

fminfloat | 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 (default), the lowest frequency in freqs is used.

fmaxfloat | 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 (default), the highest frequency in freqs is used.

fdecimint

Decimation factor in the frequency domain. Selects every Nth frequency bin from the time-frequency decomposition (where N is the value of fdecim). If 1 (default), no decimation occurs.

sm_timesfloat

Amount of time to consider for the temporal smoothing, in seconds. If 0.0 (default), no temporal smoothing is applied.

sm_freqsint

Number of points for frequency smoothing. If 1 (default), no spectral smoothing is applied.

sm_kernel'square' | 'hanning'

Smoothing kernel type. For 'hanning', see numpy.hanning().

paddingfloat

Amount of time to consider as padding at the beginning and end of each epoch in seconds (0.0 default for no padding). See Notes of spectral_connectivity_time() for more information.

mt_bandwidthfloat

Product between the temporal window length (in seconds) and the full frequency bandwidth (in Hz; default 4.0). 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. Ignored if data is an mne.time_frequency.EpochsTFR object.

n_cyclesfloat | array_like

Number of cycles in the wavelet, either a fixed number or one per frequency (7.0 default). The number of cycles n_cycles and the frequencies of interest freqs define the temporal window length. For details, see mne.time_frequency.tfr_array_multitaper() and mne.time_frequency.tfr_array_morlet() documentation. Ignored if data is an mne.time_frequency.EpochsTFR object.

decimint

Decimation factor in the time domain. Selects every Nth time bin from the time-frequency decomposition (where N is the value of decim). If 1 (default), no decimation occurs.

n_jobsint

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

verbosebool | str | int | 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:
psiinstance of EpochSpectralConnectivity or SpectralConnectivity

Computed connectivity measure. Either a EpochSpectralConnectivity or SpectralConnectivity container depending on the average parameter. The shape of the connectivity dataset is ([n_epochs,] n_cons, n_bands):

  • The epoch dimension is present when average=False, and absent when average=True.

  • n_cons = n_signals ** 2 when indices='all'

  • n_cons = n_signals * (n_signals - 1) / 2 when indices is 'lower' or 'upper'

  • n_cons = len(indices[0]) when indices is supplied as a tuple of arrays

  • n_bands is the number of frequency bands defined by fmin and fmax

See also

mne_connectivity.spectral_connectivity_time
mne_connectivity.phase_slope_index
mne_connectivity.SpectralConnectivity
mne_connectivity.EpochSpectralConnectivity

Notes

If connectivity for all possible connections is desired, we can save time and memory by only computing and storing the lower- (or upper-) triangular part of the connectivity matrix. When the full set of connectivity values is needed, the missing values can be inferred based on what has been computed. See the notes section of the get_data() method in the connectivity containers for more information.

If one is only interested in the connectivity between some signals, the indices parameter can be specified as a tuple of array-likes. For example, to compute the connectivity between the signal with index 0 and the signals with indices 2, 3, and 4 (a total of 3 connections) one can use the following:

indices = (np.array([0, 0, 0]),  # seed indices
           np.array([2, 3, 4]))  # target indices

Added in version 0.8.

References

Examples using mne_connectivity.phase_slope_index_time#

Compute Phase Slope Index (PSI) in source space for a visual stimulus

Compute Phase Slope Index (PSI) in source space for a visual stimulus