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
- Study Name: LSL markers versus hardware triggers
- Fields: LSL, EEG, data acquisition, data analysis
- Project run in house at Brain Products
- Webinar Recording: click here
- Hardware used: Brain Products EEG amplifier, TriggerBox (Plus)
- Software used: Lab Streaming Layer (LSL), PsychoPy, MATLAB®, E-Prime®, Presentation®
- Code: mostly Open Source
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:
- 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.
- 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.
- 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.
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.
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.
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”.
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
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).
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.
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.
Figure 7: Output port 1 is set to COM3 which is where the TriggerBox (Plus) is connected.
Figure 8: Make sure there are values selected in all of the drop-down menus.
Presentation® tips
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
info = StreamInfo(name=“LSL_Markers”, type=“Markers”, channel_count=1,
channel_format=“int32”, source_id=“PsychoPy Markers”)
outlet = StreamOutlet(info)
and/or the LSL markers are sent via the function send_triggers (last line):
def send_triggers(value):
“””Send value as hardware trigger and LSL marker.”””
port.write(value)
outlet.push_sample(value)
(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:
def send_triggers(value):
“””Send value as hardware trigger and LSL marker.”””
port.write(value)
outlet.push_sample(value)
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
% LSL Setup
lib = lsl_loadlib();LSL_markers_info = lsl_streaminfo(lib,‘TriggerStream’,‘Markers’,1,0,‘cf_int32’,‘SourceID42’);
LSL_markers = lsl_outlet(LSL_markers_info);
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 Setup:
port = serialport(‘COM3’,2000000);
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).
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:
Note: You can use the LiveAmp without a Sensor and Trigger Extension if you only want to use a single bit trigger. In this case, please ask for a cable that connects only one line of the 8-bit trigger cable to the Trigger In port on the LiveAmp (the 2.5 mm jack connector). Alternatively, you can also directly connect a StimTrak to the LiveAmp Trigger In and use triggers based on the Photo Sensor signal instead. This way, you can either compare LSL markers to hardware triggers or to photo triggers.
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?
What do the figures tell you?
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
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.
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.
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.
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.
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.
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.
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.
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.