neural-processing-index

name	neural-processing-index
description	Index of all L2 paradigm skills by group + analysis_goal → paradigm matrix
layer	L2
group	modality
metadata	{"tags":["index","paradigms","navigation","l2"],"analysis_goal_allowed":["classification","source_localization","feature_extraction","clinical_screening","exploratory","generic","connectivity","phase_amplitude_coupling","online_inference"],"analysis_goal_forbidden":[]}

L2 Paradigm Index — BCI Domain Knowledge

Navigation.
L0 IO formats → L1 Orchestration → L2 (this page) → L3 Operators.

This index lists every L2 paradigm skill — domain expertise for a specific modality or task. The L1 orchestrator (pipeline) loads the matching paradigm skill before generating a pipeline; the matrix at the bottom shows which paradigms suit which analysis_goal.

Load any paradigm with skill_view(name='<paradigm>').

Signal Processing Principles

Frequency Bands of Interest

Band	Range (Hz)	Function	Relevant Paradigms
Delta	0.5-4	Deep sleep, pathology	Sleep staging
Theta	4-8	Memory, attention	Cognitive BCI, emotion
Alpha/Mu	8-13	Idle sensorimotor, visual	Motor imagery, relaxation
Beta	13-30	Active motor, attention	Motor imagery, cognitive
Low Gamma	30-70	Perception, cognition	SSVEP, working memory
High Gamma	70-150	Local cortical processing	sEEG/ECoG, speech
HFO	150-500	Epileptogenic zones	Epilepsy monitoring

Modality Characteristics

Modality	Typical Sfreq	Noise Profile	Reference Scheme
Scalp EEG	256-1024 Hz	Muscle, eye, line noise	CAR or linked mastoids
sEEG	1000-2048 Hz	Low artifact, high SNR	Bipolar (adjacent contacts)
ECoG	1000-2048 Hz	Minimal muscle, some line noise	Bipolar or CAR
MEG	1000+ Hz	Environmental magnetic, no reference needed	Already reference-free
fNIRS	10-50 Hz	Motion, systemic physiology	Short-channel regression
Spike	30000 Hz	Electrode drift, crosstalk	Local reference

Quality Indicators

Metric	Good	Warning	Fail
Channel variance ratio	< 3x median	3-10x median	> 10x median
Flatline duration	0	< 1 sec	> 1 sec continuous
Line noise SNR (50/60 Hz)	< 3 dB above band	3-10 dB	> 10 dB
NaN ratio	0%	< 1%	> 1%
Amplitude range (EEG)	±100 µV	±200 µV	> ±500 µV

Paradigms by Group

modality/ — Modality skeletons (6)

Paradigm	Modalities	analysis_goal_allowed
ecog	—	classification, clinical_screening, exploratory, feature_extraction, source_localization
eeg_general	—	classification, exploratory, feature_extraction, generic, source_localization
fnirs	—	classification, exploratory, feature_extraction, generic
ieeg_depth	—	clinical_screening, connectivity, exploratory, feature_extraction, phase_amplitude_coupling
meg	—	classification, connectivity, exploratory, feature_extraction, generic, source_localization
spike_lfp	—	classification, exploratory, feature_extraction, generic

cognitive_evoked/ — Cognitive — evoked / stimulus-locked (3)

Paradigm	Modalities	analysis_goal_allowed
motor_imagery	eeg	classification, exploratory, feature_extraction, generic, online_inference, source_localization
p300_erp	eeg	classification, clinical_screening, exploratory, feature_extraction, generic
ssvep	eeg	classification, exploratory, feature_extraction, generic, online_inference

cognitive_task/ — Cognitive — task / volitional (planned)

No paradigms in this group yet — slot reserved for future skills (T2 / 03).

clinical/ — Clinical / diagnostic (3)

Paradigm	Modalities	analysis_goal_allowed
emotion_recognition	—	classification, exploratory, feature_extraction, generic
seeg_epilepsy	seeg, ecog	clinical_screening, exploratory, feature_extraction
sleep_staging	—	classification, clinical_screening, exploratory, feature_extraction

connectivity_resting/ — Connectivity / resting state (2)

Paradigm	Modalities	analysis_goal_allowed
connectivity	eeg, meg, seeg, ecog, lfp	connectivity, exploratory, feature_extraction, source_localization
phase_amplitude_coupling	eeg, seeg, ecog, lfp	exploratory, feature_extraction, phase_amplitude_coupling

online_hybrid/ — Online inference / hybrid (1)

Paradigm	Modalities	analysis_goal_allowed
online_inference	eeg, ecog, lfp	online_inference

multimodal/ — Multi-modal integration (1)

Paradigm	Modalities	analysis_goal_allowed
multimodal	—	classification, connectivity, exploratory, feature_extraction, generic, source_localization

analysis_goal → Paradigm Matrix

For each REGISTRY goal, the table lists paradigms whose frontmatter declares the goal in analysis_goal_allowed. A paradigm appears as (F) when the goal is in its analysis_goal_forbidden list instead.

analysis_goal	Recommended paradigms
classification	ecog, eeg_general, emotion_recognition, fnirs, meg, motor_imagery, multimodal, p300_erp, phase_amplitude_coupling (F), sleep_staging, spike_lfp, ssvep
source_localization	connectivity, ecog, eeg_general, emotion_recognition (F), meg, motor_imagery, multimodal, online_inference (F), spike_lfp (F), ssvep (F)
feature_extraction	connectivity, ecog, eeg_general, emotion_recognition, fnirs, ieeg_depth, meg, motor_imagery, multimodal, p300_erp, phase_amplitude_coupling, seeg_epilepsy, sleep_staging, spike_lfp, ssvep
clinical_screening	ecog, emotion_recognition (F), ieeg_depth, motor_imagery (F), p300_erp, seeg_epilepsy, sleep_staging, ssvep (F)
exploratory	connectivity, ecog, eeg_general, emotion_recognition, fnirs, ieeg_depth, meg, motor_imagery, multimodal, p300_erp, phase_amplitude_coupling, seeg_epilepsy, sleep_staging, spike_lfp, ssvep
generic	eeg_general, emotion_recognition, fnirs, meg, motor_imagery, multimodal, p300_erp, spike_lfp, ssvep
connectivity	connectivity, ieeg_depth, meg, multimodal
phase_amplitude_coupling	fnirs (F), ieeg_depth, online_inference (F), p300_erp (F), phase_amplitude_coupling
online_inference	connectivity (F), fnirs (F), ieeg_depth (F), motor_imagery, online_inference, p300_erp (F), phase_amplitude_coupling (F), seeg_epilepsy (F), sleep_staging (F), spike_lfp (F), ssvep

Step Selection Heuristics

Given a data fingerprint, use these rules to select steps:

1. Always start with: Identify and handle bad data (fill_nan if needed, then drop_bads or interpolate_bads)
2. Reference: CAR for scalp EEG (>= 16 ch), bipolar_ref for sEEG/depth
3. Line noise: Notch if PSD shows 50/60 Hz peak
4. Band limiting: Bandpass to paradigm-relevant range
5. Artifact removal: ICA for EEG if eye/cardiac artifacts present
6. Resample: If original sfreq >> needed (save computation)
7. Normalize: Scale as final step before output

Decision Framework

When uncertain about a parameter, choose based on:

1. Preservation over aggression: Keep more data; less aggressive filtering preserves neural information
2. Paradigm constraints: The downstream analysis defines what frequencies/features matter
3. Data quality drives decisions: Clean data needs less processing; noisy data needs more
4. Reproducibility: Pin ALL randomness to seed 42 — lock numpy/random at script top, pass random_state=42 to every stochastic operator (ICA, split, sampling).

Layering contract

• layer: every paradigm carries layer: L2 in frontmatter.
• group: matches the parent directory (bci/neural-processing/<group>/).
• analysis_goal_allowed/forbidden: at least one must be non-empty; values come from the 9-enum REGISTRY in easybci_lib/tools/neural_processing/preprocess/analysis_goals.py.

The layer / group enums are defined in easybci_lib/tools/neural_processing/skill_layers.py (single source of truth). Run python -m easybci_lib.tools.neural_processing._check_consistency --strict to verify the contract before merging new paradigm skills.