EEG ASSR EEGLAB Plugins

This repository contains the three project plugins developed for ASSR EEG analysis:

• eeg_automatic_pipeline: MATLAB/EEGLAB preprocessing, batch execution, preset builder, reports, and the Python/MNE companion pipeline.
• attention_plugin: attention-index extraction and visualization.
• friedman_assr: ASSR Friedman and permutation statistics helpers.

EEGLAB itself and third-party EEGLAB plugins are treated as external dependencies. Do not commit local EEG recordings, generated outputs, or machine-specific files.

Interfaces

The MATLAB Pipeline Builder configures and runs the ASSR preprocessing steps inside EEGLAB. The Python GUI runs the same batch workflow without a MATLAB license.

Documentation

Main user documentation lives with the preprocessing plugin. For a copy-paste, non-developer walkthrough of the demo, start with the Demo Quick Start:

• eeglab2026.0.0/plugins/eeg_automatic_pipeline/docs/DEMO_QUICKSTART.md
• eeglab2026.0.0/plugins/eeg_automatic_pipeline/README.md
• eeglab2026.0.0/plugins/eeg_automatic_pipeline/docs/INSTALL.md
• eeglab2026.0.0/plugins/eeg_automatic_pipeline/docs/USAGE.md
• eeglab2026.0.0/plugins/eeg_automatic_pipeline/docs/VALIDATION.md
• eeglab2026.0.0/plugins/eeg_automatic_pipeline/docs/DEMO_GUIDE.md
• eeglab2026.0.0/plugins/eeg_automatic_pipeline/docs/TROUBLESHOOTING.md

Python-specific usage is documented in:

• eeglab2026.0.0/plugins/eeg_automatic_pipeline/python_eeg_pipeline/README.md

The companion plugin READMEs are:

• eeglab2026.0.0/plugins/attention_plugin/README.md
• eeglab2026.0.0/plugins/friedman_assr/README.md

Requirements

• MATLAB R2025b/R2026a with EEGLAB 2026.0.0.
• EEGLAB plugins required by the selected pipeline steps, including xdfimport, clean_rawdata, ICLabel, firfilt, dipfit, and EEG-BIDS when BIDS export is used.
• Python 3.10+ for the MNE companion pipeline (developed and validated on 3.14).
• uv is recommended for repeatable Python test and CLI execution.

The local validation environment used:

• MATLAB R2025b Update 1 and MATLAB R2026a.
• EEGLAB 2026.0.0.
• ICLabel 1.7.
• clean_rawdata 2.11.
• ASR component version 0.13.
• xdfimport 2.0.

Installation

Clone the project once, or enter the existing checkout:

git clone <repository-url> eegui
cd eegui

EEGLAB 2026.0.0 ships inside the checkout, so no plugin copy step is needed — go straight to the Quick Starts below.

Using a separate EEGLAB install instead

If EEGLAB lives somewhere else, symlink the three project plugins into its plugins folder so the Git checkout stays the single editable source:

PROJECT_ROOT="/path/to/eegui"
EEGLAB_ROOT="/path/to/eeglab2026.0.0"

mkdir -p "$EEGLAB_ROOT/plugins"
for p in eeg_automatic_pipeline attention_plugin friedman_assr; do
  ln -sfn "$PROJECT_ROOT/eeglab2026.0.0/plugins/$p" "$EEGLAB_ROOT/plugins/$p"
done

MATLAB Quick Start

In MATLAB, run the one-line startup script (point it at your checkout). It adds the required paths, starts EEGLAB, and opens the Pipeline Builder:

run('/path/to/eegui/eeglab2026.0.0/plugins/eeg_automatic_pipeline/init_eeg_pipeline.m')

Run a scriptable batch (after init_eeg_pipeline has set up the paths):

pluginRoot = fileparts(which("init_eeg_pipeline"));
preset = loadPipelinePreset(fullfile(pluginRoot, "presets", "assr_preprocessing.json"));
report = runEegPipelineBatch("input.xdf", ...
    preset.steps, ...
    OutputDir="eeg_pipeline_output", ...
    ChannelLocations=fullfile(pluginRoot, "ebneuroASSR.locs"), ...
    SaveDatasets=false);

Use SaveDatasets=false for lightweight validation runs when .set/.fdt exports are not needed.

Python Quick Start

cd /path/to/eegui/eeglab2026.0.0/plugins/eeg_automatic_pipeline/python_eeg_pipeline
uv sync --all-extras
uv run eeg-pipeline-py gui

uv sync --all-extras installs every optional feature (xdf, iclabel, gui, dev) in one step; uv run reuses that environment. To verify the install:

uv run pytest
uv run ruff check .

Run a preset from the CLI:

uv run eeg-pipeline-py run-preset ../presets/psd_only.json \
  --input-file /path/to/input.set \
  --output-dir /tmp/eeg_python_out

Run a guided ASSR batch from the GUI when a no-code workflow is required. The GUI writes a batch manifest, per-run reports, PSD/feature exports, and validation summaries.

Validation Status

The project is demo-ready with the current validation caveat:

• MATLAB is the numerical reference implementation.
• Python is implemented as a methodological MNE counterpart and is not expected to match EEGLAB exactly for CleanLine, ASR, ICA, ICLabel, or spherical interpolation internals.
• MATLAB/Python parity should be judged with explicit feature tolerances and the generated validation reports, not only by visual plot inspection.
• Final acceptance still requires manual review of representative real EEG runs with the project supervisor.

Run the Python test suite before demonstrations:

cd eeglab2026.0.0/plugins/eeg_automatic_pipeline/python_eeg_pipeline
uv run pytest
uv run ruff check .

For MATLAB smoke tests, use the plugin tests under:

eeglab2026.0.0/plugins/eeg_automatic_pipeline/tests

License

Released under the MIT License. See LICENSE for details. EEGLAB and third-party EEGLAB plugins are external dependencies distributed under their own licenses.