Willkommen! In diesem Tutorial lernen wir, wie man das Lab Streaming Layer (LSL) in Python verwendet, um Emotiv EEG-Daten von mehreren Geräten zu erfassen und zu synchronisieren. Es erfordert grundlegende Kenntnisse der Programmiersprache Python.

Was Sie lernen werden

1. Was das Lab Streaming Layer (LSL) ist und warum Forscher es verwenden

2. Wie man synchronisierte Daten von mehreren Emotiv EEG-Geräten erfasst

3. Wie man erfasste Daten importiert und überprüft

1.1 Was ist LSL und wofür ist es gut?

Lab Streaming Layer (LSL) ist eine Open-Source-Toolbox, die verwendet werden kann, um neuronale, physiologische und Verhaltensdatenströme von verschiedenen Sensor-Hardwares zu senden, zu empfangen und zu synchronisieren. Immer leistungsfähigere, präzisere und mobilere Gehirn- und Körpersensor-Hardwaregeräte (wie die EEG-Systeme von Emotiv) bringen die Neurowissenschaften aus dem Labor in die Welt der Echtzeitdaten. Während Gehirnmessungen wie EEG und MEG früher auf Forschungslabors beschränkt waren, ermöglichen uns mobile Geräte, mehrere Daten in natürlicheren Umgebungen und von mehreren Personen gleichzeitig zu erfassen.

Ein Forscher könnte an der physiologischen Synchronie zwischen zwei Personen interessiert sein, die dieselbe Musik hören. LSL kann uns helfen, Daten von zwei EEG-Headsets separat zu erfassen, die zudem mit der Präsentation des Tons synchronisiert sind.

Einige Beispiele für andere Anwendungen von LSL:

1. Hinzufügen von Ereignismarkern aus einem Experiment zu laufenden EEG-Daten

2. Zeitliche Ausrichtung von Daten aus mehreren Quellen für einen einzelnen Teilnehmer (z. B. Herzfrequenz, EMG, EEG)

3. Zeitliche Ausrichtung von Daten von mehreren Teilnehmern (z. B. EEG-Hyperscanning-Studien)

1.2 Wie funktioniert LSL?

Lab Streaming Layer ist ein Protokoll für den Echtzeit-Austausch von Zeitreihendaten zwischen mehreren Geräten. LSL kann mithilfe von Open-Source-Bibliotheken für Programmiersprachen wie Python, MATLAB, C++, Java und andere implementiert werden.

Die Kernfunktionalität dreht sich um LSL-Datenströme:

1. Ein Erfassungsgerät/eine Software sammelt Daten und erstellt einen Datenstrom - Physiologische Daten können von EEG-Aufzeichnungsgeräten, Eye-Trackern, Motion-Capture-Systemen, Herzfrequenzmonitoren usw. an LSL gestreamt werden, einschließlich Metadaten (Abtastrate, Datentyp, Kanalinformationen usw.) - Ereignismarker aus Experimenten (z. B. mit PsychoPy) können ebenfalls als Datenstrom über LSL gesendet werden

2. Der Datenstrom wird im Netzwerk veröffentlicht - So werden Daten mit LSL gesendet; der Datenstrom wird im Netzwerk „ausgestrahlt“ - Veröffentlichte Ströme sind im Netzwerk verfügbar und für andere LSL-unterstützte Geräte im selben Netzwerk auffindbar - LSL weist jedem Datenblock oder jeder Probe einen Zeitstempel basierend auf einer gemeinsamen Uhr zu (nach dem Network Time Protocol). - Der Strom wird Probe für Probe (oder Block für Block) durch ein „Outlet“ übertragen

3. Erfassungsgeräte „abonnieren“ Datenströme - So werden Daten mit LSL empfangen - Erfassungsgeräte im selben Netzwerk empfangen veröffentlichte Datenströme über „Inlets“. - Jedes Inlet empfängt die Stromproben und Metadaten von nur einem Outlet

4. Daten speichern - Nach dem Abonnieren eines Datenstroms können Sie ihn in einer Variablen in Ihrer bevorzugten Programmiersprache speichern oder die von LSL bereitgestellte Software LabRecorder verwenden, um ihn in einem Standardformat wie .xdf zu speichern.

2.0 Tutorial-Übersicht

In diesem Tutorial nehmen wir ein Beispiel für einen Versuchsaufbau und führen Sie durch die notwendigen Schritte und den Code für die Implementierung mit LSL in Python. Wir werden Python verwenden, um einen Ton abzuspielen, während wir EEG-Daten von zwei Personen erfassen, die Emotiv-Headsets tragen. Wir werden zwei Computer verwenden, auf denen jeweils EmotivPRO läuft, um die EEG-Daten zu erfassen und jeden Strom über ein separates LSL-Outlet zu übertragen. Wir werden eine Python-Bibliothek verwenden, um eine Audiodatei abzuspielen und gleichzeitig bei jedem Start der Datei einen Trigger zu senden.

SCHRITTE:

1. Verwenden Sie EmotivPRO, um Daten über LSL-Outlets zu streamen, die EEG-Daten (und/oder Bewegung, Kontaktqualität, Signalqualität usw.) enthalten. 2. Spielen Sie eine Tonspur mit einem Python-Skript ab und senden Sie gleichzeitig einen Trigger über ein anderes LSL. Verwenden Sie LabRecorder, um alle drei Datenströme über ein LSL-Inlet zu erfassen und zu speichern.

2.1 SCHRITT 1 - Einrichtung und Installation

1. Sie benötigen unterstützte Datenerfassungsgeräte zum Sammeln von Daten
   • Alle Brainware-Geräte von Emotiv verbinden sich über die EmotivPRO-Software mit LSL

2. Installieren Sie EmotivPRO auf Ihren Geräten. Sie benötigen eine gültige EmotivPRO-Lizenz, um LSL zu verwenden.

3. Installieren Sie die Python-LSL-Bibliothek mit dem folgenden Befehl:
   pip install pylsl

4. Laden Sie die LabRecorder-Software herunter. Dies ist eine einfache, kostenlose App, die über die
   Kommandozeile oder als eigenständiger Download ausgeführt werden kann

5. Für unser Experiment: Installieren Sie die erforderlichen Pakete zum Abspielen von Audio mit Python
   pip install sounddevice soundfile

2.2 SCHRITT 3 - Senden der Daten aus EmotivPRO über einen LSL-Stream

1. Suchen Sie das „…“-Symbol in der oberen rechten Ecke der App und navigieren Sie zu den Einstellungen

2. Suchen Sie den Abschnitt „Lab Streaming Layer“ und den Unterabschnitt „Outlet“

3. Wählen Sie alle Datentypen aus, die Sie übertragen möchten

4. Wählen Sie das Datenformat (32-Bit-Float oder 64-Bit-Double)

5. Wählen Sie aus, ob Daten Probe für Probe oder in Blöcken von Proben gesendet werden sollen

6. Klicken Sie auf „Start“, um einen LSL-Datenstrom zu übertragen

2.3 SCHRITT 4 - Verwenden eines Python-Skripts zum Abspielen von Audio und Senden von Triggern

1. Kopieren Sie den folgenden Codeblock und fügen Sie ihn in eine Python-Datei ein und speichern Sie diese auf Ihrem Computer.

2. Suchen Sie eine Audiodatei (idealerweise eine .wav-Datei), die Sie abspielen möchten, und bearbeiten Sie das Skript, indem Sie die
   Variable audio_filepath in den Dateipfad Ihrer Audiodatei auf Ihrem Computer ändern

3. Öffnen Sie eine Eingabeaufforderung, um mit der Befehlszeile zu interagieren, und navigieren Sie zu dem Ordner, in dem
   Ihre Python-Datei gespeichert ist

4. Geben Sie ein: python3 dateiname.py
   • Abhängig von Ihrer Python-Installation können Sie python anstelle von python3 verwenden
   
   Hinweis: Ersetzen Sie /path/to/audio.wav durch den Speicherort der Audiodatei, die Sie während Ihres Experiments abspielen möchten.

"""
LSL Example: Play audio and send a trigger marker
<p>This script creates an LSL marker stream, waits for the user to<br>press ENTER, then plays an audio file and sends a marker that<br>can be synchronized with EEG data collected through LabRecorder.<br>"""</p>
<p>import sounddevice as sd<br>import soundfile as sf<br>from pylsl import StreamInfo, StreamOutlet</p>
<p>def wait_for_keypress():<br>print("Press ENTER to start audio playback and send an LSL marker.")<br>while True:<br>if input() == "":<br>break</p>
<p>def play_audio_and_send_marker(audio_file, outlet):<br>data, fs = sf.read(audio_file)</p>
<pre><code>print("Playing audio and sending LSL marker...")

marker_val = [1]
outlet.push_sample(marker_val)

sd.play(data, fs)
sd.wait()

print("Audio playback finished.")
</code></pre>
<p>if <strong>name</strong> == "<strong>main</strong>":</p>
<pre><code>info = StreamInfo(
    name="AudioMarkers",
    type="Markers",
    channel_count=1,
    nominal_srate=0,
    channel_format="int32",
    source_id="uniqueMarkerID12345"
)

outlet = StreamOutlet(info)

while True:
    wait_for_keypress()

    audio_filepath = "/path/to/audio.wav"

    play_audio_and_send_marker(
        audio_filepath,
        outlet
    )</code></pre><h2 dir="auto">2.4 STEP 5 - Use LabRecorder to view and save all LSL streams</h2><ol dir="auto"><li data-preset-tag="p"><p>Open LabRecorder</p></li><li data-preset-tag="p"><p>Press <code>Update</code>. The available LSL streams should be visible in the stream list<br>• You should be able to see streams from both EmotivPROs (usually called “Emotiv-<br>DataStream”) and the marker stream (called “AudioMarkers”)</p></li><li data-preset-tag="p"><p>Click <code>Browse</code> to select a location to store data (and set other parameters)</p></li><li data-preset-tag="p"><p>Select all streams and press <code>Record</code> to start recording</p></li></ol><h2 dir="auto">3.0 Working with the data</h2><p dir="auto">LabRecorder outputs an XDF file (Extensible Data Format) that contains data from all the streams. XDF files are structured into, streams, each with a different header that describes what it contains (device name, data type, sampling rate, channels, and more). You can use the below codeblock to open your XDF file and display some basic information.</p><p dir="auto"><strong>Note: Replace </strong><code><strong>/path/to/your/file.xdf</strong></code><strong> with the filepath for your LabRecorder XDF output file.</strong></p><pre data-language="JSX"><code>import pyxdf
</code></pre>
<p>import mne<br>import matplotlib.pyplot as plt<br>import numpy as np</p>
<h1>Give the path to your LSL output file here.</h1>
<p>data_path = "/path/to/your/file.xdf"</p>
<h1>Load the XDF file.</h1>
<p>streams, fileheader = pyxdf.load_xdf(data_path)</p>
<p>print("XDF File Header:", fileheader)<br>print("Number of streams found:", len(streams))</p>
<p>for i, stream in enumerate(streams):<br>print("\nStream", i + 1)<br>print("Stream Name:", stream["info"]["name"][0])<br>print("Stream Type:", stream["info"]["type"][0])<br>print("Number of Channels:", stream["info"]["channel_count"][0])</p>
<pre><code>sfreq = float(stream["info"]["nominal_srate"][0])
print("Sampling Rate:", sfreq)

print("Number of Samples:", len(stream["time_series"]))
print("First 5 data points:", stream["time_series"][:5])

channel_names = [
    chan["label"][0]
    for chan in stream["info"]["desc"][0]["channels"][0]["channel"]
]

print("Channel Names:", channel_names)

channel_types = "eeg"</code></pre><h3 dir="auto"><br></h3><h2 dir="auto">4.0 Additional Resources</h2><h4 dir="auto">Official Documentation</h4><ol dir="auto"><li data-preset-tag="p"><p>Check out the <a href="1. Check out the online documentation, including the official README file on GitHub 2. Additional resources: • Code to run LSL using Emotiv’s devices, with example scripts • Useful LSL demo on YouTube • SCCN LSL GitHub repository for all associated libraries • LSL GitHub repository for a collection a submodules and apps 3. HyPyP analysis pipeline for Hyperscanning studies" target="_blank">online documentation</a>, including the <a href="https://github.com/sccn/labstreaminglayer/" target="_blank">official README file on GitHub</a></p></li><li data-preset-tag="p"><p>Additional resources:<br>• <a href="https://github.com/Emotiv/labstreaminglayer" target="_blank">Code</a> to run LSL using Emotiv’s devices, with example scripts<br>• Useful <a href="https://www.youtube.com/watch?v=Y1at7yrcFW0&amp;list=PLVnr33MP5RMRhGwY36zHHDOmAaYTB138D" target="_blank">LSL demo on YouTube</a><br>• <a href="https://github.com/sccn/labstreaminglayer" target="_blank">SCCN LSL GitHub repository</a> for all associated libraries<br>• <a href="https://github.com/labstreaminglayer" target="_blank">LSL GitHub repository</a> for a collection a submodules and apps</p></li><li data-preset-tag="p"><p><a href="https://academic.oup.com/scan/article/16/1-2/72/5919711?login=false" target="_blank">HyPyP analysis pipeline</a> for Hyperscanning studies</p></li></ol>
</code></pre

"""
LSL Example: Play audio and send a trigger marker
<p>This script creates an LSL marker stream, waits for the user to<br>press ENTER, then plays an audio file and sends a marker that<br>can be synchronized with EEG data collected through LabRecorder.<br>"""</p>
<p>import sounddevice as sd<br>import soundfile as sf<br>from pylsl import StreamInfo, StreamOutlet</p>
<p>def wait_for_keypress():<br>print("Press ENTER to start audio playback and send an LSL marker.")<br>while True:<br>if input() == "":<br>break</p>
<p>def play_audio_and_send_marker(audio_file, outlet):<br>data, fs = sf.read(audio_file)</p>
<pre><code>print("Playing audio and sending LSL marker...")

marker_val = [1]
outlet.push_sample(marker_val)

sd.play(data, fs)
sd.wait()

print("Audio playback finished.")
</code></pre>
<p>if <strong>name</strong> == "<strong>main</strong>":</p>
<pre><code>info = StreamInfo(
    name="AudioMarkers",
    type="Markers",
    channel_count=1,
    nominal_srate=0,
    channel_format="int32",
    source_id="uniqueMarkerID12345"
)

outlet = StreamOutlet(info)

while True:
    wait_for_keypress()

    audio_filepath = "/path/to/audio.wav"

    play_audio_and_send_marker(
        audio_filepath,
        outlet
    )</code></pre><h2 dir="auto">2.4 STEP 5 - Use LabRecorder to view and save all LSL streams</h2><ol dir="auto"><li data-preset-tag="p"><p>Open LabRecorder</p></li><li data-preset-tag="p"><p>Press <code>Update</code>. The available LSL streams should be visible in the stream list<br>• You should be able to see streams from both EmotivPROs (usually called “Emotiv-<br>DataStream”) and the marker stream (called “AudioMarkers”)</p></li><li data-preset-tag="p"><p>Click <code>Browse</code> to select a location to store data (and set other parameters)</p></li><li data-preset-tag="p"><p>Select all streams and press <code>Record</code> to start recording</p></li></ol><h2 dir="auto">3.0 Working with the data</h2><p dir="auto">LabRecorder outputs an XDF file (Extensible Data Format) that contains data from all the streams. XDF files are structured into, streams, each with a different header that describes what it contains (device name, data type, sampling rate, channels, and more). You can use the below codeblock to open your XDF file and display some basic information.</p><p dir="auto"><strong>Note: Replace </strong><code><strong>/path/to/your/file.xdf</strong></code><strong> with the filepath for your LabRecorder XDF output file.</strong></p><pre data-language="JSX"><code>import pyxdf
</code></pre>
<p>import mne<br>import matplotlib.pyplot as plt<br>import numpy as np</p>
<h1>Give the path to your LSL output file here.</h1>
<p>data_path = "/path/to/your/file.xdf"</p>
<h1>Load the XDF file.</h1>
<p>streams, fileheader = pyxdf.load_xdf(data_path)</p>
<p>print("XDF File Header:", fileheader)<br>print("Number of streams found:", len(streams))</p>
<p>for i, stream in enumerate(streams):<br>print("\nStream", i + 1)<br>print("Stream Name:", stream["info"]["name"][0])<br>print("Stream Type:", stream["info"]["type"][0])<br>print("Number of Channels:", stream["info"]["channel_count"][0])</p>
<pre><code>sfreq = float(stream["info"]["nominal_srate"][0])
print("Sampling Rate:", sfreq)

print("Number of Samples:", len(stream["time_series"]))
print("First 5 data points:", stream["time_series"][:5])

channel_names = [
    chan["label"][0]
    for chan in stream["info"]["desc"][0]["channels"][0]["channel"]
]

print("Channel Names:", channel_names)

channel_types = "eeg"</code></pre><h3 dir="auto"><br></h3><h2 dir="auto">4.0 Additional Resources</h2><h4 dir="auto">Official Documentation</h4><ol dir="auto"><li data-preset-tag="p"><p>Check out the <a href="1. Check out the online documentation, including the official README file on GitHub 2. Additional resources: • Code to run LSL using Emotiv’s devices, with example scripts • Useful LSL demo on YouTube • SCCN LSL GitHub repository for all associated libraries • LSL GitHub repository for a collection a submodules and apps 3. HyPyP analysis pipeline for Hyperscanning studies" target="_blank">online documentation</a>, including the <a href="https://github.com/sccn/labstreaminglayer/" target="_blank">official README file on GitHub</a></p></li><li data-preset-tag="p"><p>Additional resources:<br>• <a href="https://github.com/Emotiv/labstreaminglayer" target="_blank">Code</a> to run LSL using Emotiv’s devices, with example scripts<br>• Useful <a href="https://www.youtube.com/watch?v=Y1at7yrcFW0&amp;list=PLVnr33MP5RMRhGwY36zHHDOmAaYTB138D" target="_blank">LSL demo on YouTube</a><br>• <a href="https://github.com/sccn/labstreaminglayer" target="_blank">SCCN LSL GitHub repository</a> for all associated libraries<br>• <a href="https://github.com/labstreaminglayer" target="_blank">LSL GitHub repository</a> for a collection a submodules and apps</p></li><li data-preset-tag="p"><p><a href="https://academic.oup.com/scan/article/16/1-2/72/5919711?login=false" target="_blank">HyPyP analysis pipeline</a> for Hyperscanning studies</p></li></ol>
</code></pre

"""
LSL Example: Play audio and send a trigger marker
<p>This script creates an LSL marker stream, waits for the user to<br>press ENTER, then plays an audio file and sends a marker that<br>can be synchronized with EEG data collected through LabRecorder.<br>"""</p>
<p>import sounddevice as sd<br>import soundfile as sf<br>from pylsl import StreamInfo, StreamOutlet</p>
<p>def wait_for_keypress():<br>print("Press ENTER to start audio playback and send an LSL marker.")<br>while True:<br>if input() == "":<br>break</p>
<p>def play_audio_and_send_marker(audio_file, outlet):<br>data, fs = sf.read(audio_file)</p>
<pre><code>print("Playing audio and sending LSL marker...")

marker_val = [1]
outlet.push_sample(marker_val)

sd.play(data, fs)
sd.wait()

print("Audio playback finished.")
</code></pre>
<p>if <strong>name</strong> == "<strong>main</strong>":</p>
<pre><code>info = StreamInfo(
    name="AudioMarkers",
    type="Markers",
    channel_count=1,
    nominal_srate=0,
    channel_format="int32",
    source_id="uniqueMarkerID12345"
)

outlet = StreamOutlet(info)

while True:
    wait_for_keypress()

    audio_filepath = "/path/to/audio.wav"

    play_audio_and_send_marker(
        audio_filepath,
        outlet
    )</code></pre><h2 dir="auto">2.4 STEP 5 - Use LabRecorder to view and save all LSL streams</h2><ol dir="auto"><li data-preset-tag="p"><p>Open LabRecorder</p></li><li data-preset-tag="p"><p>Press <code>Update</code>. The available LSL streams should be visible in the stream list<br>• You should be able to see streams from both EmotivPROs (usually called “Emotiv-<br>DataStream”) and the marker stream (called “AudioMarkers”)</p></li><li data-preset-tag="p"><p>Click <code>Browse</code> to select a location to store data (and set other parameters)</p></li><li data-preset-tag="p"><p>Select all streams and press <code>Record</code> to start recording</p></li></ol><h2 dir="auto">3.0 Working with the data</h2><p dir="auto">LabRecorder outputs an XDF file (Extensible Data Format) that contains data from all the streams. XDF files are structured into, streams, each with a different header that describes what it contains (device name, data type, sampling rate, channels, and more). You can use the below codeblock to open your XDF file and display some basic information.</p><p dir="auto"><strong>Note: Replace </strong><code><strong>/path/to/your/file.xdf</strong></code><strong> with the filepath for your LabRecorder XDF output file.</strong></p><pre data-language="JSX"><code>import pyxdf
</code></pre>
<p>import mne<br>import matplotlib.pyplot as plt<br>import numpy as np</p>
<h1>Give the path to your LSL output file here.</h1>
<p>data_path = "/path/to/your/file.xdf"</p>
<h1>Load the XDF file.</h1>
<p>streams, fileheader = pyxdf.load_xdf(data_path)</p>
<p>print("XDF File Header:", fileheader)<br>print("Number of streams found:", len(streams))</p>
<p>for i, stream in enumerate(streams):<br>print("\nStream", i + 1)<br>print("Stream Name:", stream["info"]["name"][0])<br>print("Stream Type:", stream["info"]["type"][0])<br>print("Number of Channels:", stream["info"]["channel_count"][0])</p>
<pre><code>sfreq = float(stream["info"]["nominal_srate"][0])
print("Sampling Rate:", sfreq)

print("Number of Samples:", len(stream["time_series"]))
print("First 5 data points:", stream["time_series"][:5])

channel_names = [
    chan["label"][0]
    for chan in stream["info"]["desc"][0]["channels"][0]["channel"]
]

print("Channel Names:", channel_names)

channel_types = "eeg"</code></pre><h3 dir="auto"><br></h3><h2 dir="auto">4.0 Additional Resources</h2><h4 dir="auto">Official Documentation</h4><ol dir="auto"><li data-preset-tag="p"><p>Check out the <a href="1. Check out the online documentation, including the official README file on GitHub 2. Additional resources: • Code to run LSL using Emotiv’s devices, with example scripts • Useful LSL demo on YouTube • SCCN LSL GitHub repository for all associated libraries • LSL GitHub repository for a collection a submodules and apps 3. HyPyP analysis pipeline for Hyperscanning studies" target="_blank">online documentation</a>, including the <a href="https://github.com/sccn/labstreaminglayer/" target="_blank">official README file on GitHub</a></p></li><li data-preset-tag="p"><p>Additional resources:<br>• <a href="https://github.com/Emotiv/labstreaminglayer" target="_blank">Code</a> to run LSL using Emotiv’s devices, with example scripts<br>• Useful <a href="https://www.youtube.com/watch?v=Y1at7yrcFW0&amp;list=PLVnr33MP5RMRhGwY36zHHDOmAaYTB138D" target="_blank">LSL demo on YouTube</a><br>• <a href="https://github.com/sccn/labstreaminglayer" target="_blank">SCCN LSL GitHub repository</a> for all associated libraries<br>• <a href="https://github.com/labstreaminglayer" target="_blank">LSL GitHub repository</a> for a collection a submodules and apps</p></li><li data-preset-tag="p"><p><a href="https://academic.oup.com/scan/article/16/1-2/72/5919711?login=false" target="_blank">HyPyP analysis pipeline</a> for Hyperscanning studies</p></li></ol>
</code></pre