EEGPrep

EEGPrep is an EEGLAB-compatible, Python-native toolkit for loading, cleaning, visualizing, scripting, and validating EEG preprocessing workflows. It keeps the EEGLAB concepts researchers already know, including EEG, ALLEEG, CURRENTSET, pop_* functions, command history, ICA fields, channel locations, events, epochs, STUDY workflows, and EEGBrowser-style review, while providing a standalone Python package with GUI, interactive console, CLI, tests, and Sphinx documentation.

EEGPrep is built for EEG researchers who want EEGLAB-style workflows, Python reproducibility, and agent-friendly automation without requiring MATLAB or an EEGLAB checkout at runtime.

Documentation: sccn.github.io/eegprep | Issue tracker: github.com/sccn/eegprep/issues

Why EEGPrep?

• Familiar to EEGLAB users. Function names, data structures, menus, history commands, and GUI workflows follow EEGLAB where that helps users move between tools.
• Python-native and standalone. Runtime code lives in the eegprep package and works without calling MATLAB or reading the vendored EEGLAB reference tree.
• GUI and console share one workspace. Launch eegprep-console and switch between the Qt GUI and Python commands while EEG, ALLEEG, CURRENTSET, LASTCOM, ALLCOM, STUDY, and CURRENTSTUDY stay synchronized.
• Scriptable from day one. The same pop_* workflows can be used from the GUI, Python scripts, and the command-line interface.
• Designed for reproducible research. CLI commands support structured JSON, manifests, pipeline validation, stable error codes, and bundled agent guidance.
• Validated against EEGLAB. Numerical parity tests and visual parity checks compare EEGPrep behavior with EEGLAB for deterministic workflows.

Install

EEGPrep uses uv for development and CI. For a published release, install the lean package with:

uv add eegprep

To install all optional extras, including GUI, console, docs, and classifier dependencies, use:

uv add "eegprep[all]"

If you are installing into a non-uv environment, pip install eegprep remains supported for published releases:

pip install eegprep

For a source checkout:

git clone https://github.com/sccn/eegprep.git
cd eegprep
uv sync --group dev

The complete install can pull in large optional binaries on some platforms, especially for ICLabel/PyTorch support. You can install a lightweight CPU-only PyTorch build manually if that better matches your system.

Quick Start

The repository includes tutorial data in sample_data/, named after EEGLAB's sample-data convention.

Shared GUI and Python Console

Launch EEGPrep with the main GUI and a synchronized IPython workspace:

uv run eegprep-console --full

Then use the GUI to load sample_data/eeglab_data.set, run preprocessing actions from the menus, and inspect the same state from the console:

EEG["setname"], EEG["srate"], EEG["nbchan"], EEG["pnts"]
CURRENTSET
LASTCOM
eegh()

You can also run pop_* commands directly:

pop_resample(EEG, 64)
pop_reref(EEG, [])

GUI actions and console commands append to the same history, so workflows can be replayed or moved into scripts.

GUI Only

uv run eegprep-gui --full

Use this when you want the EEGLAB-style menu workflow without an attached console.

Agent-Friendly CLI

The eegprep command is intended for headless pipelines, batch processing, and AI agents that need machine-readable output.

uv run eegprep inspect sample_data/eeglab_data.set --json
uv run eegprep validate sample_data/eeglab_data.set --json
uv run eegprep capabilities --json
uv run eegprep skills get eegprep-cli

Transform commands use the same EEGPrep processing functions as the Python API and write manifests for reproducibility:

uv run eegprep resample sample_data/eeglab_data.set \
  --freq 64 \
  --output sample_data/eeglab_data_64hz.set \
  --manifest sample_data/eeglab_data_64hz_manifest.json \
  --json

Python API

from pathlib import Path

from eegprep import pop_eegfiltnew, pop_loadset, pop_resample, pop_saveset

input_file = Path("sample_data") / "eeglab_data.set"
output_file = Path("sample_data") / "eeglab_data_quickstart.set"

EEG = pop_loadset(input_file)
EEG, filter_com = pop_eegfiltnew(
    EEG,
    locutoff=1.0,
    hicutoff=40.0,
    plotfreqz=False,
    return_com=True,
)
EEG, resample_com = pop_resample(EEG, 64, return_com=True)
pop_saveset(EEG, output_file)

print(filter_com)
print(resample_com)

return_com=True returns the updated dataset and the replayable command string that EEGPrep records in GUI and console history.

For EEGLAB Users

EEGLAB concept	EEGPrep equivalent
eeglab GUI	uv run eegprep-gui --full or uv run eegprep-console --full
EEG, ALLEEG, CURRENTSET	Shared EEGPrepSession state in the GUI and console
MATLAB command history	LASTCOM, ALLCOM, and eegh() in eegprep-console
pop_* wrappers	Python eegprep.pop_* functions with return_com=True
EEGBrowser / scrolling review	EEGPrep EEGBrowser and pop_eegplot workflows
clean_rawdata, ICLabel, FIRFilt, DIPFIT, EEG-BIDS	Bundled EEGPrep plugin ports and menu integrations
STUDY workflows	Python STUDY structures, GUI paths, and std_* helpers
MATLAB scripts	Python scripts, CLI pipelines, and history-derived commands

EEGPrep follows EEGLAB's one-based user-facing indices where researchers expect them, while using zero-based Python indices internally. Continuous data is channel-major, usually (nbchan, pnts), and epoched data is usually (nbchan, pnts, trials).

What Is Included

• EEGLAB .set loading/saving, BIDS import/export, and common EEG file I/O.
• BIDS derivative workflows intended to interoperate with EEGPrep, EEGLAB, FieldTrip, Brainstorm, MNE, and other EEG analysis tools.
• Dataset, event, channel-location, epoch, and history workflows.
• Filtering, resampling, rereferencing, cleaning, rejection, interpolation, ICA, component review, ICLabel, DIPFIT, topographies, spectra, time-frequency, and statistics workflows.
• EEGBrowser-style scrolling inspection, marking, and rejection.
• STUDY and group-level workflow support.
• Extension SDK, plugin discovery, extension validation, and agent-facing extension authoring guidance.
• Sphinx documentation, API reference, examples, and a structured CLI.

Documentation

Start with the online documentation:

• Quick Start
• GUI and Console Session
• Scripting Workflows
• EEGBrowser
• Extensions
• API Reference

Repository documentation helpers are kept in docs/. The docs workflow publishes the Sphinx site to GitHub Pages.

Project Status

EEGPrep is in active pre-release development. It is intended to become a standalone Python counterpart for core EEGLAB preprocessing workflows. Current development emphasizes EEGLAB parity, GUI and console usability, BIDS support, extension support, and reproducible headless workflows.

Use EEGPrep with the same care you would apply to any research preprocessing software: validate pipelines on representative data, inspect intermediate outputs, and record the exact version and command history used for analysis.

Numerical Parity

EEGPrep is developed against EEGLAB as a parity oracle. The MATLAB and Python implementations are tested for close numerical agreement, including default preprocessing pipeline comparisons that target accuracy down to 1e-5 uV where the algorithms are deterministic. They have also been compared using the first two subjects from the BIDS datasets ds003061 and ds002680 on NEMAR. Observed differences were very small, with the largest reported HighpassFilter difference below 0.002, indicating strong numerical consistency for the tested workflows.

Development

Run tests from the project root with:

uv run pytest tests

For quick local iteration:

uv run pytest -m "not slow"

The repo uses ruff, ty, and pre-commit.py for linting, formatting, and type-checking:

./pre-commit.py --changed-from origin/develop
uv run --no-sync ruff check .
uv run --no-sync ruff format --check .
uv run --no-sync ty check

MATLAB parity tests require MATLAB Engine for Python. Install the engine from your MATLAB installation, for example on macOS:

uv pip install /Applications/MATLAB_R2025a.app/extern/engines/python

Check the installation:

import matlab.engine

engine = matlab.engine.start_matlab()
engine.eval("disp('hello world');", nargout=0)

The MATLAB comparison entry point is tests/matlab/main_compare.m.

Cite

If EEGPrep contributes to your research, please cite EEGPrep and the EEGLAB methods it ports. For EEGLAB, cite:

Delorme, A., & Makeig, S. (2004). EEGLAB: an open source toolbox for analysis of single-trial EEG dynamics including independent component analysis. Journal of Neuroscience Methods, 134(1), 9-21.

Core Maintainers

• Arnaud Delorme, UCSD, CA, USA
• Suraj Ranganath, UCSD, CA, USA
• Christian Kothe, Intheon, CA, USA
• Bruno Aristimunha Pinto, Inria, France

Maintainer release notes

Versioning

• Change the version inside pyproject.toml.
• Change the version inside tools/hpc/main.pbs for Singularity/Docker image references.
• Run make_release in the script folder and tag with the version.
• Use the correct Docker version when building.

PyPI Release Process

Use the release script for streamlined releases:

uv run --group release python scripts/make_release.py

The script will:

1. Check prerequisites: build, twine, and git status.
2. Confirm the version from pyproject.toml.
3. Let you choose a test release, production release, or both.
4. Build and upload the package. TestPyPI builds automatically use the eegprep_test name.
5. Create and push git tags for production releases.

Install release tools with:

uv sync --group release

Get API tokens for PyPI and TestPyPI. Twine can prompt for them during upload, or you can store them in ~/.pypirc.

Manual release remains possible, but scripts/make_release.py is preferred to avoid package-name mistakes. A former maintainer owns the eegprep name on TestPyPI, so manual TestPyPI builds must temporarily change name = "eegprep" to name = "eegprep_test" in pyproject.toml, then change it back after uploading.

uv run --group release python -m build
uv run --group release python -m twine upload --repository testpypi dist/*
uv pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ eegprep_test==X.Y.Z

Production release:

uv run --group release python -m twine upload dist/*
git tag -a vX.Y.Z -m "Release version X.Y.Z"
git push origin vX.Y.Z
uv pip install eegprep==X.Y.Z

Packaging follows the Python Packaging User Guide: https://packaging.python.org/en/latest/tutorials/packaging-projects/.

Docker notes for SCCN power users

docker build -t eegprep:0.2.9 -f DOCKERFILE .
docker tag eegprep:0.2.9 arnodelorme/eegprep:0.2.9
docker push arnodelorme/eegprep:0.2.9

Check the project on Docker Hub: https://hub.docker.com/.

Mounted folders are available in /usr/src/project.