EEGLAB: the Matlab toolbox that still sets the baseline for EEG analysis

A Matlab environment, with an Octave caveat

EEGLAB is described as an open source signal processing environment for electrophysiological signals, running on Matlab and Octave, and developed at the SCCN at UCSD. The repository description adds the detail that Octave support is command line only, which is the sort of limitation that is easier to state plainly than to discover.

The history is in the readme as well. This folder contains the original Matlab functions from what was formerly the ICA/EEG Matlab toolbox, all released under the GNU public licence, with the licence file named in the readme. The project is the one behind the standard citation in the field, which the readme asks users to reference in publications, and that citation is a 2004 paper.

The scope is much wider than the name suggests. The topic list for the repository covers brain and biosignal work, electrocardiography, electrocorticography, electrodermal activity, intracranial EEG, magnetoencephalography, heart rate variability, preprocessing, source localization and spectral analysis, alongside Octave and Matlab. So it is a general electrophysiology environment that grew out of an EEG toolbox, and the plugin system is where the modality-specific work lives.

The project is MIT in the repository listing, which is one of the places where the metadata and the readme disagree, and the readme says GNU public licence. The licence file in the repository is the document to check, and it matters for an academic toolbox that many commercial groups build on.

Install from a release, because the repository is submodules

The installation section is three paragraphs, and one of them is a warning.

The recommended route is to download the official EEGLAB release from the project's own download page. The alternative is the repository, but the readme says plainly: do not download a zip file directly from git, as it will not contain the EEGLAB submodules.

That is a specific and common failure. The source is split across repositories, and a zip of the working tree is missing the parts that live in the submodules. The supported clone does the right thing in one command:

git clone --recurse-submodules https://github.com/sccn/eeglab.git

And if the submodules were missed, the readme gives the repair, which is run from inside the eeglab folder and then updates the tree with the submodules pulled as well:

git submodule update --init --recursive --remote
git pull --recurse-submodules

The use of the remote flag on the submodule update is worth noticing, because it means the submodules track their own upstream rather than being pinned to a commit recorded in the parent repository. For a user who wants the exact combination the maintainers tested, that is a hazard; for a user who wants the latest of everything, it is a feature. The official release avoids the question by giving you a consistent snapshot, which is the reason it is the recommended path.

The directory layout is the public interface

The sub-directories section reads like a map of the toolbox, and it is the part of the readme to skim before you start.

The functions directory holds all the distributed EEGLAB functions, and the readme groups them the way the toolbox itself is organised, into admin, sigproc, pop and misc. The pop prefix is the one to know, because it is the convention for the pop-up window functions that make up most of the interactive interface, and the naming pattern is what lets you find the function you need without documentation.

The plugins directory is where downloaded plug-ins go, and the readme notes that dipfit at version 1.0 is present by default. dipfit is the source localisation component, so shipping it by default tells you something about what the project considers core.

Then there are two data directories that matter more than their size suggests. The sample data directory holds miscellaneous EEGLAB data used in the tutorials and references, and the sample locations directory holds standard channel location files, in the 10-10 and 10-20 montages, which is what you need to put electrodes on a head.

The root itself has the files you would expect from a Matlab project, a main function file, a project file, a contents file for the paths, and the tutorial scripts directory. There is also a plugin directory in the listing that is separate from the plugins directory inside the project, which is a naming collision worth knowing about before you copy things around.

Using it is one command, and the compiled version has a wrinkle

The usage section is five steps and could hardly be simpler.

You start Matlab, you use Matlab to change into the folder containing EEGLAB, you type eeglab at the command prompt and press enter, you open the main EEGLAB tutorial page, and you send feedback and suggestions to the address given in the readme.

The one caveat is the compiled version. If you experience problems, the readme says, try running EEGLAB as administrator. That is a sign of an era: the distributed form is a compiled package, and a compiled package that wants to write to its own directory or to a location it cannot reach will need administrator rights to get going.

The documentation, in the meantime, is not in the repository. It is on the EEGLAB wiki, and the readme links the wiki page for the tutorial as the place to go after launching, which is the natural order for a piece of software with this much surface area.

The feedback address is a good thing to note as well. For a project with this many users in academia, a working address that a person reads is worth more than any number of issue templates, and the readme asks for it directly rather than pointing at a tracker.

The citation is still the 2004 paper, and that is a fact about the field

The publication section is short and it asks users to reference a specific paper.

Delorme and Makeig, published in 2004 in the Journal of Neuroscience Methods, describes EEGLAB as an open source toolbox for the analysis of single-trial EEG dynamics, including independent component analysis, and the readme links the article.

Twenty years later the toolbox is still described with that citation, and there is something instructive in that. It means EEGLAB is not a fast moving product with a quarterly release note; it is an artefact that the field settled on, which is exactly why a new project needs to interoperate with it rather than replace it.

That also explains the shape of the repository. The default branch is develop rather than master, which is the older convention but also a sign that the branching has been thought about, and the repository publishes no releases at all, because the distribution mechanism is the download page rather than a package index. For a Matlab toolbox that is perfectly reasonable: there is no dependency to resolve, no runtime to pin, and the installer is a folder you add to the path.

The one caveat for a modern lab is the environment itself. Matlicence is not free, so an Octave user is the one with a free path, and the readme is clear that Octave is command line only, which means the interactive interface is a Matlab feature.

For the record, the topics also say the toolbox now covers considerably more than the 2004 paper did, with electrocardiography, electrocorticography, electrodermal activity, intracranial recordings, magnetoencephalography and heart rate variability all in scope, and those extensions live in the plugin directory rather than in the core.

What to check before you build a pipeline on it

A short checklist for anyone about to use this in a project.

First, the install. Take the official release rather than a zip of the repository, because the release bundles the submodules for you, and if you must clone, use the recursive form and the repair command the readme gives.

Second, the licence. The repository listing and the readme describe it differently, and the readme names the file that governs the original functions as the GNU public licence. If your institution has a policy on copyleft in analysis code, that file answers the question.

Third, the environment. Decide Matlab or Octave early, because the Octave path is command line only and that shapes what your students or your collaborators can do with the data.

Fourth, the versioning. There are no releases in the repository, so a paper that says we used EEGLAB needs a version statement, and the download page is where the version comes from. The develop branch is where work lands, and the submodule update with the remote flag means the components move independently of the parent tree.

Fifth, and most practically, the plugins. The toolbox itself is the platform, and the parts of your analysis that matter for your field are plugins, with the default set being smaller than the community set. The readme points at the download page for those, and the wiki for everything else.

And last, check whether the tool you need is already there. The direction of travel in this field is towards more open formats and more independent reimplementations of the same analyses, and a pipeline that depends on a plugin someone stopped maintaining is a pipeline you will be rewriting. The 2004 citation and the active repository are both good signs, but they are not the same as a guarantee.

Editorial conclusion

Adopt EEGLAB if you analyse electroencephalography data and want the reference implementation that most published EEG pipelines are built against, especially if you need the existing plugins rather than a modern rewrite. Do not adopt it if your requirement is a reproducible environment you can pin and distribute, because there are no releases and the project is developed on a branch rather than versioned in the usual way. Before you install, take the official release rather than cloning a zip, because the repository carries submodules that the download page bundles for you, and decide early whether you will work in Matlab or in Octave, because the Octave path is command line only.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. sccn/eeglab on GitHub