Home / neurokit2 / references/eeg.md

references/eeg.md

EEG Analysis and Microstates

Overview

Analyze electroencephalography (EEG) signals for frequency band power, channel quality assessment, source localization, and microstate identification. NeuroKit2 integrates with MNE-Python for comprehensive EEG processing workflows.

Core EEG Functions

eeg_power()

Compute power across standard frequency bands for specified channels.

power = nk.eeg_power(eeg_data, sampling_rate=250, channels=['Fz', 'Cz', 'Pz'],
                     frequency_bands={'Delta': (0.5, 4),
                                     'Theta': (4, 8),
                                     'Alpha': (8, 13),
                                     'Beta': (13, 30),
                                     'Gamma': (30, 45)})

Standard frequency bands: - Delta (0.5-4 Hz): Deep sleep, unconscious processes - Theta (4-8 Hz): Drowsiness, meditation, memory encoding - Alpha (8-13 Hz): Relaxed wakefulness, eyes closed - Beta (13-30 Hz): Active thinking, focus, anxiety - Gamma (30-45 Hz): Cognitive processing, binding

Returns: - DataFrame with power values for each channel × frequency band combination - Columns: Channel_Band (e.g., 'Fz_Alpha', 'Cz_Beta')

Use cases: - Resting state analysis - Cognitive state classification - Sleep staging - Meditation or neurofeedback monitoring

eeg_badchannels()

Identify problematic channels using statistical outlier detection.

bad_channels = nk.eeg_badchannels(eeg_data, sampling_rate=250, bad_threshold=2)

Detection methods: - Standard deviation outliers across channels - Correlation with other channels - Flat or dead channels - Channels with excessive noise

Parameters: - bad_threshold: Z-score threshold for outlier detection (default: 2)

Returns: - List of channel names identified as problematic

Use case: - Quality control before analysis - Automatic bad channel rejection - Interpolation or exclusion decisions

eeg_rereference()

Re-express voltage measurements relative to different reference points.

rereferenced = nk.eeg_rereference(eeg_data, reference='average', robust=False)

Reference types: - 'average': Average reference (mean of all electrodes) - 'REST': Reference Electrode Standardization Technique - 'bipolar': Differential recording between electrode pairs - Specific channel name: Use single electrode as reference

Common references: - Average reference: Most common for high-density EEG - Linked mastoids: Traditional clinical EEG - Vertex (Cz): Sometimes used in ERP research - REST: Approximates infinity reference

Returns: - Re-referenced EEG data

eeg_gfp()

Compute Global Field Power - the standard deviation of all electrodes at each time point.

gfp = nk.eeg_gfp(eeg_data)

Interpretation: - High GFP: Strong, synchronized brain activity across regions - Low GFP: Weak or desynchronized activity - GFP peaks: Points of stable topography, used for microstate detection

Use cases: - Identify periods of stable topographic patterns - Select time points for microstate analysis - Event-related potential (ERP) visualization

eeg_diss()

Measure topographic dissimilarity between electric field configurations.

dissimilarity = nk.eeg_diss(eeg_data1, eeg_data2, method='gfp')

Methods: - GFP-based: Normalized difference - Spatial correlation - Cosine distance

Use case: - Compare topographies between conditions - Microstate transition analysis - Template matching

Source Localization

eeg_source()

Perform source reconstruction to estimate brain-level activity from scalp recordings.

sources = nk.eeg_source(eeg_data, method='sLORETA')

Methods: - 'sLORETA': Standardized Low-Resolution Electromagnetic Tomography - Zero localization error for point sources - Good spatial resolution - 'MNE': Minimum Norm Estimate - Fast, well-established - Bias toward superficial sources - 'dSPM': Dynamic Statistical Parametric Mapping - Normalized MNE - 'eLORETA': Exact LORETA - Improved localization accuracy

Requirements: - Forward model (lead field matrix) - Co-registered electrode positions - Head model (boundary element or spherical)

Returns: - Source space activity estimates

eeg_source_extract()

Extract activity from specific anatomical brain regions.

regional_activity = nk.eeg_source_extract(sources, regions=['PFC', 'MTL', 'Parietal'])

Region options: - Standard atlases: Desikan-Killiany, Destrieux, AAL - Custom ROIs - Brodmann areas

Returns: - Time series for each region - Averaged or principal component across voxels

Use cases: - Region-of-interest analysis - Functional connectivity - Source-level statistics

Microstate Analysis

Microstates are brief (80-120 ms) periods of stable brain topography, representing coordinated neural networks. Typically 4-7 microstate classes (often labeled A, B, C, D) with distinct functions.

microstates_segment()

Identify and extract microstates using clustering algorithms.

microstates = nk.microstates_segment(eeg_data, n_microstates=4, sampling_rate=250,
                                      method='kmod', normalize=True)

Methods: - 'kmod' (default): Modified k-means optimized for EEG topographies - Polarity-invariant clustering - Most common in microstate literature - 'kmeans': Standard k-means clustering - 'kmedoids': K-medoids (more robust to outliers) - 'pca': Principal component analysis - 'ica': Independent component analysis - 'aahc': Atomize and agglomerate hierarchical clustering

Parameters: - n_microstates: Number of microstate classes (typically 4-7) - normalize: Normalize topographies (recommended: True) - n_inits: Number of random initializations (increase for stability)

Returns: - Dictionary with: - 'maps': Microstate template topographies - 'labels': Microstate label at each time point - 'gfp': Global field power - 'gev': Global explained variance

microstates_findnumber()

Estimate the optimal number of microstates.

optimal_k = nk.microstates_findnumber(eeg_data, show=True)

Criteria: - Global Explained Variance (GEV): Percentage of variance explained - Elbow method: find "knee" in GEV curve - Typically 70-80% GEV achieved - Krzanowski-Lai (KL) Criterion: Statistical measure balancing fit and parsimony - Maximum KL indicates optimal k

Typical range: 4-7 microstates - 4 microstates: Classic A, B, C, D states - 5-7 microstates: Finer-grained decomposition

microstates_classify()

Reorder microstates based on anterior-posterior and left-right channel values.

classified = nk.microstates_classify(microstates)

Purpose: - Standardize microstate labels across subjects - Match conventional A, B, C, D topographies: - A: Left-right orientation, parieto-occipital - B: Right-left orientation, fronto-temporal - C: Anterior-posterior orientation, frontal-central - D: Fronto-central, anterior-posterior (inverse of C)

Returns: - Reordered microstate maps and labels

microstates_clean()

Preprocess EEG data for microstate extraction.

cleaned_eeg = nk.microstates_clean(eeg_data, sampling_rate=250)

Preprocessing steps: - Bandpass filtering (typically 2-20 Hz) - Artifact rejection - Bad channel interpolation - Re-referencing to average

Rationale: - Microstates reflect large-scale network activity - High-frequency and low-frequency artifacts can distort topographies

microstates_peaks()

Identify GFP peaks for microstate analysis.

peak_indices = nk.microstates_peaks(eeg_data, sampling_rate=250)

Purpose: - Microstates typically analyzed at GFP peaks - Peaks represent moments of maximal, stable topographic activity - Reduces computational load and noise sensitivity

Returns: - Indices of GFP local maxima

microstates_static()

Compute temporal properties of individual microstates.

static_metrics = nk.microstates_static(microstates)

Metrics: - Duration (ms): Mean time spent in each microstate - Typical: 80-120 ms - Reflects stability and persistence - Occurrence (per second): Frequency of microstate appearances - How often each state is entered - Coverage (%): Percentage of total time in each microstate - Relative dominance - Global Explained Variance (GEV): Variance explained by each class - Quality of template fit

Returns: - DataFrame with metrics for each microstate class

Interpretation: - Changes in duration: altered network stability - Changes in occurrence: shifting state dynamics - Changes in coverage: dominance of specific networks

microstates_dynamic()

Analyze transition patterns between microstates.

dynamic_metrics = nk.microstates_dynamic(microstates)

Metrics: - Transition matrix: Probability of transitioning from state i to state j - Reveals preferential sequences - Transition rate: Overall transition frequency - Higher rate: more rapid switching - Entropy: Randomness of transitions - High entropy: unpredictable switching - Low entropy: stereotyped sequences - Markov test: Are transitions history-dependent?

Returns: - Dictionary with transition statistics

Use cases: - Identify abnormal microstate sequences in clinical populations - Network dynamics and flexibility - State-dependent information processing

microstates_plot()

Visualize microstate topographies and time course.

nk.microstates_plot(microstates, eeg_data)

Displays: - Topographic maps for each microstate class - GFP trace with microstate labels - Transition plot showing state sequences - Statistical summary

MNE Integration Utilities

mne_data()

Access sample datasets from MNE-Python.

raw = nk.mne_data(dataset='sample', directory=None)

Available datasets: - 'sample': Multi-modal (MEG/EEG) example - 'ssvep': Steady-state visual evoked potentials - 'eegbci': Motor imagery BCI dataset

mne_to_df() / mne_to_dict()

Convert MNE objects to NeuroKit-compatible formats.

df = nk.mne_to_df(raw)
data_dict = nk.mne_to_dict(epochs)

Use case: - Work with MNE-processed data in NeuroKit2 - Convert between formats for analysis

mne_channel_add() / mne_channel_extract()

Manage individual channels in MNE objects.

# Extract specific channels
subset = nk.mne_channel_extract(raw, ['Fz', 'Cz', 'Pz'])

# Add derived channels
raw_with_eog = nk.mne_channel_add(raw, new_channel_data, ch_name='EOG')

mne_crop()

Trim recordings by time or samples.

cropped = nk.mne_crop(raw, tmin=10, tmax=100)

mne_templateMRI()

Provide template anatomy for source localization.

subjects_dir = nk.mne_templateMRI()

Use case: - Source analysis without individual MRI - Group-level source localization - fsaverage template brain

eeg_simulate()

Generate synthetic EEG signals for testing.

synthetic_eeg = nk.eeg_simulate(duration=60, sampling_rate=250, n_channels=32)

Practical Considerations

Sampling Rate Recommendations

  • Minimum: 100 Hz for basic power analysis
  • Standard: 250-500 Hz for most applications
  • High-resolution: 1000+ Hz for detailed temporal dynamics

Recording Duration

  • Power analysis: ≥2 minutes for stable estimates
  • Microstates: ≥2-5 minutes, longer preferred
  • Resting state: 3-10 minutes typical
  • Event-related: Depends on trial count (≥30 trials per condition)

Artifact Management

  • Eye blinks: Remove with ICA or regression
  • Muscle artifacts: High-pass filter (≥1 Hz) or manual rejection
  • Bad channels: Detect and interpolate before analysis
  • Line noise: Notch filter at 50/60 Hz

Best Practices

Power analysis:

# 1. Clean data
cleaned = nk.signal_filter(eeg_data, sampling_rate=250, lowcut=0.5, highcut=45)

# 2. Identify and interpolate bad channels
bad = nk.eeg_badchannels(cleaned, sampling_rate=250)
# Interpolate bad channels using MNE

# 3. Re-reference
rereferenced = nk.eeg_rereference(cleaned, reference='average')

# 4. Compute power
power = nk.eeg_power(rereferenced, sampling_rate=250, channels=channel_list)

Microstate workflow:

# 1. Preprocess
cleaned = nk.microstates_clean(eeg_data, sampling_rate=250)

# 2. Determine optimal number of states
optimal_k = nk.microstates_findnumber(cleaned, show=True)

# 3. Segment microstates
microstates = nk.microstates_segment(cleaned, n_microstates=optimal_k,
                                     sampling_rate=250, method='kmod')

# 4. Classify to standard labels
microstates = nk.microstates_classify(microstates)

# 5. Compute temporal metrics
static = nk.microstates_static(microstates)
dynamic = nk.microstates_dynamic(microstates)

# 6. Visualize
nk.microstates_plot(microstates, cleaned)

Clinical and Research Applications

Cognitive neuroscience: - Attention, working memory, executive function - Language processing - Sensory perception

Clinical populations: - Epilepsy: seizure detection, localization - Alzheimer's disease: slowing of EEG, microstate alterations - Schizophrenia: altered microstates, especially state C - ADHD: increased theta/beta ratio - Depression: frontal alpha asymmetry

Consciousness research: - Anesthesia monitoring - Disorders of consciousness - Sleep staging

Neurofeedback: - Real-time frequency band training - Alpha enhancement for relaxation - Beta enhancement for focus

References

  • Michel, C. M., & Koenig, T. (2018). EEG microstates as a tool for studying the temporal dynamics of whole-brain neuronal networks: A review. Neuroimage, 180, 577-593.
  • Pascual-Marqui, R. D., Michel, C. M., & Lehmann, D. (1995). Segmentation of brain electrical activity into microstates: model estimation and validation. IEEE Transactions on Biomedical Engineering, 42(7), 658-665.
  • Gramfort, A., Luessi, M., Larson, E., Engemann, D. A., Strohmeier, D., Brodbeck, C., ... & Hämäläinen, M. (2013). MEG and EEG data analysis with MNE-Python. Frontiers in neuroscience, 7, 267.
← Back to neurokit2