Skip to content

About

πŸ§ πŸ“Š End-to-end EEG Processing Pipeline in MATLAB: preprocessing (filtering, ICA, bad channels), ERP analysis (WSA/GA), and CWT time-frequency analysis with publication-ready plots.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

2 Commits

Folders and files

Repository files navigation

EEG Processing Pipeline

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.

Overview

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.

Pipeline Architecture

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 filtfilt implementation, 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.

Key Features

  • 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/ellip with zero-phase filtfilt application
  • 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) and report (full portfolio set)
  • Comprehensive scientific reports with mathematical foundations for each stage

Example Outputs

Stage 01 β€” PSD Before/After Filtering Stage 02 β€” Regional Before/After ICA
Stage 03 β€” GA Topographic Maps Stage 04 β€” GA Time-Frequency Maps

Quick Start

1. Provide local external data

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.mat
  • data/external/raw/sub-035_ses-01_task-Rest_eeg.mat
  • data/external/ica/matrixW_sub-003.txt
  • data/external/ica/matrixW_sub-035.txt
  • data/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)

2. Configure EEGLAB path (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.

3. Validate repository structure

powershell -ExecutionPolicy Bypass -File scripts/validate_repo.ps1

4. Run smoke tests

addpath('tests');
run_smoke_tests("configs/pipeline.smoke.json", "sub-035");

5. Run full pipeline

outputs = run_pipeline("all", "sub-035", "configs/pipeline.default.json", "apply");

6. Generate report bundle

addpath('scripts');
bundle = generate_report("sub-035", "configs/pipeline.default.json");

Repository Structure

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

Configuration System

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.

Scientific Reports

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.

Dependencies

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.

License

This project was developed as part of the Brain Signal & Image Processing (EEG) course at the master's degree level.

About

πŸ§ πŸ“Š End-to-end EEG Processing Pipeline in MATLAB: preprocessing (filtering, ICA, bad channels), ERP analysis (WSA/GA), and CWT time-frequency analysis with publication-ready plots.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages