EEG browsers

Introduction

This document provides an overview of free and open-source software EEG browsers. I only include tools written with freely available programming languages here, which excludes everything written in MATLAB.

Definition

An EEG browser is an application which visualizes certain aspects of electroencephalographic (EEG) or similar modalities. Such signals are basically a collection of time series recorded simultaneously from different locations. At the very least, interactively visualizing the time course of these signals is one of the core features of any EEG browser.

Core features

Of course, the effectiveness of an EEG browser depends critically on how and which visualization features are implemented. If users can smoothly scroll and zoom through the data in both time and channels, assessing data quality is much easier than when only whole pages of displayed data are updated. Displaying a large quantity of data points smoothly is not trivial.

For example, a typical segment of interest consists of dozens of channels and several seconds of data with a sampling frequency of 512 Hz or higher. This amounts to roughly 300,000 data points that need to be rendered simultaneously. Scrolling forward or backward in time means that new data needs to be visualized almost instantaneously for a smooth user experience. In most cases, this requires some sort of downsampling to process such large amounts of data. In fact, there are only a limited number of pixels available to display the data, so for example drawing 10,000 data points in a window consisting of 1,000 pixels horizontally is both inefficient and not necessary.

In addition to displaying the raw EEG signals, it is also important that EEG browsers support creating and editing annotations. An annotation is a time segment in the data associated with a specific start and stop time, a specific channel (or all channels), and a label (such as "artifact"). An EEG recording can have multiple, possibly overlapping, annotations. An EEG browser needs to support creating annotations (for example using mouse actions such as dragging over a specific data segment), editing and deleting annotations, as well as showing and hiding all or specific types of annotations.

Online data streaming is a bonus feature that some users might find useful to monitor incoming EEG data (such as when recording with LSL). However, it might be preferrable to have dedicated data streaming viewers for such applications instead of extending EEG browsers with these capabilities.

Data formats

There are dozens of file formats for EEG data. MNE (a widely used Python package for EEG/MEG analysis) supports most widely used formats – which means that Python-based EEG browsers can easily import these formats. Once imported, EEG data can be represented as an array of floating point numbers (double precision in most cases).

The most commonly used formats are:

• EDF (European Data Format, the probably the most widely used format)
• BrainVision (mainly used by Brain Products amplifiers)
• EEGLAB (basically a MATLAB file with specific data structures)
• BDF (mainly used by Biosemi amplifiers, based on and similar to EDF)

These formats are also supported by the BIDS EEG standard, and they specifically recommend to use EDF or BrainVision whenever possible.

Test data

The MNE testing data repository contains test files for many formats. Specifically, here are some files for the four formats discussed previously:

• The EDF format uses only one file (test_edf_stim_resamp.edf)
• The BrainVision format consists of three files (test_NO.vhdr, test_NO.vmrk, test_NO.eeg)
• The EEGLAB format can consist of one (test_raw_onefile.set) or two files (test_raw.set, test_raw.fdt)
• The BDF format is almost identical to EDF (multiple_annotation_chans.bdf)

Available apps

• SigViewer (Windows/macOS/Linux): Written in C++/Qt. Supports multiple file formats. Smooth scrolling. Currently requires that all of the data is loaded into memory.
• MNE (Windows/macOS/Linux): Written in Python. Based on Matplotlib. Supports multiple file formats. Chunky scrolling (page-based). Should also work when data has not been loaded completely into memory.
• MNE Qt Browser (Windows/macOS/Linux): Written in Python, based on PyQtGraph. Works as an alternative browser backend in MNE, which means it supports the same file formats. Relatively smooth scrolling and zooming (but this depends on the platform and settings such as OpenGL). Should also work when data has not been loaded completely into memory.
• EDFbrowser (Windows/macOS/Linux): Written in C++/Qt. Supports only EDF files. Relatively smooth scrolling. Not officially supported on macOS.

All four browsers use Qt in the background, sometimes directly (SigViewer, EDFbrowser), and sometimes through other packages (PyQtGraph and Matplotlib). Qt does a pretty good job in abstracting away platform idiosyncrasies, but sometimes differences in looks and/or behavior still crop up. This means that if these apps want to support all three major platforms (Windows/macOS/Linux), developing and testing on all three platforms cannot be avoided completely.

The following sections show how to open and browse the test file test_edf_stim_resamp.edf with each app in turn.

SigViewer

• Install SigViewer from https://github.com/cbrnr/sigviewer.
• Open SigViewer (on macOS, you might have to right-click and select "Open" because double-clicking does not work the first time).
• Select "File" – "Open" and pick the file test_edf_stim_resamp.edf.
• That's it, now the file is open and you can scroll through the data both horizontally and vertically.

MNE

• Create a Python (virtual) environment containing the mne package.

• Put the file in the working directory and run the following script:

  import mne
  
  mne.viz.set_browser_backend("matplotlib")
  raw = mne.io.read_raw_edf("test_edf_stim_resamp.edf")
  raw.plot(block=True)

MNE Qt Browser

• Create a Python (virtual) environment containing the mne and mne-qt-browser packages.

• Install PySide6 or PyQt6.

• Put the file in the working directory and run the following script:

  import mne
  
  mne.viz.set_browser_backend("qt")
  raw = mne.io.read_raw_edf("test_edf_stim_resamp.edf")
  raw.plot(block=True)

EDFbrowser

EDFbrowser opens only EDF files that are 100% standard-compliant. Unfortunately, the example file we are using here cannot be opened, because it is missing a required channel label (EDF+ mandates that an annotations channel must be present, which is not the case for our file).

Web-based EEG browsers

This is where web-based tools (running in a modern browser) might come in handy.