Modular MATLAB/EEGLAB pipeline for EEG preprocessing, artifact removal, ERP analysis, and time-frequency decomposition β designed for a three-stimulus oddball paradigm with 60-channel recordings.
This pipeline implements a complete, reproducible EEG processing workflow from raw continuous recordings to publication-ready event-related potential (ERP) and time-frequency (TF) analyses. Built as a portfolio-grade project for the Brain Signal & Image Processing (EEG) master's course, it processes data through four sequential stages with JSON-driven configuration, automated quality control, and 58 diagnostic figures per subject. The pipeline supports both single-subject within-subject averaging and grand average analysis across 25 participants.
Raw EEG (.mat)
β
βΌ
ββββββββββββββββββββββββββββββββββββββββ
β Stage 01 β Preprocessing β
β Detrend β LP/HP/Notch filters β β
β Epoch extraction β Bad channel QC β
ββββββββββββββββ¬ββββββββββββββββββββββββ
β PreprocessStep1.mat
βΌ
ββββββββββββββββββββββββββββββββββββββββ
β Stage 02 β ICA Artifact Removal β
β ICA decomposition β Component β
β classification β Reconstruction β β
β Interpolation β Average reference β
ββββββββββββββββ¬ββββββββββββββββββββββββ
β PreprocessStep2.mat
βΌ
βββββββββ΄βββββββββ
β β
βΌ βΌ
βββββββββββββββ βββββββββββββββββββ
β Stage 03 β β Stage 04 β
β ERP (WSA β β Time-Frequency β
β + GA) β β (CWT + GA) β
βββββββββββββββ βββββββββββββββββββ
- Stage 01 applies linear detrending, a cascaded IIR elliptic filter bank (lowpass at 60 Hz, highpass at 0.5 Hz, notch at 60 Hz) with zero-phase
filtfiltimplementation, extracts event-locked epochs ([-0.2, 0.8] s), and detects bad channels via adaptive neighbor-correlation thresholding. - Stage 02 performs ICA decomposition (extended Infomax), provides tri-domain diagnostic evidence (topography, spectrum, time course) for each component, reconstructs the signal with artifact components removed, interpolates bad channels via spherical splines, and applies the common average reference with CPz insertion.
- Stage 03 computes within-subject averaged ERPs for each condition (standard, target, distractor), generates topographic voltage maps, derives difference waveforms (target-standard, distractor-standard) with peak annotation, and extends all analyses to a 25-subject grand average.
- Stage 04 decomposes the signal into the time-frequency domain via CWT with complex Morlet wavelet, applies baseline normalization in dB, examines band-specific dynamics (theta, alpha, beta), and generates topographic TF evolution maps at both subject and group levels.
- JSON-driven configuration with base config + per-subject overrides and deep-merge logic
- Four-stage modular architecture with clear data contracts between stages
- IIR elliptic filter design via
ellipord/ellipwith zero-phasefiltfiltapplication - Automated bad channel detection based on spatial coherence (neighbor correlation, adaptive threshold)
- ICA with full transparency β every removed and retained component documented with topographic, spectral, and temporal evidence
- Three-stimulus oddball paradigm analysis (standard / target / distractor)
- Within-subject + grand average analysis across 25 subjects
- CWT-based time-frequency decomposition with analytic Morlet wavelet (3.125β50 Hz)
- 58 publication-ready figures per run with configurable DPI (340) and optional PDF export
- Two plot levels:
core(essential diagnostics) andreport(full portfolio set) - Comprehensive scientific reports with mathematical foundations for each stage
| Stage 01 β PSD Before/After Filtering | Stage 02 β Regional Before/After ICA |
![]() |
![]() |
| Stage 03 β GA Topographic Maps | Stage 04 β GA Time-Frequency Maps |
![]() |
![]() |
This public repository ships only lightweight sample/reference assets. Create the directories if needed, then provide the full external inputs manually under:
data/external/raw/sub-003_ses-01_task-Rest_eeg.matdata/external/raw/sub-035_ses-01_task-Rest_eeg.matdata/external/ica/matrixW_sub-003.txtdata/external/ica/matrixW_sub-035.txtdata/external/preprocessed/sub-003_PreprocessStep2.mat(optional)data/external/preprocessed/sub-035_PreprocessStep2.mat(optional)data/external/preprocessed/WSA_allsubjects.mat(optional)data/external/preprocessed/TF_Power_GA.mat(optional)
Set eeglab.path in configs/pipeline.default.json or configs/pipeline.smoke.json to your local EEGLAB installation. Public configs intentionally ship with REPLACE_WITH_LOCAL_EEGLAB_PATH.
If eeglab.path is left unchanged or unavailable, the pipeline still runs but skips topographic figures with a structured warning.
powershell -ExecutionPolicy Bypass -File scripts/validate_repo.ps1addpath('tests');
run_smoke_tests("configs/pipeline.smoke.json", "sub-035");outputs = run_pipeline("all", "sub-035", "configs/pipeline.default.json", "apply");addpath('scripts');
bundle = generate_report("sub-035", "configs/pipeline.default.json");EEG Processing Pipeline/
βββ configs/
β βββ pipeline.default.json # Full configuration (report profile)
β βββ pipeline.smoke.json # Minimal config for fast testing
β βββ subjects/ # Per-subject config overrides
β βββ ica_decisions/ # ICA component removal decisions
βββ src/
β βββ stages/
β β βββ stage01_preprocess_raw.m
β β βββ stage02_artifact_cleaning.m
β β βββ stage03_erp_wsa_ga.m
β β βββ stage04_tf_analysis.m
β βββ common/ # Shared utilities (plotting, I/O, regions)
β βββ ica/ # ICA decision application
β βββ io/ # Config loading, metrics I/O
βββ data/
β βββ external/ # Local-only raw .mat, ICA weights, GA sources
β βββ sample/ # Electrode locations, reference files
βββ outputs/
β βββ intermediate/<subject>/ # .mat checkpoint files per stage
β βββ figures/<subject>/stage0N/ # Numbered PNG/PDF figures
β βββ figures/group/stage0N/ # Grand average figures
β βββ metrics/<subject>/ # JSON metric summaries
β βββ reports/<subject>/report/ # HTML/PDF report bundles
βββ reports/
β βββ stage01/report.md # Preprocessing & Signal Conditioning
β βββ stage02/report.md # ICA-Based Artifact Removal
β βββ stage03/report.md # Event-Related Potential Analysis
β βββ stage04/report.md # Time-Frequency Analysis
βββ scripts/ # Report generation, validation
βββ tests/ # Smoke tests, regression, plotting contracts
βββ run_pipeline.m # Main orchestrator
The pipeline is fully parameterized via JSON configuration files:
- Base config (
configs/pipeline.default.json): defines all processing parameters β filter specifications, epoch windows, ICA settings, ERP/TF analysis options, plot styling, and export settings. - Subject overrides (
configs/subjects/sub-*.json): per-subject parameter adjustments, deep-merged with the base config at load time. - ICA decisions (
configs/ica_decisions/sub-*.json): component removal lists and bad channel indices for each subject. - Plot level (
outputs.plot_level):"core"for essential diagnostics only,"report"for the full set of 58 portfolio figures.
Configuration loading is handled by src/io/load_pipeline_config.m, which performs deep merge, default injection, and path resolution.
Detailed scientific reports with mathematical foundations, figure captions, and theoretical context are available for each pipeline stage:
| Report | Content | Figures | Equations |
|---|---|---|---|
| Stage 01 | Preprocessing & Signal Conditioning | 13 | 12 |
| Stage 02 | ICA-Based Artifact Removal | 21 | 13 |
| Stage 03 | Event-Related Potential Analysis | 11 | 6 |
| Stage 04 | Time-Frequency Analysis | 14 | 11 |
Each report follows an interleaved narrative architecture: theoretical foundations are presented in thematic blocks, immediately followed by the corresponding pipeline figures with scientific captions and interpretation. The reports cover the complete mathematical framework β from IIR filter design and ICA theory through ERP averaging and CWT decomposition β integrated with the empirical results from the pipeline.
| Requirement | Notes |
|---|---|
| MATLAB R2020b+ | Core platform |
| Signal Processing Toolbox | Required for ellipord, ellip, iirnotch, filtfilt |
| Wavelet Toolbox | Required for Stage 04 (cwt with analytic Morlet) |
| EEGLAB | Optional β enables topographic plots; pipeline continues without it |
EEGLAB integration is controlled via config (eeglab.path, eeglab.auto_addpath). Public configs ship with REPLACE_WITH_LOCAL_EEGLAB_PATH; set that value to your local EEGLAB installation if you want topographic plots. If topoplot is unavailable, topographic figures are skipped with a structured warning. Set eeglab.require_topoplot = true to enforce availability as a hard requirement.
This project was developed as part of the Brain Signal & Image Processing (EEG) course at the master's degree level.



