gh-k-dense-ai-claude-scientific-skills-scientific-skills/skills/neurokit2/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.