Global Field Power peaks

This example demonstrates how to extract Global Field Power (GFP) peaks from an EEG recording.

Note

The lemon datasets used in this tutorial is composed of EEGLAB files. To use the MNE reader mne.io.read_raw_eeglab(), the pymatreader optional dependency is required. Use the following installation method appropriate for your environment:

• pip install pymatreader

• conda install -c conda-forge pymatreader

Note that an environment created via the MNE installers includes pymatreader by default.

import mne
from mne.io import read_raw_eeglab

from pycrostates.datasets import lemon

raw_fname = lemon.data_path(subject_id="010004", condition="EC")
raw = read_raw_eeglab(raw_fname, preload=True)

raw.pick("eeg")
raw.set_eeg_reference("average")

Reading /home/docs/pycrostates_data/PREPROCESSED_LEMON/sub-010004_EC.fdt
Reading 0 ... 119277  =      0.000 ...   477.108 secs...
/home/docs/checkouts/readthedocs.org/user_builds/pycrostates/checkouts/latest/tutorials/preprocessing/00_extract_gfp_peaks.py:32: RuntimeWarning: Limited 1 annotation(s) that were expanding outside the data range.
  raw = read_raw_eeglab(raw_fname, preload=True)
/home/docs/checkouts/readthedocs.org/user_builds/pycrostates/checkouts/latest/tutorials/preprocessing/00_extract_gfp_peaks.py:32: RuntimeWarning: The data contains 'boundary' events, indicating data discontinuities. Be cautious of filtering and epoching around these events.
  raw = read_raw_eeglab(raw_fname, preload=True)
EEG channel type selected for re-referencing
Applying average reference.
Applying a custom ('EEG',) reference.

	General
	Filename(s)	sub-010004_EC.fdt
	MNE object type	RawEEGLAB
	Measurement date	Unknown
	Participant	Unknown
	Experimenter	Unknown
	Acquisition
	Duration	00:07:58 (HH:MM:SS)
	Sampling frequency	250.00 Hz
	Time points	119,278
	Channels
	EEG	61
	Head & sensor digitization	64 points
	Filters
	Highpass	0.00 Hz
	Lowpass	125.00 Hz

Global Field Power (GFP) is computed as the standard deviation of the sensors at a given timepoint. Local maxima of the Global Field Power (GFP) are known to represent the portions of EEG data with highest signal-to-noise ratio[1]. We can use the extract_gfp_peaks() function to extract samples with the highest Global Field Power. The minimum distance between consecutive peaks can be defined with the min_peak_distance argument.

from pycrostates.preprocessing import extract_gfp_peaks

gfp_data = extract_gfp_peaks(raw, min_peak_distance=3)
gfp_data

ChData	14713 samples

	General
	MNE object type	ChInfo
	Measurement date	Unknown
	Participant	Unknown
	Experimenter	Unknown
	Acquisition
	Channels
	EEG	61
	Head & sensor digitization	64 points
	Filters

GFP peaks can also be extracted from an Epochs object.

epochs = mne.make_fixed_length_epochs(raw, duration=2, preload=True)
gfp_data = extract_gfp_peaks(epochs, min_peak_distance=3)
gfp_data

Not setting metadata
238 matching events found
No baseline correction applied
0 projection items activated
Using data from preloaded Raw for 238 events and 500 original time points ...
0 bad epochs dropped

ChData	14617 samples

	General
	MNE object type	ChInfo
	Measurement date	Unknown
	Participant	Unknown
	Experimenter	Unknown
	Acquisition
	Channels
	EEG	61
	Head & sensor digitization	64 points
	Filters

The extracted GFP peaks can be used in other preprocessing steps, such as a resampling using resample():

from pycrostates.preprocessing import resample

# extract 1 resample of 100 random high GFP samples
resample = resample(gfp_data, n_resamples=1, n_samples=100)
resample[0]

ChData	100 samples

	General
	MNE object type	ChInfo
	Measurement date	Unknown
	Participant	Unknown
	Experimenter	Unknown
	Acquisition
	Channels
	EEG	61
	Head & sensor digitization	64 points
	Filters

Or they can be used to fit a clustering algorithm on the portion of EEG data with the highest signal-to-noise ratio.

from pycrostates.cluster import ModKMeans

ModK = ModKMeans(n_clusters=5, random_state=42)
ModK.fit(gfp_data, n_jobs=5, verbose="WARNING")
ModK.plot()

<Figure size 1500x300 with 5 Axes>

References

[1]

Thomas Koenig and Daniel Brandeis. Inappropriate assumptions about eeg state changes and their impact on the quantification of eeg state dynamics. NeuroImage, 125:1104–1106, 2016. doi:10.1016/j.neuroimage.2015.06.035.

Estimated memory usage: 387 MB