Willkommen! In diesem Tutorial lernen wir, wie man den 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 der Lab Streaming Layer (LSL) ist und warum Forscher ihn nutzen

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?

Der Lab Streaming Layer (LSL) ist eine Open-Source-Toolbox, mit der neuronale, physiologische und Verhaltensdatenströme von verschiedenen Sensor-Hardwarekomponenten gesendet, empfangen und synchronisiert werden können. Immer leistungsfähigere, präzisere und mobile Gehirn- und Körpersensor-Hardware (wie die Emotiv EEG-Systeme) bringen die Neurowissenschaften aus dem Labor in die Welt der Echtzeitdaten. Während Gehirnmessungen wie EEG und MEG früher auf Forschungslabore beschränkt waren, ermöglichen mobile Geräte heute die Erfassung von Datenmengen in natürlicheren Umgebungen und von mehreren Personen gleichzeitig.

Ein Forscher könnte sich für die physiologische Synchronie zwischen zwei Personen interessieren, die dieselbe Musik hören. LSL kann uns dabei helfen, Daten von zwei separaten EEG-Headsets zu erfassen, die zudem mit der Präsentation des Tons synchronisiert sind.

Einige Beispiele für weitere Einsatzzwecke von LSL:

1. Hinzufügen von Ereignismarkern (Event Markers) 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 mehrerer Teilnehmer (z. B. EEG-Hyperscanning-Studien)

1.2 Wie funktioniert LSL?

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

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

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

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

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

4. Daten speichern - Nach dem Abonnieren eines Datenstroms können Sie diesen 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 mit Emotiv-Headsets erfassen. Wir werden zwei Computer verwenden, auf denen jeweils EmotivPRO läuft, um die EEG-Daten zu erfassen und jeden Stream ü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 Audiospur mithilfe eines Python-Skripts ab und senden Sie gleichzeitig einen Trigger über eine andere LSL-Verbindung. 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 Ihrem Gerät bzw. Ihren Geräten. Sie benötigen eine gültige EmotivPRO-Lizenz, um LSL nutzen zu können.

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 notwendigen 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 rechten oberen Ecke der App und navigieren Sie zu „Settings“ (Einstellungen)

2. Suchen Sie den Bereich „Lab Streaming Layer“ und den Unterbereich „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 die Daten Sample für Sample oder in Blöcken (Chunks) gesendet werden sollen

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

2.3 SCHRITT 4 - Verwenden Sie ein Python-Skript, um Audio abzuspielen und Trigger zu senden

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

2. Suchen Sie eine Audiodatei (idealerweise ein .wav-Format), die Sie abspielen möchten, und bearbeiten Sie das Skript, indem Sie die
   Variable audio_filepath durch den Dateipfad zu Ihrer Audiodatei auf Ihrem Computer ersetzen

3. Öffnen Sie eine Eingabeaufforderung, um mit der Kommandozeile 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 verwenden Sie eventuell python anstelle von python3
   
   Hinweis: Ersetzen Sie /path/to/audio.wav durch den Pfad der Audiodatei, die Sie während des Experiments abspielen möchten.

"""
LSL Example: Play audio and send a trigger marker

This script creates an LSL marker stream, waits for the user to
press ENTER, then plays an audio file and sends a marker that
can be synchronized with EEG data collected through LabRecorder.
"""

import sounddevice as sd
import soundfile as sf
from pylsl import StreamInfo, StreamOutlet


def wait_for_keypress():
    print("Press ENTER to start audio playback and send an LSL marker.")
    while True:
        if input() == "":
            break


def play_audio_and_send_marker(audio_file, outlet):
    data, fs = sf.read(audio_file)

    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.")


if __name__ == "__main__":

    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
        )

"""
LSL Example: Play audio and send a trigger marker

This script creates an LSL marker stream, waits for the user to
press ENTER, then plays an audio file and sends a marker that
can be synchronized with EEG data collected through LabRecorder.
"""

import sounddevice as sd
import soundfile as sf
from pylsl import StreamInfo, StreamOutlet


def wait_for_keypress():
    print("Press ENTER to start audio playback and send an LSL marker.")
    while True:
        if input() == "":
            break


def play_audio_and_send_marker(audio_file, outlet):
    data, fs = sf.read(audio_file)

    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.")


if __name__ == "__main__":

    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
        )

"""
LSL Example: Play audio and send a trigger marker

This script creates an LSL marker stream, waits for the user to
press ENTER, then plays an audio file and sends a marker that
can be synchronized with EEG data collected through LabRecorder.
"""

import sounddevice as sd
import soundfile as sf
from pylsl import StreamInfo, StreamOutlet


def wait_for_keypress():
    print("Press ENTER to start audio playback and send an LSL marker.")
    while True:
        if input() == "":
            break


def play_audio_and_send_marker(audio_file, outlet):
    data, fs = sf.read(audio_file)

    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.")


if __name__ == "__main__":

    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
        )

2.4 SCHRITT 5 - LabRecorder zum Anzeigen und Speichern aller LSL-Streams verwenden

1. Öffnen Sie LabRecorder

2. Drücken Sie Update. Die verfügbaren LSL-Streams sollten in der Stream-Liste sichtbar sein
   • Sie sollten in der Lage sein, Streams von beiden EmotivPROs (normalerweise „Emotiv-
   DataStream“ genannt) und den Marker-Stream (genannt „AudioMarkers“) zu sehen

3. Klicken Sie auf Browse, um einen Speicherort für die Daten auszuwählen (und andere Parameter festzulegen)

4. Wählen Sie alle Streams aus und drücken Sie Record, um die Aufzeichnung zu starten

3.0 Mit den Daten arbeiten

LabRecorder gibt eine XDF-Datei (Extensible Data Format) aus, die Daten aus allen Streams enthält. XDF-Dateien sind in Streams strukturiert, von denen jeder einen anderen Header hat, der den Inhalt beschreibt (Gerätename, Datentyp, Abtastrate, Kanäle und mehr). Sie können den folgenden Codeblock verwenden, um Ihre XDF-Datei zu öffnen und einige grundlegende Informationen anzuzeigen.

Hinweis: Ersetzen Sie /path/to/your/file.xdf durch den Dateipfad Ihrer LabRecorder XDF-Ausgabedatei.

import pyxdf
import mne
import matplotlib.pyplot as plt
import numpy as np

# Give the path to your LSL output file here.
data_path = "/path/to/your/file.xdf"

# Load the XDF file.
streams, fileheader = pyxdf.load_xdf(data_path)

print("XDF File Header:", fileheader)
print("Number of streams found:", len(streams))

for i, stream in enumerate(streams):
    print("\nStream", i + 1)
    print("Stream Name:", stream["info"]["name"][0])
    print("Stream Type:", stream["info"]["type"][0])
    print("Number of Channels:", stream["info"]["channel_count"][0])

    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"

import pyxdf
import mne
import matplotlib.pyplot as plt
import numpy as np

# Give the path to your LSL output file here.
data_path = "/path/to/your/file.xdf"

# Load the XDF file.
streams, fileheader = pyxdf.load_xdf(data_path)

print("XDF File Header:", fileheader)
print("Number of streams found:", len(streams))

for i, stream in enumerate(streams):
    print("\nStream", i + 1)
    print("Stream Name:", stream["info"]["name"][0])
    print("Stream Type:", stream["info"]["type"][0])
    print("Number of Channels:", stream["info"]["channel_count"][0])

    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"

import pyxdf
import mne
import matplotlib.pyplot as plt
import numpy as np

# Give the path to your LSL output file here.
data_path = "/path/to/your/file.xdf"

# Load the XDF file.
streams, fileheader = pyxdf.load_xdf(data_path)

print("XDF File Header:", fileheader)
print("Number of streams found:", len(streams))

for i, stream in enumerate(streams):
    print("\nStream", i + 1)
    print("Stream Name:", stream["info"]["name"][0])
    print("Stream Type:", stream["info"]["type"][0])
    print("Number of Channels:", stream["info"]["channel_count"][0])

    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"

4.0 Zusätzliche Ressourcen

Offizielle Dokumentation

1. Sehen Sie sich die Online-Dokumentation an, einschließlich der offiziellen README-Datei auf GitHub

2. Zusätzliche Ressourcen:
   • Code zur Ausführung von LSL mit Emotiv-Geräten, mit Beispiel-Skripten
   • Hilfreiche LSL-Demo auf YouTube
   • SCCN LSL GitHub-Repository für alle zugehörigen Bibliotheken
   • LSL GitHub-Repository für eine Sammlung von Submodulen und Apps

3. HyPyP Analysis Pipeline für Hyperscanning-Studien