@brainpilot/skills 0.0.6

package/skills/05_EEG_ERP/mne-python-guide/references/preprocessing.md

@@ -0,0 +1,259 @@
+# Preprocessing Reference
+
+## Table of Contents
+1. [Filtering](#filtering)
+2. [ICA Artifact Removal](#ica-artifact-removal)
+3. [Automated Artifact Detection](#automated-artifact-detection)
+4. [Bad Channel Handling](#bad-channel-handling)
+5. [Re-referencing](#re-referencing)
+6. [Maxwell Filtering (MEG)](#maxwell-filtering-meg)
+7. [Current Source Density (CSD)](#current-source-density)
+8. [EOG/ECG Processing](#eogecg-processing)
+9. [fNIRS Preprocessing](#fnirs-preprocessing)
+10. [iEEG Preprocessing](#ieeg-preprocessing)
+11. [Eye-tracking Preprocessing](#eye-tracking-preprocessing)
+12. [Annotations](#annotations)
+
+## Filtering
+
+```python
+# Bandpass
+raw.filter(l_freq=0.1, h_freq=40.)       # ERP standard (Luck, 2014)
+raw.filter(l_freq=1., h_freq=100.)        # time-frequency / ICA fitting
+
+# Highpass only
+raw.filter(l_freq=1., h_freq=None)
+
+# Lowpass only
+raw.filter(l_freq=None, h_freq=40.)
+
+# Notch filter (line noise)
+raw.notch_filter(freqs=[50, 100, 150])    # 50 Hz regions
+raw.notch_filter(freqs=[60, 120, 180])    # 60 Hz regions
+
+# Key parameters
+raw.filter(l_freq=0.1, h_freq=40.,
+           method='fir',           # 'fir' (default) or 'iir'
+           fir_design='firwin',    # 'firwin' (default) or 'firwin2'
+           phase='zero',           # 'zero' (default), 'zero-double', 'minimum'
+           l_trans_bandwidth=0.1,  # transition bandwidth (Hz)
+           h_trans_bandwidth=10.)
+```
+
+## ICA Artifact Removal
+
+```python
+# Initialize
+ica = mne.preprocessing.ICA(
+    n_components=20,       # int or float (0-1 for variance explained)
+    method='fastica',      # 'fastica' (default), 'picard', 'infomax'
+    random_state=97,
+    max_iter=800           # or 'auto'
+)
+
+# Fit (on 1 Hz highpass filtered data)
+filt_raw = raw.copy().filter(l_freq=1., h_freq=None)
+ica.fit(filt_raw)
+# or: ica.fit(epochs)  # can also fit on epochs
+
+# Automatic artifact detection
+eog_idx, eog_scores = ica.find_bads_eog(raw)
+ecg_idx, ecg_scores = ica.find_bads_ecg(raw, method='correlation', threshold='auto')
+muscle_idx, muscle_scores = ica.find_bads_muscle(raw)
+
+# Visual inspection
+ica.plot_components()                          # topographies of all components
+ica.plot_sources(raw)                          # time courses
+ica.plot_properties(raw, picks=eog_idx)        # detailed per-component view
+ica.plot_scores(eog_scores)                    # correlation scores
+ica.plot_overlay(raw, exclude=eog_idx)         # before/after overlay
+
+# Apply
+ica.exclude = eog_idx + ecg_idx
+ica.apply(raw)  # modifies in-place
+
+# Save/load
+ica.save('my-ica.fif')
+ica = mne.preprocessing.read_ica('my-ica.fif')
+
+# Cross-subject template matching
+from mne.preprocessing import corrmap
+corrmap(icas_list, template=(0, eog_idx[0]), threshold=0.9, label='blink')
+```
+
+## Automated Artifact Detection
+
+```python
+# Annotate high-amplitude segments
+annot, bads = mne.preprocessing.annotate_amplitude(
+    raw, peak=dict(eeg=200e-6), flat=dict(eeg=1e-6))
+raw.set_annotations(raw.annotations + annot)
+
+# Annotate muscle artifacts
+annot, scores = mne.preprocessing.annotate_muscle_zscore(
+    raw, threshold=5, ch_type='eeg')
+
+# Annotate breaks in recording
+annot = mne.preprocessing.annotate_break(raw, min_break_duration=15.)
+
+# Annotate movement (MEG with cHPI)
+annot = mne.preprocessing.annotate_movement(raw, pos, rotation_velocity_limit=5.)
+
+# Detect bad channels (Local Outlier Factor)
+bads, scores = mne.preprocessing.find_bad_channels_lof(raw)
+
+# Detect bad channels (Maxwell filtering, MEG only)
+noisy, flat = mne.preprocessing.find_bad_channels_maxwell(raw)
+```
+
+## Bad Channel Handling
+
+```python
+# Mark bad channels
+raw.info['bads'] = ['EEG 053', 'MEG 2443']
+raw.info['bads'].extend(['EEG 001'])
+
+# Interpolate
+raw.interpolate_bads()  # spherical spline for EEG, field interpolation for MEG
+
+# Detect bridged electrodes
+bridged, ed_matrix = mne.preprocessing.compute_bridged_electrodes(raw)
+mne.preprocessing.interpolate_bridged_electrodes(raw, bridged)
+
+# Equalize bad channels across subjects (for group analysis)
+mne.preprocessing.equalize_bads(raws_list)
+```
+
+## Re-referencing
+
+```python
+# Average reference
+raw.set_eeg_reference('average')
+
+# Specific channels
+raw.set_eeg_reference(['M1', 'M2'])       # mastoid reference
+raw.set_eeg_reference(['TP9', 'TP10'])     # linked earlobes
+
+# REST reference (Reference Electrode Standardization Technique)
+raw.set_eeg_reference('REST', forward=fwd)
+
+# Projection-based (add as projector, don't modify data)
+raw.set_eeg_reference('average', projection=True)
+```
+
+## Maxwell Filtering (MEG)
+
+Signal Space Separation for MEG denoising:
+
+```python
+raw_sss = mne.preprocessing.maxwell_filter(
+    raw,
+    origin='auto',          # head origin
+    int_order=8,            # internal expansion order
+    ext_order=3,            # external expansion order
+    st_duration=10.,        # tSSS buffer duration (None for SSS only)
+    st_correlation=0.98,    # tSSS correlation threshold
+    coord_frame='head',     # coordinate frame
+    calibration=cal_fname,  # fine calibration file
+    cross_talk=ct_fname     # cross-talk correction file
+)
+
+# Prepare empty room data for noise covariance
+raw_er = mne.preprocessing.maxwell_filter_prepare_emptyroom(raw_er, raw)
+```
+
+## Current Source Density
+
+Surface Laplacian for EEG:
+
+```python
+raw_csd = mne.preprocessing.compute_current_source_density(raw)
+epochs_csd = mne.preprocessing.compute_current_source_density(epochs)
+```
+
+## EOG/ECG Processing
+
+```python
+# Create artifact epochs
+eog_epochs = mne.preprocessing.create_eog_epochs(raw, ch_name='EOG 061')
+ecg_epochs = mne.preprocessing.create_ecg_epochs(raw)
+
+# Find events
+eog_events = mne.preprocessing.find_eog_events(raw)
+ecg_events = mne.preprocessing.find_ecg_events(raw)
+
+# SSP projectors
+projs_eog, _ = mne.preprocessing.compute_proj_eog(raw, n_eeg=1)
+projs_ecg, _ = mne.preprocessing.compute_proj_ecg(raw, n_eeg=1)
+raw.add_proj(projs_eog + projs_ecg)
+raw.apply_proj()
+
+# EOG regression (alternative to ICA)
+model = mne.preprocessing.EOGRegression(picks='eeg', picks_artifact='eog')
+model.fit(raw)
+raw_clean = model.apply(raw)
+```
+
+## fNIRS Preprocessing
+
+```python
+from mne.preprocessing.nirs import (
+    optical_density, beer_lambert_law, scalp_coupling_index,
+    short_channel_regression, temporal_derivative_distribution_repair
+)
+
+# Convert to optical density
+raw_od = optical_density(raw)
+
+# Scalp coupling index (quality metric)
+sci = scalp_coupling_index(raw_od)
+raw_od.info['bads'] = [ch for ci, ch in zip(sci, raw_od.ch_names) if ci < 0.5]
+
+# Short channel regression
+raw_od = short_channel_regression(raw_od)
+
+# Convert to hemoglobin concentration
+raw_haemo = beer_lambert_law(raw_od, ppf=0.1)
+
+# TDDR (motion artifact correction)
+raw_haemo = temporal_derivative_distribution_repair(raw_haemo)
+```
+
+## iEEG Preprocessing
+
+```python
+from mne.preprocessing.ieeg import project_sensors_onto_brain
+
+# Project electrode contacts onto brain surface
+pos_corrected = project_sensors_onto_brain(
+    info, trans, subject, subjects_dir=subjects_dir)
+```
+
+## Eye-tracking Preprocessing
+
+```python
+from mne.preprocessing.eyetracking import (
+    read_eyelink_calibration, interpolate_blinks, set_channel_types_eyetrack
+)
+
+cals = read_eyelink_calibration(raw_et)
+raw_et = interpolate_blinks(raw_et, buffer=(0.05, 0.2))
+```
+
+## Annotations
+
+```python
+# Add annotations
+raw.annotations.append(onset=5.0, duration=1.0, description='bad_segment')
+
+# Read/write
+annot = mne.read_annotations('annotations.fif')
+raw.set_annotations(annot)
+raw.annotations.save('annotations.fif')
+
+# Mark bad segments interactively
+raw.plot()  # click and drag to mark bad segments
+
+# Convert annotations to events
+events, event_id = mne.events_from_annotations(raw)
+```

package/skills/05_EEG_ERP/mne-python-guide/references/simulation.md

@@ -0,0 +1,173 @@
+# Simulation Reference
+
+## Table of Contents
+1. [Creating Objects from Arrays](#from-arrays)
+2. [Simulating Source Activity](#source-activity)
+3. [Simulating Raw Data](#raw-data)
+4. [Simulating Evoked Responses](#evoked)
+5. [Adding Artifacts](#artifacts)
+6. [Adding Noise](#noise)
+7. [SourceSimulator Class](#source-simulator)
+8. [Simulation Metrics](#metrics)
+
+## Creating Objects from Arrays
+
+```python
+import mne
+import numpy as np
+
+# Create Info
+info = mne.create_info(ch_names=['Fz', 'Cz', 'Pz'], sfreq=256., ch_types='eeg')
+info.set_montage('standard_1020')
+
+# RawArray
+data = np.random.randn(3, 10000)  # (n_channels, n_times)
+raw = mne.io.RawArray(data, info)
+
+# EpochsArray
+epochs_data = np.random.randn(50, 3, 128)  # (n_epochs, n_channels, n_times)
+events = np.column_stack([np.arange(0, 50*128, 128), np.zeros(50, int), np.ones(50, int)])
+epochs = mne.EpochsArray(epochs_data, info, events, tmin=-0.2, event_id={'stim': 1})
+
+# EvokedArray
+evoked_data = np.random.randn(3, 128)  # (n_channels, n_times)
+evoked = mne.EvokedArray(evoked_data, info, tmin=-0.2)
+```
+
+## Simulating Source Activity
+
+```python
+from mne.simulation import simulate_stc, simulate_sparse_stc
+
+# Dense source simulation
+stc = simulate_stc(src, labels=[label_lh, label_rh],
+                    stc_data=np.array([[1, 1, 0], [0, 1, 1]]),
+                    tmin=0, tstep=1./info['sfreq'])
+
+# Sparse source simulation (few active dipoles)
+stc = simulate_sparse_stc(src, n_dipoles=2, times=times,
+    data_fun=lambda t: 1e-9 * np.sin(20 * 2 * np.pi * t))
+
+# Select source in label
+from mne.simulation import select_source_in_label
+lh_vertno, rh_vertno = select_source_in_label(src, label, location='center')
+```
+
+## Simulating Raw Data
+
+```python
+from mne.simulation import simulate_raw, SourceSimulator
+
+# Simple: from source time course + forward model
+raw_sim = simulate_raw(info, stc=stc, forward=fwd)
+
+# Complex: using SourceSimulator
+source_sim = SourceSimulator(src, tstep=1./info['sfreq'])
+source_sim.add_data(label, waveform, events)
+raw_sim = simulate_raw(info, source_sim, forward=fwd)
+```
+
+## Simulating Evoked Responses
+
+```python
+from mne.simulation import simulate_evoked
+
+evoked_sim = simulate_evoked(fwd, stc, info,
+                              cov=noise_cov,   # noise covariance
+                              nave=100,         # number of averages
+                              random_state=42)
+```
+
+## Adding Artifacts
+
+```python
+from mne.simulation import add_ecg, add_eog
+
+# Add heartbeat artifact
+raw_sim = add_ecg(raw_sim)
+
+# Add eye blink artifact
+raw_sim = add_eog(raw_sim)
+
+# Add cHPI signals (MEG)
+from mne.simulation import add_chpi
+raw_sim = add_chpi(raw_sim, head_pos=head_pos)
+```
+
+## Adding Noise
+
+```python
+from mne.simulation import add_noise
+
+# From covariance
+add_noise(raw_sim, cov=noise_cov, random_state=42)
+add_noise(evoked_sim, cov=noise_cov, random_state=42)
+
+# Ad-hoc covariance
+cov = mne.make_ad_hoc_cov(info)
+add_noise(raw_sim, cov, random_state=42)
+```
+
+## SourceSimulator Class
+
+For complex experimental designs with multiple conditions:
+
+```python
+from mne.simulation import SourceSimulator
+
+source_sim = SourceSimulator(src, tstep=1./info['sfreq'])
+
+# Add condition 1: auditory in left hemisphere
+waveform_aud = 1e-9 * np.sin(2 * np.pi * 10 * times)
+source_sim.add_data(label_auditory, waveform_aud, events_aud)
+
+# Add condition 2: visual in right hemisphere
+waveform_vis = 1e-9 * np.cos(2 * np.pi * 15 * times)
+source_sim.add_data(label_visual, waveform_vis, events_vis)
+
+# Get source estimate
+stc = source_sim.get_stc()
+
+# Get stimulus channel
+stim_data = source_sim.get_stim_channel()
+
+# Properties
+source_sim.duration
+source_sim.n_times
+
+# Generate raw
+raw_sim = simulate_raw(info, source_sim, forward=fwd)
+```
+
+## Simulation Metrics
+
+Compare simulated ground truth with estimated source activity:
+
+```python
+from mne.simulation.metrics import (
+    cosine_score,
+    region_localization_error,
+    f1_score,
+    precision_score,
+    recall_score,
+    roc_auc_score,
+    spatial_deviation_error,
+    peak_position_error
+)
+
+# Cosine similarity (0=orthogonal, 1=identical)
+score = cosine_score(stc_true, stc_estimated)
+
+# Region localization error (mm)
+rle = region_localization_error(stc_true, stc_estimated, src)
+
+# Classification metrics (after binarization)
+f1 = f1_score(stc_true, stc_estimated, threshold='90%')
+prec = precision_score(stc_true, stc_estimated, threshold='90%')
+rec = recall_score(stc_true, stc_estimated, threshold='90%')
+auc = roc_auc_score(stc_true, stc_estimated)
+
+# Spatial spread metrics
+sd = spatial_deviation_error(stc_true, stc_estimated, src, threshold='50%')
+ppe = peak_position_error(stc_true, stc_estimated, src)
+```

package/skills/05_EEG_ERP/mne-python-guide/references/source_localization.md

@@ -0,0 +1,234 @@
+# Source Localization Reference
+
+## Table of Contents
+1. [Source Space Setup](#source-space)
+2. [BEM Model](#bem)
+3. [Forward Solution](#forward)
+4. [Noise Covariance](#noise-covariance)
+5. [Minimum Norm Estimates](#minimum-norm)
+6. [Beamformers](#beamformers)
+7. [Dipole Fitting](#dipole-fitting)
+8. [Template MRI (fsaverage)](#template-mri)
+9. [Source Estimate Operations](#stc-operations)
+
+## Source Space
+
+```python
+# Surface source space
+src = mne.setup_source_space(subject, spacing='oct6', subjects_dir=subjects_dir)
+# spacing options:
+#   'oct5' ~1026 sources/hemi, 'oct6' ~4098 (default), 'ico4' ~2562, 'ico5' ~10242
+
+# Volume source space
+src = mne.setup_volume_source_space(subject, pos=5.0, subjects_dir=subjects_dir)
+# pos: grid spacing in mm
+
+# Mixed source space (surface + volume)
+src = mne.setup_source_space(subject, spacing='oct6') + \
+      mne.setup_volume_source_space(subject, pos=5.0, volume_label='Left-Hippocampus')
+
+# Read/write
+src = mne.read_source_spaces('sample-src.fif')
+src.save('sample-src.fif')
+```
+
+## BEM
+
+```python
+# 3-layer BEM for EEG (brain, skull, scalp)
+model = mne.make_bem_model(subject, conductivity=(0.3, 0.006, 0.3),
+                            subjects_dir=subjects_dir)
+
+# 1-layer BEM for MEG only (inner skull)
+model = mne.make_bem_model(subject, conductivity=(0.3,),
+                            subjects_dir=subjects_dir)
+
+# Compute BEM solution
+bem = mne.make_bem_solution(model)
+
+# Sphere model (simpler alternative)
+sphere = mne.make_sphere_model(r0='auto', head_radius='auto', info=info)
+```
+
+## Forward Solution
+
+```python
+fwd = mne.make_forward_solution(
+    info, trans=trans, src=src, bem=bem,
+    eeg=True, meg=True, mindist=5.0, n_jobs=-1)
+
+# Read from file
+fwd = mne.read_forward_solution('sample-fwd.fif')
+
+# Convert orientation
+fwd = mne.convert_forward_solution(fwd, surf_ori=True, force_fixed=False)
+
+# Restrict to label
+fwd_label = mne.forward.restrict_forward_to_label(fwd, label)
+```
+
+## Noise Covariance
+
+```python
+# From pre-stimulus baseline epochs
+noise_cov = mne.compute_covariance(epochs, tmax=0., method='auto')
+# method: 'auto', 'empirical', 'diagonal_fixed', 'shrunk', 'oas',
+#         'ledoit_wolf', 'factor_analysis'
+
+# From empty room recording
+noise_cov = mne.compute_raw_covariance(raw_empty_room)
+
+# Ad-hoc covariance (for testing)
+noise_cov = mne.make_ad_hoc_cov(info)
+
+# Read/write
+noise_cov = mne.read_cov('sample-cov.fif')
+mne.write_cov('sample-cov.fif', noise_cov)
+
+# Visualize
+noise_cov.plot(info)
+evoked.plot_white(noise_cov)  # check whitening quality
+```
+
+## Minimum Norm Estimates
+
+```python
+from mne.minimum_norm import (
+    make_inverse_operator, apply_inverse, apply_inverse_epochs,
+    apply_inverse_raw, apply_inverse_cov, read_inverse_operator,
+    write_inverse_operator
+)
+
+# Create inverse operator
+inv = make_inverse_operator(info, fwd, noise_cov,
+                             loose=0.2,    # 0=fixed, 0.2=default, 1=free
+                             depth=0.8)    # depth weighting (0-1)
+
+# Apply to evoked
+snr = 3.0
+lambda2 = 1. / snr ** 2  # = 1/9 ≈ 0.111
+stc = apply_inverse(evoked, inv, lambda2, method='dSPM',
+                     pick_ori=None)  # None, 'normal', 'vector'
+
+# Apply to epochs (per-trial source estimates)
+stcs = apply_inverse_epochs(epochs, inv, lambda2, method='dSPM',
+                             return_generator=True)  # memory-efficient
+
+# Apply to raw (continuous)
+stc = apply_inverse_raw(raw, inv, lambda2, method='MNE')
+
+# Apply to covariance (source power)
+stc_power = apply_inverse_cov(data_cov, info, inv)
+
+# Resolution analysis
+from mne.minimum_norm import make_inverse_resolution_matrix, resolution_metrics
+rm = make_inverse_resolution_matrix(fwd, inv, method='dSPM', lambda2=lambda2)
+metrics = resolution_metrics(rm, src, function='psf', metric='peak_err')
+```
+
+## Beamformers
+
+### LCMV (time domain)
+```python
+from mne.beamformer import make_lcmv, apply_lcmv, apply_lcmv_epochs, apply_lcmv_raw
+
+data_cov = mne.compute_covariance(epochs, tmin=0., tmax=0.5)
+filters = make_lcmv(info, fwd, data_cov,
+                     noise_cov=noise_cov,
+                     reg=0.05,
+                     pick_ori='max-power')  # None, 'normal', 'max-power', 'vector'
+
+stc = apply_lcmv(evoked, filters)
+stcs = apply_lcmv_epochs(epochs, filters)
+stc = apply_lcmv_raw(raw, filters)
+```
+
+### DICS (frequency domain)
+```python
+from mne.beamformer import make_dics, apply_dics, apply_dics_csd, apply_dics_epochs
+from mne.time_frequency import csd_morlet
+
+csd = csd_morlet(epochs, freqs=[10], n_cycles=7)
+noise_csd = csd_morlet(epochs, freqs=[10], n_cycles=7, tmin=-0.5, tmax=0.)
+
+filters = make_dics(info, fwd, csd, noise_csd=noise_csd, reg=0.05)
+stc_power, freqs = apply_dics_csd(csd, filters)
+stc = apply_dics(evoked, filters)
+```
+
+### RAP-MUSIC / TRAP-MUSIC
+```python
+from mne.beamformer import rap_music, trap_music
+dipoles, residual = rap_music(evoked, fwd, noise_cov, n_dipoles=2)
+```
+
+## Dipole Fitting
+
+```python
+dip, residual = mne.fit_dipole(evoked, noise_cov, bem, trans,
+                                min_dist=5.0, n_jobs=-1)
+dip.plot_locations(trans, subject, subjects_dir)
+dip.plot_amplitudes()
+
+# Confidence volume
+dip.conf  # confidence volume in mm³
+```
+
+## Template MRI (fsaverage)
+
+For EEG studies without individual MRI:
+
+```python
+import os.path as op
+fs_dir = mne.datasets.fetch_fsaverage(verbose=True)
+subjects_dir = op.dirname(fs_dir)
+subject = 'fsaverage'
+trans = 'fsaverage'  # built-in identity transform
+
+src = mne.setup_source_space(subject, spacing='oct6', subjects_dir=subjects_dir)
+model = mne.make_bem_model(subject, subjects_dir=subjects_dir)
+bem = mne.make_bem_solution(model)
+fwd = mne.make_forward_solution(info, trans, src, bem)
+
+# Then proceed with inverse as usual
+inv = make_inverse_operator(info, fwd, noise_cov)
+stc = apply_inverse(evoked, inv, lambda2=1./9., method='dSPM')
+```
+
+## Source Estimate Operations
+
+```python
+# Visualization
+stc.plot(subject, subjects_dir=subjects_dir, hemi='both',
+         surface='inflated', views='lateral')
+brain = stc.plot(subject, hemi='split', size=(800, 400))
+brain.add_foci(vertex_id, hemi='rh', color='yellow')
+brain.save_image('brain.png')
+
+# Peak detection
+vertex, time_idx = stc.get_peak(hemi='rh', tmin=0.05, tmax=0.15)
+
+# Time operations
+stc.crop(tmin=0., tmax=0.3)
+stc_mean = stc.mean()
+
+# ROI extraction
+label = mne.read_label('lh.V1.label')
+stc_label = stc.in_label(label)
+
+# Extract label time courses
+labels = mne.read_labels_from_annot(subject, parc='aparc', subjects_dir=subjects_dir)
+label_ts = mne.extract_label_time_course(stcs, labels, src,
+                                          mode='mean_flip')  # 'mean', 'mean_flip',
+                                                              # 'pca_flip', 'max'
+
+# Morphing between subjects
+morph = mne.compute_source_morph(stc, subject_from='sample',
+                                  subject_to='fsaverage',
+                                  subjects_dir=subjects_dir)
+stc_fsaverage = morph.apply(stc)
+
+# Arithmetic
+stc_diff = stc1 - stc2
+stc_scaled = stc * 1e9
+```