@brainpilot/skills 0.0.6

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

@@ -0,0 +1,196 @@
+# Statistics Reference
+
+## Table of Contents
+1. [Cluster-Based Permutation Tests](#cluster-permutation)
+2. [Spatio-Temporal Cluster Tests](#spatio-temporal)
+3. [TFCE](#tfce)
+4. [Adjacency Matrices](#adjacency)
+5. [Parametric Tests](#parametric)
+6. [Multiple Comparison Correction](#correction)
+7. [Linear Regression](#regression)
+8. [ERP Quality Metrics](#erp-quality)
+9. [Source Space Statistics](#source-stats)
+
+## Cluster-Based Permutation Tests
+
+Controls for multiple comparisons by clustering neighboring significant samples (Maris & Oostenveld, 2007):
+
+```python
+from mne.stats import permutation_cluster_test, permutation_cluster_1samp_test
+
+# Two-sample test (comparing two conditions)
+T_obs, clusters, p_values, H0 = permutation_cluster_test(
+    [X1, X2],               # list of arrays, shape (n_obs, n_times)
+    n_permutations=1000,
+    tail=0,                  # 0=two-tailed, 1=right, -1=left
+    threshold=None,          # None=auto, float, or dict for TFCE
+    out_type='mask'          # 'mask' or 'indices'
+)
+
+# One-sample test (against zero)
+T_obs, clusters, p_values, H0 = permutation_cluster_1samp_test(
+    X,                       # shape (n_obs, n_times)
+    n_permutations=1000,
+    tail=0
+)
+
+# Find significant clusters
+good_clusters = [clusters[i] for i in range(len(clusters)) if p_values[i] < 0.05]
+```
+
+## Spatio-Temporal Cluster Tests
+
+For data with both spatial and temporal dimensions:
+
+```python
+from mne.stats import spatio_temporal_cluster_test, spatio_temporal_cluster_1samp_test
+
+# Build adjacency matrix
+adjacency, ch_names = mne.channels.find_ch_adjacency(epochs.info, 'eeg')
+
+# Data shape: (n_obs, n_times, n_channels) — NOTE: time BEFORE channels!
+X1 = cond1_epochs.get_data().transpose(0, 2, 1)  # transpose from (obs, ch, time)
+X2 = cond2_epochs.get_data().transpose(0, 2, 1)
+
+# Two-sample
+T_obs, clusters, p_values, H0 = spatio_temporal_cluster_test(
+    [X1, X2], adjacency=adjacency, n_permutations=1000)
+
+# One-sample
+T_obs, clusters, p_values, H0 = spatio_temporal_cluster_1samp_test(
+    X, adjacency=adjacency, n_permutations=1000)
+```
+
+## TFCE
+
+Threshold-Free Cluster Enhancement — avoids arbitrary cluster-forming threshold:
+
+```python
+tfce = dict(start=0.4, step=0.4)  # TFCE parameters
+T_obs, clusters, p_values, H0 = spatio_temporal_cluster_test(
+    [X1, X2], tfce, adjacency=adjacency, n_permutations=100)
+```
+
+## Adjacency Matrices
+
+```python
+# From channel layout (most common)
+adjacency, ch_names = mne.channels.find_ch_adjacency(info, ch_type='eeg')
+# or from template: adjacency, ch_names = mne.channels.read_ch_adjacency('biosemi64')
+
+# Distance-based
+adjacency = mne.spatial_dist_adjacency(info, dist=0.04)
+
+# Source space
+adjacency = mne.spatial_src_adjacency(src)
+adjacency = mne.spatio_temporal_src_adjacency(src, n_times)
+
+# Triangulation-based
+adjacency = mne.spatial_tris_adjacency(tris)
+
+# Inter-hemisphere
+adjacency = mne.spatial_inter_hemi_adjacency(src, max_dist=0.04)
+
+# Combine for multi-dimensional data (time × freq × space)
+adjacency = mne.stats.combine_adjacency(n_times, n_freqs, ch_adjacency)
+
+# Visualize
+mne.viz.plot_ch_adjacency(info, adjacency, ch_names)
+```
+
+## Parametric Tests
+
+```python
+from mne.stats import (f_oneway, f_mway_rm, f_threshold_mway_rm,
+                        ttest_1samp_no_p, ttest_ind_no_p)
+
+# One-way ANOVA
+F_obs, p_values = f_oneway(X1, X2, X3)
+
+# Repeated measures ANOVA
+F_obs, p_values = f_mway_rm(data, factor_levels=[2, 3], effects='A*B')
+# effects: 'A', 'B', 'A:B', 'A*B' (main + interaction)
+
+# Get F-threshold for cluster test
+threshold = f_threshold_mway_rm(n_subjects, factor_levels=[2, 3],
+                                 effects='A*B', pvalue=0.05)
+
+# T-tests (return t-statistic only, no p-value — for use as cluster threshold)
+t_obs = ttest_1samp_no_p(X)
+t_obs = ttest_ind_no_p(X1, X2)
+```
+
+## Multiple Comparison Correction
+
+```python
+from mne.stats import bonferroni_correction, fdr_correction
+
+# Bonferroni
+reject_bonf, pval_bonf = bonferroni_correction(p_values, alpha=0.05)
+
+# FDR (Benjamini-Hochberg)
+reject_fdr, pval_fdr = fdr_correction(p_values, alpha=0.05, method='indep')
+# method: 'indep' (Benjamini-Hochberg) or 'negcorr' (Benjamini-Yekutieli)
+
+# Permutation t-test with t-max correction
+from mne.stats import permutation_t_test
+T_obs, p_values, H0 = permutation_t_test(X, n_permutations=10000, tail=0)
+```
+
+## Linear Regression
+
+### On Epochs (with metadata)
+```python
+from mne.stats import linear_regression
+
+# epochs.metadata must be a pandas DataFrame
+results = linear_regression(epochs, design_matrix, names=['intercept', 'condition'])
+results['condition'].beta.plot_joint()   # regression coefficients as evoked
+results['condition'].t_val.plot_joint()  # t-values
+results['condition'].p_val               # p-values
+```
+
+### On Raw (continuous regression, overlap correction)
+```python
+from mne.stats import linear_regression_raw
+
+results = linear_regression_raw(
+    raw, events, event_id={'stim': 1, 'resp': 2},
+    tmin=-0.1, tmax=1.0,
+    covariates=None,       # dict-like for continuous predictors
+    reject=dict(eeg=100e-6),
+    decim=10               # important for high sfreq data!
+)
+# Returns dict of Evoked-like objects, one per condition
+results['stim'].plot()
+```
+
+## ERP Quality Metrics
+
+```python
+from mne.stats.erp import compute_sme
+
+# Standardized Measurement Error
+sme = compute_sme(epochs)  # returns Evoked-like object
+sme.plot()
+```
+
+## Source Space Statistics
+
+```python
+from mne.stats import summarize_clusters_stc
+
+# Visualize significant source-space clusters
+stc_cluster = summarize_clusters_stc(
+    clu,                    # output from cluster test
+    tstep=tstep,
+    vertices=vertices,
+    subject='fsaverage'
+)
+stc_cluster.plot(subject='fsaverage', subjects_dir=subjects_dir)
+
+# Bootstrap confidence intervals
+from mne.stats import bootstrap_confidence_interval
+ci = bootstrap_confidence_interval(data, ci=0.95, n_bootstraps=2000,
+                                    stat_fun='mean')
+```

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

@@ -0,0 +1,165 @@
+# Time-Frequency Analysis Reference
+
+## Table of Contents
+1. [Power Spectral Density (PSD)](#psd)
+2. [Time-Frequency Representations (TFR)](#tfr)
+3. [Cross-Spectral Density (CSD)](#csd)
+4. [Array-Level Functions](#array-level)
+5. [Baseline Correction Modes](#baseline-modes)
+6. [Parameter Selection Guide](#parameter-guide)
+
+## PSD
+
+```python
+# New API (recommended)
+psd = raw.compute_psd(method='welch', fmin=0.5, fmax=50.)
+psd = raw.compute_psd(method='multitaper', fmin=0.5, fmax=50.)
+psd = epochs.compute_psd(method='multitaper')
+
+# Plotting
+psd.plot()                              # PSD curves
+psd.plot_topomap(normalize=True)        # topographic PSD
+psd.plot_topo()                         # per-channel in layout
+
+# Array-level
+from mne.time_frequency import psd_array_welch, psd_array_multitaper
+psds, freqs = psd_array_welch(data, sfreq, fmin=0.5, fmax=50., n_fft=256)
+psds, freqs = psd_array_multitaper(data, sfreq, fmin=0.5, fmax=50., bandwidth=4.)
+```
+
+## TFR
+
+### New API (recommended)
+```python
+import numpy as np
+freqs = np.arange(4, 30, 2)
+
+# Morlet wavelets
+power = epochs.compute_tfr(method="morlet", freqs=freqs, n_cycles=freqs / 2.,
+                           average=True, return_itc=True, decim=3)
+
+# Multitaper (better frequency resolution)
+power = epochs.compute_tfr(method="multitaper", freqs=freqs,
+                           n_cycles=freqs / 2., time_bandwidth=4.0)
+
+# Stockwell transform (adaptive resolution)
+power = epochs.compute_tfr(method="stockwell", fmin=6, fmax=35)
+
+# Per-epoch TFR (no averaging)
+power_epochs = epochs.compute_tfr(method="morlet", freqs=freqs,
+                                   n_cycles=freqs / 2., average=False)
+```
+
+### Inter-Trial Coherence (ITC)
+```python
+power, itc = epochs.compute_tfr(method="morlet", freqs=freqs,
+                                 n_cycles=freqs / 2., return_itc=True)
+# ITC ranges from 0 (no phase consistency) to 1 (perfect phase locking)
+```
+
+### TFR Visualization
+```python
+power.plot(picks='Cz', baseline=(-0.5, 0), mode='logratio')  # single channel
+power.plot_topo(baseline=(-0.5, 0), mode='logratio')          # all channels
+power.plot_topomap(tmin=0.1, tmax=0.3, fmin=8, fmax=12)       # time-freq window
+power.plot_joint(baseline=(-0.5, 0), mode='mean')              # TFR + topomaps
+```
+
+### Legacy API (still works but deprecated)
+```python
+from mne.time_frequency import tfr_morlet, tfr_multitaper, tfr_stockwell
+power, itc = tfr_morlet(epochs, freqs, n_cycles)
+power = tfr_multitaper(epochs, freqs, n_cycles, time_bandwidth=4.0)
+power = tfr_stockwell(epochs, fmin=6, fmax=35)
+```
+
+## CSD
+
+Cross-spectral density for beamformer source localization:
+
+```python
+from mne.time_frequency import csd_morlet, csd_multitaper, csd_fourier, csd_tfr
+
+# From epochs
+csd = csd_morlet(epochs, freqs=[10, 20], n_cycles=7)
+csd = csd_multitaper(epochs, fmin=7, fmax=30, bandwidth=4.)
+csd = csd_fourier(epochs, fmin=7, fmax=30)
+
+# From TFR
+csd = csd_tfr(epochs_tfr)
+
+# Array-level
+from mne.time_frequency import csd_array_morlet, csd_array_multitaper, csd_array_fourier
+csd = csd_array_morlet(data, sfreq, freqs)
+```
+
+## Array-Level Functions
+
+For working directly with numpy arrays:
+
+```python
+from mne.time_frequency import (
+    tfr_array_morlet, tfr_array_multitaper, tfr_array_stockwell,
+    morlet, dpss_windows, fwhm, stft, istft, stftfreq
+)
+
+# TFR on arrays — data shape: (n_epochs, n_channels, n_times)
+out = tfr_array_morlet(data, sfreq, freqs, n_cycles,
+                        output='power')  # 'complex', 'power', 'phase',
+                                         # 'avg_power', 'itc', 'avg_power_itc'
+
+out = tfr_array_multitaper(data, sfreq, freqs, n_cycles, time_bandwidth=4.0)
+out = tfr_array_stockwell(data, sfreq, fmin=6, fmax=35)
+
+# Generate wavelets
+Ws = morlet(sfreq=256., freqs=[10, 20], n_cycles=7)
+
+# DPSS tapers
+tapers, eigenvalues = dpss_windows(N=256, half_nbw=4, Kmax=3)
+
+# FWHM of Morlet wavelet (Cohen, 2019)
+width = fwhm(freq=10., n_cycles=7)
+
+# Short-time Fourier transform
+X = stft(data, wsize=256, tstep=128)
+x_reconstructed = istft(X, tstep=128)
+freqs = stftfreq(wsize=256, sfreq=256.)
+```
+
+## Baseline Correction Modes
+
+```python
+power.apply_baseline(baseline=(-0.5, 0), mode='logratio')
+```
+
+| Mode | Formula | Use case |
+|------|---------|----------|
+| `'mean'` | data - mean | Subtract baseline mean |
+| `'ratio'` | data / mean | Ratio to baseline |
+| `'logratio'` | log(data / mean) | dB-like, symmetric, most common |
+| `'percent'` | (data - mean) / mean × 100 | Percent change |
+| `'zscore'` | (data - mean) / std | Z-score normalization |
+| `'zlogratio'` | (log(data) - log(mean)) / std(log) | Z-score of log ratio |
+
+## Parameter Selection Guide
+
+### n_cycles
+- Lower values → better time resolution, worse frequency resolution
+- Higher values → better frequency resolution, worse time resolution
+- `n_cycles = freqs / 2.` — adaptive heuristic (common default)
+- `n_cycles = 7` — fixed, good for narrow-band analysis
+
+### time_bandwidth (multitaper only)
+- Controls number of tapers: `n_tapers = int(time_bandwidth - 1)`
+- Higher → smoother estimate, more frequency smoothing
+- Default: 4.0 (gives 3 tapers)
+
+### decim
+- Decimation factor applied after TFR computation
+- Reduces output size and speeds up computation
+- Set to avoid aliasing (decim should not exceed Nyquist for your frequency range)
+
+### Choosing method
+- **Morlet**: Good general-purpose, adjustable time-frequency tradeoff
+- **Multitaper**: Better for narrow-band, reduces spectral leakage
+- **Stockwell**: Adaptive resolution, no n_cycles parameter needed

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

@@ -0,0 +1,175 @@
+# Visualization Reference
+
+## Table of Contents
+1. [Raw Data](#raw)
+2. [Epochs](#epochs)
+3. [Evoked](#evoked)
+4. [Topomaps](#topomaps)
+5. [Time-Frequency](#tfr)
+6. [Source Estimates](#source)
+7. [ICA](#ica)
+8. [Sensors and Layout](#sensors)
+9. [Publication Figures](#publication)
+10. [Report Generation](#report)
+11. [3D Backend](#3d-backend)
+
+## Raw Data
+
+```python
+raw.plot(duration=5, n_channels=30, scalings='auto')  # interactive browser
+raw.compute_psd(fmax=50).plot()                         # PSD curves
+raw.compute_psd().plot_topomap(normalize=True)          # PSD topomap
+raw.plot_sensors(show_names=True)                       # sensor positions
+raw.plot_sensors(kind='3d')                             # 3D sensor positions
+```
+
+## Epochs
+
+```python
+epochs.plot(n_epochs=20, n_channels=20)     # interactive (click to mark bad)
+epochs.plot_image(picks='eeg')               # ERP image (trials × time heatmap)
+epochs.plot_drop_log()                       # rejection statistics
+epochs.plot_topo_image()                     # topographic image
+```
+
+## Evoked
+
+```python
+evoked.plot()                                           # butterfly plot
+evoked.plot_joint()                                     # butterfly + topomaps at peaks
+evoked.plot_topomap(times=[0.1, 0.2, 0.3])             # scalp topographies
+evoked.plot_image()                                     # channels × time heatmap
+evoked.plot_topo()                                      # per-channel in layout
+evoked.plot_white(noise_cov)                            # whitened (check noise model)
+
+# Compare conditions
+mne.viz.plot_compare_evokeds(
+    {'auditory': evoked_aud, 'visual': evoked_vis},
+    picks='Cz', ci=0.95)
+
+# Field maps
+maps = mne.make_field_map(evoked, trans, subject, subjects_dir)
+mne.viz.plot_evoked_field(evoked, maps)
+```
+
+## Topomaps
+
+```python
+# Generic topomap from array
+mne.viz.plot_topomap(data, info,
+                      cmap='RdBu_r',
+                      vlim=(-3, 3),
+                      contours=6,
+                      sensors=True,
+                      show_names=False,
+                      mask=significant_channels,
+                      outlines='head')
+```
+
+## Time-Frequency
+
+```python
+power.plot(picks='Cz', baseline=(-0.5, 0), mode='logratio')  # single channel
+power.plot_topo(baseline=(-0.5, 0), mode='logratio')          # all channels
+power.plot_topomap(tmin=0.1, tmax=0.3, fmin=8, fmax=12)       # time-freq window
+power.plot_joint(baseline=(-0.5, 0), mode='mean')              # TFR + topomaps
+```
+
+## Source Estimates
+
+```python
+# 3D brain (requires PyVista)
+stc.plot(subject, subjects_dir=subjects_dir, hemi='both',
+         surface='inflated', views='lateral', time_viewer=True)
+
+# Split view
+brain = stc.plot(subject, hemi='split', size=(800, 400),
+                  views='lateral', surface='inflated')
+
+# Add markers
+brain.add_foci(vertex_id, hemi='rh', color='yellow')
+brain.add_text(0.1, 0.9, 'Peak activation', font_size=14)
+
+# Save screenshot
+brain.save_image('brain.png')
+
+# Volume source estimates
+mne.viz.plot_volume_source_estimates(stc_vol, src,
+                                      subject=subject, subjects_dir=subjects_dir)
+
+# Vector source estimates
+mne.viz.plot_vector_source_estimates(stc_vec, subject=subject)
+```
+
+## ICA
+
+```python
+ica.plot_components(picks=range(20))                    # component topographies
+ica.plot_sources(raw)                                   # component time courses
+ica.plot_properties(raw, picks=[0, 1, 2])               # detailed per-component
+ica.plot_scores(eog_scores)                             # correlation scores
+ica.plot_overlay(raw, exclude=[0, 1])                   # before/after overlay
+```
+
+## Sensors and Layout
+
+```python
+raw.plot_sensors(show_names=True, kind='topomap')       # 2D sensor map
+mne.viz.plot_montage(mne.channels.make_standard_montage('standard_1020'))
+mne.viz.plot_layout(mne.channels.find_layout(info))
+
+# Coregistration check
+mne.viz.plot_alignment(info, trans, subject, subjects_dir,
+                        surfaces=['head', 'brain'], meg='sensors', eeg='original')
+```
+
+## Publication Figures
+
+```python
+import matplotlib.pyplot as plt
+
+# Custom multi-panel figure
+fig, axes = plt.subplots(1, 3, figsize=(12, 4))
+evoked.plot_topomap(times=[0.1, 0.2, 0.3], axes=axes, show=False,
+                     colorbar=False)
+fig.savefig('figure.pdf', dpi=300, bbox_inches='tight')
+
+# Combine evoked with brain screenshot
+fig, axes = plt.subplots(2, 1, figsize=(4.5, 3),
+                          gridspec_kw=dict(height_ratios=[3, 4]))
+evoked.plot(axes=axes[0], show=False)
+axes[1].imshow(brain_screenshot)
+axes[1].axis('off')
+
+# Brain colorbar
+from mpl_toolkits.axes_grid1 import make_axes_locatable
+divider = make_axes_locatable(axes[1])
+cax = divider.append_axes('right', size='5%', pad=0.2)
+mne.viz.plot_brain_colorbar(cax, clim, colormap, label='Activation')
+```
+
+## Report Generation
+
+```python
+report = mne.Report(title='EEG Analysis')
+report.add_raw(raw, title='Raw Data', psd=True)
+report.add_epochs(epochs, title='Epochs')
+report.add_evokeds(evoked, titles=['Auditory'])
+report.add_ica(ica, title='ICA', inst=raw)
+report.add_covariance(noise_cov, info, title='Noise Covariance')
+report.add_forward(fwd, title='Forward Solution')
+report.add_inverse_operator(inv, title='Inverse Operator')
+report.add_stc(stc, title='Source Estimate',
+               subject=subject, subjects_dir=subjects_dir)
+report.save('report.html', overwrite=True, open_browser=False)
+```
+
+## 3D Backend
+
+```python
+mne.viz.set_3d_backend('pyvistaqt')    # desktop (default)
+mne.viz.set_3d_backend('notebook')      # Jupyter notebook
+
+# Browser backend for 2D plots
+mne.viz.set_browser_backend('matplotlib')  # or 'qt'
+```