1. Description

This tutorial demonstrates how LabStreamingLayer (LSL) can be used within a complete pipeline for recording EEG and other signals, adding event markers to the data stream, accessing and visualizing data online, as well as analyzing and converting data after it has been recorded. While the tutorial is not limited to Open Source, it is definitely an important factor as the complete pipeline can be run with freely available tools.

2. The Complete Pipeline

Streaming EEG data

The first step of any pipeline that involves EEG data is to set up data acquisition. Brain Products amplifiers usually come with BrainVision Recorder in the package, but they are also compatible with LSL, either indirectly by connecting to the remote data access (RDA) server or by using specific LSL connectors that have been developed for each individual amplifier.

Downloading an LSL connector

To make your life easier, we created our own page on github where you can find all the relevant connectors and some useful tools all in one place. To get the full picture of LSL, you may also want to look at the main page and the app collection for more information and additional tools.

Depending on which amplifier you want to use, download the corresponding LSL connector. For example, when using LiveAmp, first go to LSL-LiveAmp and then click on releases. Here, you should find at least one version (e.g., 1.19.1). In the respective assets section you will see a list of downloadable content, comprising source code and executables. Download the zip file corresponding to your operating system.

Using the LSL connector

Extract the zip file to a folder of choice on your computer. LSL connectors usually do not have to be installed; instead, it will be enough to go to the folder and run the executable. In the case of LiveAmp, this would be “LiveAmp.exe”. If you want to use an amplifier for which there is no connector available, you can always use LSL-BrainVisionRDA. This connector streams the signals as they appear in BrainVision Recorder. Just make sure that you activate “Enable Remote Data Access” in the Recorder Preferences and start Monitoring or Recording.

After starting the LSL-connector (see the example for LiveAmp on the right), make sure that the amplifier is connected and turned on, or in case of LiveAmp, that the Bluetooth adapter is plugged in and LiveAmp is turned on. For connecting to LiveAmp, you will also have to click “Scan” in the LSL connector. LSL connectors typically provide all the necessary settings you will need for creating an LSL stream with EEG data. Most importantly, the number of channels and the sampling rate. Additionally, you may want to include non-EEG signals, such as accelerometer signals which are included in LiveAmp, or additional AUX channels that are naturally provided with the amplifier or via an accessory such as the LiveAmp Sensor & Trigger Extension (STE).

You should also find out which trigger sending option you prefer. If you are unsure, you can check both options. The difference will mostly affect how the trigger signals are stored in the recorded file. Basically, when you select “EEG Channel”, there will be an additional channel in your EEG stream that only consists of -1 at each sampling point except when there was an actual trigger recorded. Selecting the “Unsampled String Markers” will add an additional stream with strings describing the triggers and corresponding timestamps.

For subsequent processing steps, it is always better to have the correct channel labels by the time you start recording. For LiveAmp and actiCHamp (Plus), you can manually change the channel labels. However, you could also make use of the BVEF2lslconfig.py script. Here, you can merge an existing config file (can be created in the LSL connector) with a bvef file (find the correct one for your layout here) which comprises information on channel numbers, labels, and positions.

When you are satisfied with your settings, press “Link” and your EEG stream will be transmitted to the network almost immediately.

Streaming non-EEG data

One of the benefits of LSL is its capability to easily combine signals of different origins and record them all in one file. Such additional signal streams may comprise software markers, keyboard input, audio signals, mouse movements, mouse clicks, or other biosignals, for example from a NIRS system. Also, don’t forget, the LSL connectors for our amplifiers can already provide such streams by themselves if the corresponding option was selected for sending triggers.

An example for how you can add a software marker in is demonstrated by this code snippet which you can run in PsychoPy. You can see that there are only a few lines of code necessary to open an LSL stream and send a number every time a visual cue is shown on the screen. In this example, these cues indicate to the participant when they should perform motor imagery of either the left hand, right hand, or feet. In short, this is basically the standard Graz-BCI paradigm[1] for training motor imagery.

Looking at online LSL streams

Once the LSL streams are visible in your network, it is always a good idea to visually inspect the data. In the best case, you can constantly monitor the signals during a recording to avoid unwanted surprises when analyzing your recorded data. With the BrainVision LSL Viewer, you can do just that. This free tool allows you to connect to and display one main EEG stream (a regular stream with a defined number of samples per time period) that can be extended with several additional irregular streams (e.g., trigger channels or signals that occur at unforeseeable points in time).

Download the BrainVision LSL Viewer from our website, install and start the program. When you click on “Connect”, you can see regular and irregular streams. You will always have to select exactly one regular stream and an arbitrary number of irregular streams. To select the streams, first pick the regular (EEG) stream. Afterwards, you can select one or more irregular streams while holding and clicking on the stream names in the list. After confirming with “OK”, visualization starts automatically but from now on you can “Stop” and “Start” it yourself. You can view EEG channels only, AUX channels only, or all channels at once; up to 32 channels on one screen at the same time. Zoom in and out with the mouse wheel, drag the viewed segment with the left mouse button, and change horizontal/vertical scaling while holding the right mouse button. By clicking on the “A” in the lower left corner, you can return to the default viewing settings. You can even look at four Fast Fourier Transforms (FFTs) simultaneously by clicking on the channel labels on the y-axes. Close the FFTs by clicking the labels a second time. It is also possible to select configurations with display filters (you need to stop viewing first, otherwise “Configuration” is greyed out). Just keep BrainVision LSL Viewer running while recording your streams at the same time.

Recording LSL streams

Once everything is set up and you are satisfied with data quality, you can start recording all of your streams in one file. For this, you should install the latest version of LabRecorder which you can find under releases. After starting the application, you should immediately see all the available streams in the network. If not, check if there is a problem with your network and/or firewall settings. You have to make sure that all computers are in the same network and that none of the connections and programs are blocked by your firewall. Just select all the relevant streams you want to record, choose a folder and filename and “Start” the recording. Note that in newer versions of LabRecorder, you can already make use of the BIDS standards. Once the session is over, “Stop” the recording and wait for the file to be written.

Now, you have an XDF file that includes all the LSL streams you chose to record.

How to deal with XDF files

There are basically two main ways to load and process data stored in XDF files. For more information, it is best to directly refer to XDF on github.

• Based on MATLAB®: Use the provided function “load_xdf.m” to directly load the file into the MATLAB® workspace or just use EEGLAB. Here, you can use the xdfimport extension to load XDF files. With the bva-io extension it is also possible to export data directly to the BrainVision data format.
• Based on Python: There are also Python-based functions available. For convenience, you can also use MNELAB, a graphical user interface for MNE which provides a variety of analyzing tools (such as ICA) and can export to the BrainVision data format.

You see, with all these options, you have the freedom of choice. You can easily import your data in MATLAB® where you can do all of your further data analysis. Alternatively, you can export the data to our BrainVision data format if you prefer working with BrainVision Analyzer 2. If you do not have MATLAB® available, it is also not a problem sticking to free Open Source tools only. One very convenient way would be to simply load the data in MNELAB and export the files for BrainVision Analyzer 2.