scientific-skills/neurokit2/references/eeg.md
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.
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:
Returns:
Channel_Band (e.g., 'Fz_Alpha', 'Cz_Beta')Use cases:
Identify problematic channels using statistical outlier detection.
bad_channels = nk.eeg_badchannels(eeg_data, sampling_rate=250, bad_threshold=2)
Detection methods:
Parameters:
bad_threshold: Z-score threshold for outlier detection (default: 2)Returns:
Use case:
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 pairsCommon references:
Returns:
Compute Global Field Power - the standard deviation of all electrodes at each time point.
gfp = nk.eeg_gfp(eeg_data)
Interpretation:
Use cases:
Measure topographic dissimilarity between electric field configurations.
dissimilarity = nk.eeg_diss(eeg_data1, eeg_data2, method='gfp')
Methods:
Use case:
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
'MNE': Minimum Norm Estimate
'dSPM': Dynamic Statistical Parametric Mapping
'eLORETA': Exact LORETA
Requirements:
Returns:
Extract activity from specific anatomical brain regions.
regional_activity = nk.eeg_source_extract(sources, regions=['PFC', 'MTL', 'Parietal'])
Region options:
Returns:
Use cases:
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.
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
'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 clusteringParameters:
n_microstates: Number of microstate classes (typically 4-7)normalize: Normalize topographies (recommended: True)n_inits: Number of random initializations (increase for stability)Returns:
'maps': Microstate template topographies'labels': Microstate label at each time point'gfp': Global field power'gev': Global explained varianceEstimate the optimal number of microstates.
optimal_k = nk.microstates_findnumber(eeg_data, show=True)
Criteria:
Typical range: 4-7 microstates
Reorder microstates based on anterior-posterior and left-right channel values.
classified = nk.microstates_classify(microstates)
Purpose:
Returns:
Preprocess EEG data for microstate extraction.
cleaned_eeg = nk.microstates_clean(eeg_data, sampling_rate=250)
Preprocessing steps:
Rationale:
Identify GFP peaks for microstate analysis.
peak_indices = nk.microstates_peaks(eeg_data, sampling_rate=250)
Purpose:
Returns:
Compute temporal properties of individual microstates.
static_metrics = nk.microstates_static(microstates)
Metrics:
Returns:
Interpretation:
Analyze transition patterns between microstates.
dynamic_metrics = nk.microstates_dynamic(microstates)
Metrics:
Returns:
Use cases:
Visualize microstate topographies and time course.
nk.microstates_plot(microstates, eeg_data)
Displays:
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 datasetConvert MNE objects to NeuroKit-compatible formats.
df = nk.mne_to_df(raw)
data_dict = nk.mne_to_dict(epochs)
Use case:
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')
Trim recordings by time or samples.
cropped = nk.mne_crop(raw, tmin=10, tmax=100)
Provide template anatomy for source localization.
subjects_dir = nk.mne_templateMRI()
Use case:
Generate synthetic EEG signals for testing.
synthetic_eeg = nk.eeg_simulate(duration=60, sampling_rate=250, n_channels=32)
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)
Cognitive neuroscience:
Clinical populations:
Consciousness research:
Neurofeedback: