EEG-ExPy: classic EEG experiment protocols in Python, for cheap hardware

The economics of a research-grade EEG setup

EEG-ExPy is a collection of classic EEG experiments implemented in Python, and the README frames it as democratizing the cognitive neuroscience experiment.

The argument is economic before it is technical. Conventional lab-based EEG research typically uses research-grade and often high-density devices, dedicated stimulus delivery software and hardware, and dedicated technicians to operate it, and the price tag for those items can easily run into hundreds of thousands of dollars, which places real limits on who can acquire and use the data.

Against that, the README points to developments in hardware and software that make many classic experiments possible on a standard laptop with a relatively cheap consumer device, at a combined minimum cost of less than a thousand dollars. The protocols and analyses themselves are described as quite generic, but tailored for low-budget hardware such as the InteraXon MUSE and the OpenBCI Cyton.

That framing explains the audience and the ambitions. The README names neurotechnology and cognitive neuroscience education at both university and high school level, and more ambitious research and clinical applications using large numbers of devices and naturalistic, out-of-the-lab settings.

The library is BSD-3-Clause licensed, the documentation site is at neurotechx.github.io/EEG-ExPy, and there is a Binder badge, which means the examples can be launched in a browser without installing anything locally. For a teaching context, that matters as much as the price of the headset.

Four layers that usually live in four different programs

The core aim of the project is to provide the glue that pulls together the enabling technologies needed to run these experiments and analyse the data, and the README lists four pieces of that glue.

The first is streaming data from relatively new wireless consumer-grade EEG devices. The second is visual and auditory stimulus presentation, concurrent with and time-locked to the EEG recordings, which is the part that separates a real experiment from a recording of someone staring at a screen. The third is a growing library of well-documented, ready-to-use and ready-to-modify experiments. The fourth is signal processing, statistical and machine learning data analysis functionality.

The reason to put these in one place is that the alignment between stimulus onset and recording clock is the hard requirement in the whole field. A paradigm that is not time-locked to the recording produces data that cannot be averaged across trials, and averaging across trials is what evoked response work depends on. A library that owns both the presentation and the stream can guarantee that alignment instead of hoping two separate programs share a clock.

The repository layout reflects those layers. The package lives in eegnb/ with a parallel eegexpy/ directory, examples/ holds the paradigms, doc/ holds the documentation source, and there are environments/, binder/, tests/, a .devcontainer/ and a Makefile.

The paradigms that ship as examples

The examples directory is the clearest statement of what the library is for, because the directory names are the standard paradigms of cognitive neuroscience.

There is auditory_oddball, the classic auditory oddball where a rare tone is embedded in a stream of common ones, and the visual counterparts of the same idea in visual_gonogo, where the participant responds to a target and withholds a response to a non-target.

visual_p300 covers the P300 component, an evoked response about 300 milliseconds after a rare or meaningful stimulus, and visual_n170 covers the N170, an early negative component associated with faces and other visual expertise. visual_ssvep is the steady state visual evoked potential paradigm, where an oscillating stimulus produces a response locked to the flicker frequency, which is the basis of several brain computer interface approaches. visual_cueing is the cueing paradigm, rest is a resting state measurement, misc is a catch-all, and sandbox is a place to try things.

Having these as runnable code rather than as prose descriptions is the contribution. A paradigm in a notebook is something you can change: replace the stimulus, change the trial count, add a condition, and rerun. That is what makes a library like this a research tool rather than a set of illustrations.

The tests are configured to treat notebooks as first class code, which is the practical proof that the examples are meant to be run and edited, not just read.

brainflow for devices, LSL for streaming, PsychoPy and MNE for the rest

The acknowledgments section is unusually informative, because it names the libraries that do the heavy lifting.

EEG-ExPy was created by the NeuroTechX hacker and developer neuroscience community, and the initial idea and the majority of the groundwork were due to Alexandre Barachant, including the muse-lsl library, which the README calls a core dependency. The lead developer is now John Griffiths.

Two more credits matter for the architecture. Andrey Parfenov is thanked for the brainflow library, which has allowed the project to dramatically expand the range of supported devices, and the developers of PsychoPy and MNE are thanked, because together they make up the central scaffolding of eeg-expy. So the division of labour is: brainflow for talking to the headset, LSL for the stream, PsychoPy for stimulus presentation, MNE for the analysis conventions, and EEG-ExPy for the protocols that tie them together.

The practical consequence is that adding a device is largely a brainflow question rather than an EEG-ExPy question, and that the paradigms look the way they do because PsychoPy is doing the presentation.

The community around the project is the NeuroTechX community, with a Discord server, a Slack workspace, and an issues page used for general discussion. There is also a forthcoming research paper mentioned, and an intro talk from the Brainhack Ontario presentation.

Installation is a pip install, and the extras are the real cost

The packaging is arranged around extras, and the Makefile shows the shape of it.

build:
	pip install --use-pep517 .[full]

The full extra pulls in everything, and there are narrower ones for documentation building and for the analysis and streaming and stimulus layers separately. The setup.py in the repository parses requirements.txt by its section headers, extracting the analysis, streaming, stimpres and docsbuild blocks and turning each into an extras_require entry, with the analysis requirements as the base install.

The Makefile also has the documentation dependency install, which is the docsbuild extra installed in editable mode, a test target that runs pytest with any extra arguments, a typecheck target that runs mypy while excluding the visual_cueing examples because of errors, and docs targets that build the Sphinx site in the doc/ directory.

The platform dependencies are the part that catches people out. The install-deps-apt target lists the system packages needed on Ubuntu, and the comments explain why: xvfb for a virtual display, libgtk-3-dev for wxPython, freeglut3-dev for a wxPython dependency, portaudio19-dev which might be needed to import psychopy on Ubuntu, pulseaudio which might be needed to actually run the tests, libpulse-dev to build pocketsphinx, the speech recognition dependency of psychopy, libsdl2-dev for psychopy, and libnotify4 for the libnotify module used in wxPython.

There is a second target for wxPython, because those wheels are distribution specific and are not on PyPI, so the Makefile installs them from the wxPython extras index for Ubuntu 22.04.

So the honest picture is that a pip install is the easy part, and a working stimulus presentation stack on Linux is the part that takes an evening.

The dependency pins are a list of problems already solved

Reading the comments in requirements.txt is a compact history of what breaks.

pylsl is pinned to 1.16.2, with the comment explaining the upgrade from 1.10.5 so that the arm64 library is available on macOS Apple Silicon, to prevent an error where the liblsl64.dylib is the wrong architecture.

PsychoPy is not taken from PyPI. It is a fork, installed from git at a specific tag, v2026.2.0-rift-fix, and the comment says the fork carries a fix for a Rift stereo projection matrix crash under strict ndim psychxr.

ffpyplayer is pinned to 4.5.2 because 4.5.3 fails to build as a wheel. psychtoolbox is required at 3.0.20 or newer on arm64, with a note that the licence is MIT but that 3.0.20 and later introduced paid licensing for the prebuilt macOS and Windows binaries, leaving Linux unaffected. That is a real constraint for anyone running on a Mac, and it is the kind of detail that is easier to read here than to discover.

And there is a removal recorded: the pynput dependency is gone, because it pulls in evdev, which fails to build from source on modern Linux under the conda toolchain due to missing kernel header symbols, and the two callsites that used the pynput keyboard listener were replaced with a threading and stdin helper in eegnb/utils/cancel.py, cross-platform and with no new dependencies.

That last entry is the best example of the project's character. The fix was not to patch evdev, it was to remove the need for it.

Notebooks are tested, and the API is still moving

The test configuration in pyproject.toml says a lot about how the project is validated.

[tool.pytest.ini_options]
minversion = "6.0"
addopts = """
    --cov=eegnb
    --cov-report=term
    --cov-report=xml
    --cov-report=html
    --nbval-lax
    --current-env
    --ignore 'tests/test_run_experiments.py'

The nbval-lax flag is the notable one, because it runs Jupyter notebooks as tests, and the python_files setting includes both *.py and *.ipynb, so the examples are executed rather than only parsed. Coverage is measured on the eegnb package with three report formats. The configuration also ignores the test for running experiments, which is the one that needs a device attached.

Against that, the README is blunt about the state of the API. The current version is the 0.2.X series, and the code base and API are under major development and subject to change, with the changelog at the documentation site for notes on what changed.

The project has also been renamed twice in its history, and both earlier lines are still available: eeg-notebooks underwent major API changes in v0.2, and the v0.2 and v0.1 versions remain in separate repositories if you need them.

So the library is a well-tested, well-documented, still-moving research platform. The test coverage is better than many research codebases, and the stability of the interface is the thing to plan around.

Editorial conclusion

EEG-ExPy suits a student, a course instructor or a research group who wants to run a classic evoked response paradigm on a laptop with a consumer headset instead of committing to a laboratory setup, and it suits anyone who wants to read a complete, time-locked experiment implementation rather than assemble one from parts. It does not suit a study that needs the sampling rate, electrode density or signal quality of a research-grade amplifier, and it does not suit a project that needs a stable API, since the README says the code base and API are under major development and subject to change. Check three things before you rely on it: which of the example paradigms matches your question, whether the headset you own is in the supported set now that the device layer runs through brainflow and LSL, and that you can tolerate a 0.2.x API. The last push to the repository was on 2026-10-14 and the project publishes no GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. NeuroTechX/EEG-ExPy on GitHub
4. Project website
5. README