@synsci/cli-darwin-x64-baseline 1.1.76 → 1.1.78

package/bin/skills/neurokit2/references/eeg.md

@@ -0,0 +1,506 @@
+# 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.
+
+```python
+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.
+
+```python
+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.
+
+```python
+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.
+
+```python
+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.
+
+```python
+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.
+
+```python
+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.
+
+```python
+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.
+
+```python
+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.
+
+```python
+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.
+
+```python
+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.
+
+```python
+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.
+
+```python
+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.
+
+```python
+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.
+
+```python
+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.
+
+```python
+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.
+
+```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.
+
+```python
+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.
+
+```python
+# 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.
+
+```python
+cropped = nk.mne_crop(raw, tmin=10, tmax=100)
+```
+
+### mne_templateMRI()
+
+Provide template anatomy for source localization.
+
+```python
+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.
+
+```python
+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:**
+```python
+# 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:**
+```python
+# 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.