mne_connectivity.make_surrogate_resting_data

mne_connectivity.make_surrogate_resting_data(data, n_shuffles=1000, rng_seed=None, return_generator=True)

Create surrogate resting-state data for a null hypothesis of connectivity.

Parameters:

dataEpochs | EpochsSpectrum | EpochsTFR

The time-series or Fourier coefficients to create the null hypothesis surrogate data for. Fourier coefficients can be generated from mne.Epochs.compute_psd() or mne.Epochs.compute_tfr() with output='complex'.

Changed in version 0.9: Added support for mne.Epochs objects.

Note

Storing Fourier coefficients in mne.time_frequency.EpochsSpectrum objects requires mne >= 1.8.

n_shufflesint (default 1000)

The number of surrogate datasets to create.

rng_seedint | None (default None)

The seed to use for the random number generator. If None, no seed is specified.

return_generatorbool (default True)

Whether or not to return the surrogate data as a generator object instead of a list. This allows iterating over the surrogates without having to keep them all in memory.

Returns:

surrogate_datalist of EpochsArray or EpochsSpectrum or EpochsTFR

The surrogate data for the null hypothesis with n_shuffles entries. Returned as a generator if return_generator=True.

Notes

Use only with non-evoked data

This approach is only suitable for generating surrogate data for a null hypothesis of connectivity from non-evoked data (e.g., resting state, inter-trial period). For working with evoked data, see make_surrogate_evoked_data().

Surrogate data is generated by randomly shuffling the order of epochs, independently for each channel. This destroys the covariance of the data, such that connectivity estimates should reflect the null hypothesis of no genuine connectivity between signals (e.g., only interactions due to background noise) [1].

For the surrogate data to properly reflect a null hypothesis, the data which is shuffled must not have a temporal structure that is consistent across epochs. Examples of this data include evoked potentials, where a stimulus is presented or an action performed at a set time during each epoch. Such data should not be used for generating surrogates, as even after shuffling the epochs, it will still show a high degree of residual connectivity between channels. As a result, connectivity estimates from your surrogate data will capture genuine interactions, instead of the desired background noise. Treating these estimates as a null hypothesis will increase the likelihood of a type II (false negative) error, i.e., that there is no significant connectivity in your data.

Appropriate data for generating surrogates using this approach includes data from a resting state, inter-trial period, or similar. Here, a strong temporal consistency across epochs is not assumed, reducing the chances that genuine connectivity information is captured in your surrogate connectivity estimates.

Finally, it is important to note that you should always compare true and surrogate connectivity estimates from epochs of the same duration. This will ensure that spectral information is captured with the same accuracy in both sets of connectivity estimates. Ideally, you should also compare true and surrogate connectivity estimates from the same number of epochs to avoid biases from noise (fewer epochs gives noisier estimates) or finite sample sizes (e.g., in coherency, phase-locking value, etc… [2]).

Note

make_surrogate_evoked_data() can also be used to generate surrogates from non-evoked data. However, it is computationally more expensive, especially if your end goal is to generate connectivity estimates from non-time-resolved spectral coefficients (e.g., those in EpochsSpectrum objects).

Changed in version 0.9: This function was renamed from make_surrogate_data to clarify that it is intended for generating surrogate data from non-evoked (e.g., resting state) data, in contrast to the new make_surrogate_evoked_data() function.

References

[1]

Franziska Pellegrini, Arnaud Delorme, Vadim Nikulin, and Stefan Haufe. Identifying good practices for detecting inter-regional linear functional connectivity from EEG. NeuroImage, 277:120218, 2023. doi:10.1016/j.neuroimage.2023.120218.

[2]

Martin Vinck, Marijn van Wingerden, Thilo Womelsdorf, Pascal Fries, and Cyriel M.A. Pennartz. The pairwise phase consistency: a bias-free measure of rhythmic neuronal synchronization. NeuroImage, 51(1):112–122, 2010. doi:10.1016/j.neuroimage.2010.01.073.

Examples using mne_connectivity.make_surrogate_resting_data

Determine the significance of connectivity estimates against baseline connectivity

Determine the significance of connectivity estimates against baseline connectivity