LSL Markers and/or Hardware Triggers with Brain Products and Various Stimulus Presentation Software Tools

A BLOG POST BY DR. ALEX KREILINGER

At a glance

Description

Lab Streaming Layer (LSL) already is a well-established tool for recording and accessing EEG and other signals in many labs around the world and interest in it is still growing. LSL makes it possible to combine several data streams into one single XDF file and access the streams with various clients online. These streams can be regular streams with a certain sampling rate, or irregular streams that send data only when needed. LSL is very well explained on its GitHub page and there is a comprehensive online documentation. In addition, we provide instructions here on how to use LSL with Brain Products amplifiers and tools in your experiments.

This post serves as a hub for ideas on how to use LSL in combination with Brain Products equipment, including our amplifiers, the TriggerBox (Plus), and other accessories. We demonstrate how to use LSL and/or hardware triggers via our TriggerBox (Plus) in stimulus presentation software solutions, such as PsychoPy, Presentation®, E-Prime®, and Psychtoolbox for Matlab. Using LSL markers can be an alternative to using hardware triggers, and we want to demonstrate how you can add such software markers to your experiment, in addition to, or even instead of hardware triggers.

Often, it is not enough to simply add LSL markers to an existing setup using hardware triggers, or to add hardware triggers to a setup based on LSL markers, but it is important to easily switch between these options, being able to adapt quickly to the context. Therefore, we want to show how easy activating or deactivating the respective options can be, at the same time also pointing out differences between the different stimulus presentation tools.

An important difference between LSL markers and hardware triggers is the timing. As already covered in this Press Release article, there are some things you need to consider when switching between LSL markers and hardware triggers for synchronizing EEG signals to events. The aforementioned article demonstrates these via PsychoPy. This article expands the examples to include instructions and scripts for E-Prime®, Presentation®, and Psychtoolbox. In addition, we provide instructions on how to analyze the timing, backed with scripts for MATLAB® and Python (MNE), but also making use of MNELAB and Brain Products’ own BrainVision Analyzer 2.

General considerations

Hardware triggers with Brain Products amplifiers will always have the benefit of being directly bound to EEG data. They are saved along with EEG data immediately and precisely at the time they occur and are therefore the optimum means for synchronizing events and signals. However, they always require some additional equipment, even if it is just a cable connecting the amplifier to a computer or the TriggerBox (Plus). Sometimes, these additional connections are not feasible, for example when requiring markers in a mobile scenario. In this case, using the amplifier without any additional accessories is preferable.

For such scenarios, LSL provides a great solution, and Brain Products provides the necessary LSL connector apps on our GitHub page. With these apps, you can create LSL streams that can be recorded individually or together with other LSL streams. These other LSL streams can contain other signals, but also markers or other contextual information. At any time, it is also possible to connect to all of the streams for online processing or visualization. Because the LSL streams contain time stamps, streams can later be synchronized. However, it is still necessary to be cautious, as there are certain factors that can lead to latencies between LSL streams. For example, a software marker coming from a stimulus presentation software will appear immediately, whereas EEG signals experience a slight delay depending on the nature of the amplifier and other parameters, such as sampling rate and number of channels. On top of that, other timing-sensitive events (unrelated to LSL) may not happen exactly when they are supposed to: the screen might not update immediately but only after additional screen flips, or the sound may need some time to be played by the sound processor. If such events need to be precise, for example to trigger evoked potentials, it is important to minimize such latencies, or at least be aware of them in order to compensate for them in the analysis pipeline.

One paradigm

All examples for the different software tools are based on one and the same paradigm. We create three events in time that can be used for synchronization and verification:

  1. Visually switching a square on the top left corner between bright and dark every 500 ms. This event can be recorded with a photo sensor as an auxiliary channel when connected to your EEG amplifier.
  2. At the same time, hardware triggers are sent via the TriggerBox (Plus). The TriggerBox (Plus) is also connected to the EEG amplifier and incoming triggers are sampled along with EEG data.
  3. At the same time, LSL markers are sent directly via an irregular LSL stream. These markers are not saved directly with EEG data but can be saved along the EEG stream to a single XDF file.

Analyzing data containing many repetitions of these three events can give you some good ideas on when things actually happen and if there is something wrong with your setup.

Please go through all of the featured software tools or skip right to your favorite tool to read the specific instructions. However, please do not miss the sections on how to test LSL markers and hardware triggers with our TriggerBox Test IO and how to record and analyze with different setups along with many examples.

E-Prime®

Preparation

Install the latest version of E-Prime® and the E-Prime LSL package from the official PST GitHub page. For some additional features, especially tailored for Brain Products, you can also install the E-Prime® Extensions for Brain Products but for the purpose of this example it is optional. Installing the LSL package requires some manual steps, all of which are explained in the readme file in the downloaded zip-container. Mainly, there are two important steps:

1. The package folder must be copied to the standard folder that E-Prime® is using, or the current setting in E-Prime® needs to be updated accordingly.
2. The lsl.dll file needs to be present in all experiment folders that are using LSL. Experiments themselves need to include some specific changes in the user script and additional objects. This step, however, is already included in the provided example that can be downloaded here.

The standard examples in the LSL package provided by PST include objects that require a client to connect to the LSL stream. In our example, we removed this requirement, so you can also run an experiment without reading the LSL stream. In addition, we reduced the information of LSL messages to a minimum, in order to keep the resulted data from all different stimulus presentation software tools as similar as possible.

(De)Activating LSL markers

To be able to use LSL, make sure to select the package in the Experiment Object Properties as shown in Figure 1. Even if the package is used and LSL is active, you can still ignore its functionality. By not requiring an active connection to a client, the LSL functionality is optional. However, for a cleaner solution it is better to deactivate LSL if it is not needed.

LSL Markers and/or Hardware Triggers with Brain Products and E-Prime

Figure 1: In Packages, make sure to select the LSL package. Note that the Extension for Brain Products is not selected as it is purely optional in this case.

In the provided example, we use task events of objects for sending LSL markers. We can specify exactly when LSL markers should be sent in relation to certain events in time (Figure 2). For example, at the onset or offset of a stimulus, with or without arbitrary latencies. As usual in E-Prime®, we can send information based on variables, for example the number of the trial or a [Marker] that can have several states. If we remove the task event, no more LSL markers will be sent.

LSL Markers and/or Hardware Triggers with Brain Products and E-Prime

Figure 2: The image object “SquareOn” has two task events. Exactly at the onset time of the object, a script named “LSLSendMarker” is called which sends the value in [Marker] via LSL.

(De)Activating hardware triggers

Hardware triggers work similarly. First, you have to install the TriggerBox Software and connect the TriggerBox (Plus). Select the TriggerBox (Plus) as a serial device and activate it as a device (Figure 3). Then, it can be used for task events as well, as shown in Figure 4. If the TriggerBox (Plus) is not needed, you can simply uncheck it from the list of devices, but you can also remove the corresponding task events. For the TriggerBox Plus, it is necessary to set the baud rate to 2 000 000 bits/s. Currently, this can not be done directly in the “Bits per second” field. Instead, this can be set up by opening “Edit Global Values” in the “Startup Info” tab. Here, you can create a value called “TriggerBox.Baudrate” (change the name if necessary) and then set the value to 2 000 000.

LSL Markers and/or Hardware Triggers with Brain Products and E-Prime

Figure 3:  The TriggerBox (Plus) is activated as a serial class. Note that it can be named differently instead of “TriggerBox” as well, although you must use the given name for later reference. For the TriggerBox Plus, the baud rate needs to be 2 000 000 bits/s, but the drop-down menu only goes up to 256 000 bits/s. The value can be manually entered in the “Startup Info” tab under “Edit Global Values”.

LSL Markers and/or Hardware Triggers with Brain Products and E-Prime

Figure 4: The image object “SquareOn” has two task events. Exactly at the onset time of the object, an action corresponding to the TriggerBox (Plus) named “WriteByte” is called which sends the value in [Marker] as a hardware trigger.

As you can see, it is possible to use LSL markers and hardware triggers exclusively, simultaneously, or none of them at all.

E-Prime® tips

  • Delete the stream, i.e., quit the experiment, only after you have finished recording, otherwise the XDF file cannot be loaded properly. Ideally, include breaks before and after the experiment, so you have dedicated time slots for connecting to the LSL streams and for finishing the recording at the end.

  • Experiments can be terminated with ctrl+alt+shift, but this can result in unclosed LSL streams.

  • Turn off programs that might interfere with E-Prime®, for example causing unexpected pop-ups. Otherwise, the timing may be disturbed.

  • E-Prime® uses PreRelease times in the stimulus setup. These times can be pre-allocated for subsequent events. It depends on the context if such a PreRelease time can really be used and therefore, you may get warnings informing you about this. Additional Wait objects and some creative parameters were used for this very reason in the example experiments.

Presentation®

Preparation

Presentation® comes with LSL already included. It is very simple to just send LSL markers in parallel with other port codes.

(De)Activating LSL markers

Install Presentation®, run it and go to the settings. Here, you can easily activate LSL by checking the box Send event data to LSL under Lab Streaming Layer (Figure 5).

LSL Markers and/or Hardware Triggers with Brain Products and Presentation

Figure 5: Check the box “Send event data to LSL” in the Presentation® General settings tab.

In addition, you can select how such events should be represented in Presentation® and adjust the way LSL is handled in general. Click on Properties next to the “Send event data to LSL” check box and look at the settings in Figure 6. We recommend streaming the outlet already when the experiment is loaded. This makes it much easier to test you network connections as the LSL stream will immediately be visible on other clients that should have access to it. If you do not want to use LSL, just uncheck the box.

LSL Markers and/or Hardware Triggers with Brain Products and Presentation

Figure 6: A very practical setting is to select “Open stream outlet when experiment is loaded”. You can also choose whether to use xml-wrapped messages or simple event codes.

(De)Activating hardware triggers

First, install the TriggerBox Software and connect the TriggerBox (Plus). Then, you need to define and set up the output port in the Port settings tab (Figure 7). If there is no port available, simply add one and set it to the COM port of the connected TriggerBox (Plus). It is important to select “Emulate parallel”, but the other settings, except the “Rate” (baud rate), in “Properties”, see Figure 8, are irrelevant as was also the case in E-Prime®. To change the baud rate to 2 000 000 bits/s, as required for the TriggerBox Plus, you can simply enter the value in the “Custom rate” field after setting the “Rate” to custom.

Defining this output port is necessary to make it callable from your scripts. Please look at the example here for a very basic example on how to call the port.

If you do not want to send hardware triggers, you can simply change the line write_codes = true to write_codes = false. In this case, hardware triggers are no longer sent but LSL markers will still be used.

LSL Markers and/or Hardware Triggers with Brain Products and Presentation

Figure 7: Output port 1 is set to COM3 which is where the TriggerBox (Plus) is connected.

LSL Markers and/or Hardware Triggers with Brain Products and Presentation

Figure 8: Make sure there are values selected in all of the drop-down menus.

Presentation® tips

  • If you load the experiment with the output port configured but no TriggerBox (Plus) is connected, you will get a warning. Simply connect the TriggerBox (Plus) and restart Presentation® so you do not have to reconfigure the settings.

  • There are several ways to adjust the timing of stimuli. In this example, we only care about the synchronization of events, but in the experiment summary of Presentation®, you will notice that durations occasionally last longer than the requested 500 ms.

  • In the Presentation® example, we do not set the hardware trigger back to zero when the square goes black. Instead, there is a fixed pulse width of 10 ms. This is only relevant as there is no “0” hardware trigger at the same time of the “0” LSL marker.

PsychoPy

Preparation

Install the latest version of PsychoPy from here. We recommend using the stand-alone version, as it usually works best and does not interfere with other Python-based installations. The previously mentioned timing-verification article is based on PsychoPy, so please look it up for more information. Basically, the script takes care of all the necessary imports and defines the LSL stream parameters and serial port interface. A function called send_triggers is defined that sends both, hardware triggers and LSL markers, at the same time, ideally, when the screen is refreshing. Timing is based on the screen refresh rate of the computer monitor in use. Please consider this when you use a refresh rate other than 60 Hz. We tried to keep the code to a minimum, and therefore avoided Builder, the graphical experiment interface in PsychoPy. Instead, all of the code was written directly in the Coder interface. If you want, you can of course still give it a try and see how it works for you. You can look at the linked press release article and/or download the PsychoPy example here.

(De)Activating LSL markers

To be able to use LSL, make sure that pylsl is installed on your computer. If you do not want to use LSL markers, either simply ignore them, or comment the part where the LSL stream is generated

and/or the LSL markers are sent via the function send_triggers (last line):

(De)Activating hardware triggers

To be able to control the TriggerBox (Plus), make sure that serial is installed on your computer, that the TriggerBox Software is installed and that the TriggerBox (Plus) is connected. Other than that, the procedure is similar to (de)activating LSL markers: simply comment the lines for creating the serial port,

closing it,

and/or the part where hardware triggers are sent via the function send_triggers:

Psychtoolbox

Preparation

Psychtoolbox is a free set of functions for MATLAB®. Follow the instructions on psychtoolbox.org to download and install it. Also, make sure to install the MATLAB interface for liblsl. In the very basic example we provide, we follow the same paradigm of the flashing square again. Note that, similar to PsychoPy, the square is drawn as opposed to being loaded as an image. There are more similarities: the lsl_loadlib() needs to be loaded prior to using LSL and we define and open the LSL stream in the beginning. We also define and open the serial port by entering the COM port and a baud rate (again, you can just use 2 000 000 whether you are actually using the TriggerBox Plus or not). Timing of stimuli is again based on the number of frames, which are calculated based on the screen refresh rate.

In the loop, we either push “1” or “0” to the LSL stream and send a trigger via the serial interface at the same time immediately when the square changes to bright or dark.

(De)Activating LSL markers

Using or not using LSL depends on whether the LSL stream is created and whether you use the push sample function or not. Simply comment these lines

And the sending parts in the for loop:

If you do not want to use LSL. Otherwise leave them uncommented.

(De)Activating hardware triggers

Again, install the TriggerBox Software and connect the TriggerBox (Plus). To choose between using or not using hardware triggers, comment or uncomment the serial port-relevant code lines:

TriggerBox Test IO with LSL

The TriggerBox Software is required for interfacing the TriggerBox via the serial port, no matter the stimulus presentation tool. The software installation includes the TriggerBox Test IO which can be useful for several things. If the TriggerBox is connected, it lets you turn on/off individual bits or cycle through all bits with an arbitrary cycle period. If you are using the TriggerBox, you can add optional LSL markers to your output. For the TriggerBox Plus, this is not necessary, as the TriggerBox Plus creates its own LSL markers (Figure 9).

TriggerBox Test IO with LSL

Figure 9: TriggerBox Test IO 1.3.0 with optional LSL marker output.

When activated, a stream is immediately created and whenever a hardware trigger is set, an according LSL marker is sent via this LSL stream as an integer.

This is a nice tool to demonstrate LSL functionality and to test your setup, for example to see if the network connection is stable and if all the connections are done right. It is, however, not a realistic setup, as the timing of events is optimized.

Recording and analyzing with different setups

Now that you have all the information on the specific stimulus presentation software tools, let us get back to what all of them have in common. All of the provided examples aim to provide you with two things:

1. A simple paradigm to get to know how to use LSL and hardware triggers in various stimulus presentation software tools.
2. A means to verify potential problems in your setup, such as jitter or latencies.

There already is an explanation on what you need to do for setting up a complete LSL pipeline here, therefore, we will just summarize again shortly what you need for setting up the whole pipeline:

  • Choose the amplifier you want to use and get the according LSL connector app from the Brain Products GitHub page.

  • Decide if you want to use photo sensor, hardware triggers, and LSL markers, or just hardware triggers and LSL markers. Connect the required hardware accordingly. For example, attach the photo sensor to the upper left corner of the screen an plug it into an AUX input on the actiCHamp (Plus) or on the LiveAmp’s Sensor and Trigger Extension. Of course, also connect the TriggerBox (Plus) to the stimulus presentation computer via USB and to the amplifier via trigger cable.

  • When using the LSL connector app, always go for EEG Channel under LSL Trigger Output Style
    (see Figure 10 for an example based on the LiveAmp LSL connector app).

  • Use the BrainVision LSL Viewer for visualization.

  • Use LabRecorder for recording the data.

  • Use one of the provided scripts for analysis or load your data in MATLAB®, MNELAB, or in BrainVision Analyzer 2
    (after converting it to BrainVision data format in MNE/MNELAB or MATLAB®/EEGLAB).

Recording and analyzing with different setups

Figure 10: The LiveAmp LSL connector app with the LSL Trigger Output Style set to EEG Channel.

Analysis and interpretation of results

Please look at the Press Release article about timing verification. This article is based exclusively on PsychoPy, whereas now you can do the same thing also with Presentation®, E-Prime®, Psychtoolbox, and, to some degree, with the TriggerBox Test IO. In addition, we provide two scripts, one based on MATLAB®, and one based on Python/MNE. Please feel free to modify the scripts to accommodate your data as well, if needed. If you want to use the MATLAB® script, simply install the MATLAB importer for XDF files. For the Python script, make sure to install MNELAB, at least version 0.8.6.

You can also watch the free webinar recording to see these scripts in action and to get further ideas, for example how to use a combination of MNELAB and BrainVision Analyzer 2 without having to run any script. We also provide some example recordings with different settings, such as stimulus presentation software, amplifier, number of channels, or the type of trigger channel. The txt file in the linked zip file explains the respective recording settings.

What can you do with the scripts?

  • The two scripts should give you the same results, no matter what data you use it on. You just need to fulfill some requirements:

    1. At least one trigger channel.
    2. One LSL marker stream. We only look at values greater than zero in the provided examples.
    3. If a photo signal is used, it has to be named “PS”. If such a channel is found, the signal is analyzed, and the rising edge is used to generate photo-signal based triggers.
    4. There has to be the same number of triggers for all modalities. If one is missing or if there is one too many (e.g., after an unintentional screen flash), they have to be corrected manually.
  • The resulting figures at the end of this post show the latencies and jitter between all the event modalities; either between hardware triggers and LSL markers, or also between both of those compared to photo triggers. Thereby, you get an impression on how these events are handled differently by your stimulus presentation software tool of choice.

What do the figures tell you?

  • You may notice that photo triggers appear later than expected. This indicates that it takes one or more additional screen refresh cycles (16.67 ms for a 60 Hz monitor) for the actual stimulus to appear.

  • You will also notice that LSL markers always appear before hardware triggers. This is related to the type of amplifier, the number of channels, and the sampling rate. For example, LiveAmp adds a delay of ~12 ms due to the data transmission via Bluetooth, whereas for actiCHamp (Plus) it is in the low ms range. We recommend testing with the same setup you are going to use in your experiment to know exactly what kind of latency to expect and account for, if necessary.

  • You will observe differences between stimulus presentation software tools. Please see some examples below. These figures represent the resulting delays that were recorded in very specific situations where even the type of recording computer can make a difference. It is also definitely possible to optimize settings and reduce latencies. We encourage you to investigate and improve results and would be happy if our examples help you on the way.

  • All of the figures demonstrate the latencies between hardware triggers (HW), LSL markers (LSL), and photo triggers (PS), plotted over the number of events and the corresponding mean±standard deviation in milliseconds.

  • There are some examples from MATLAB® and some from Python/MNE. They both should give the same results. There are only some minor visual differences.

We hope that this collection of ideas, examples, scripts, and recordings can help you with your specific research interests. Please do not hesitate to contact us if you have further questions or if you want to share your experience with LSL markers and hardware triggers in your experiments.

Figures

LSL Markers and/or Hardware Triggers with Brain Products and Various Stimulus Presentation Software Tools

Figure 11: E-Prime_11.xdf. Recorded with E-Prime®. LiveAmp 500 Hz, only 1 photo sensor channel, 1000 trials (500 bright squares). HW = hardware triggers. PS = photo triggers. LSL = LSL markers. LSL markers are ahead of hardware and photo triggers, due to the latency of the signals recorded via the amplifier. Note that hardware triggers and photo triggers appear almost simultaneously.

LSL Markers and/or Hardware Triggers with Brain Products and Various Stimulus Presentation Software Tools

Figure 12: Presentation_26.xdf. Recorded with Presentation®. LiveAmp 1000 Hz, 32 EEG channels, 3 accelerometer channels, 1 photo sensor channel, 1000 trials (500 bright squares). Analyzed in MATLAB®. HW = hardware triggers. PS = photo triggers. LSL = LSL markers. The latency increases with the number of channels. Hardware triggers appear a very short time before photo triggers.

LSL Markers and/or Hardware Triggers with Brain Products and Various Stimulus Presentation Software Tools

Figure 13: Presentation_27.xdf. Recorded with Presentation®. LiveAmp 1000 Hz, 1 EEG channel, 3 accelerometer channels, 1 photo sensor channel, 1000 trials (500 bright squares). Analyzed in Python. HW = hardware triggers. PS = photo triggers. LSL = LSL markers. Reducing the number of channels decreases the latency.

LSL Markers and/or Hardware Triggers with Brain Products and Various Stimulus Presentation Software Tools

Figure 14: Presentation_28.xdf. Recorded with Presentation®. actiCHamp Plus 1000 Hz, 64 EEG channels, 1 photo sensor channel, 1000 trials (500 bright squares). Analyzed in Python. HW = hardware triggers. PS = photo triggers. LSL = LSL markers. Changing from LiveAmp to actiCHamp Plus has a big impact on the latency as there is no delay due to the Bluetooth connection.

LSL Markers and/or Hardware Triggers with Brain Products and Various Stimulus Presentation Software Tools

Figure 15: Presentation_29.xdf. Recorded with Presentation®. actiCHamp Plus 1000 Hz, 1 EEG channel, 1 photo sensor channel, 1000 trials (500 bright squares). Analyzed in Python. HW = hardware triggers. PS = photo triggers. LSL = LSL markers. Reducing the number of channels decreases the latency even more.

LSL Markers and/or Hardware Triggers with Brain Products and Various Stimulus Presentation Software Tools

Figure 16: PsychoPy_21.xdf. Recorded with PsychoPy. LiveAmp 1000 Hz, 1 photo sensor channel, 1000 trials (500 bright squares). Analyzed in Python. HW = hardware triggers. PS = photo triggers. LSL = LSL markers. In this example based on PsychoPy, hardware triggers appear ~18 ms before photo triggers. This indicates an additional, unwanted screen refresh cycle.

LSL Markers and/or Hardware Triggers with Brain Products and Various Stimulus Presentation Software Tools

Figure 17: TestIO_30.xdf. Recorded with the TriggerBox Test IO. LiveAmp 1000 Hz, 1 EEG channel, only Device Trigger. Analyzed in MATLAB®. HW = hardware triggers. LSL = LSL markers. The range on the y-axis is considerably smaller and unrealistically exact trigger intervals result in this sawtooth-like interference.

LSL Markers and/or Hardware Triggers with Brain Products and Various Stimulus Presentation Software Tools

Figure 18: PTB_16.xdf. Recorded with Psychtoolbox. LiveAmp 1000 Hz, 1 photo sensor channel, 2000 trials (1000 bright squares). Analyzed in MATLAB®. HW = hardware triggers. LSL = LSL markers. PS = photo triggers. In this case, there are even two additional screen refresh cycles, causing the photo triggers to appear more than 33 ms after the hardware triggers.