Witaj! W tym samouczku dowiemy się, jak używać Lab Streaming Layer (LSL) w języku Python do zbierania i synchronizowania danych EEG z wielu urządzeń Emotiv. Będzie to wymagało podstawowej wiedzy z zakresu programowania w języku Python.

Czego się nauczysz

1. Czym jest Lab Streaming Layer (LSL) i dlaczego naukowcy go używają

2. Jak zbierać zsynchronizowane dane z wielu urządzeń EEG Emotiv

3. Jak importować i kontrolować zebrane dane

1.1 Czym jest LSL i do czego służy?

Lab Streaming Layer (LSL) to pakiet narzędzi open-source, który może być używany do wysyłania, odbierania i synchronizowania strumieni danych neuronowych, fizjologicznych i behawioralnych z różnych urządzeń czujnikowych. Coraz bardziej wydajne, precyzyjne i mobilne urządzenia rejestrujące aktywność mózgu i ciała (takie jak systemy EEG Emotiv) wyprowadzają neuronaukę poza laboratorium, do świata danych w czasie rzeczywistym. Podczas gdy pomiary mózgu, takie jak EEG i MEG, były niegdyś ograniczone do laboratoriów badawczych, urządzenia mobilne pozwalają nam zbierać wiele danych w bardziej naturalnych środowiskach i od wielu osób jednocześnie.

Badacz może być zainteresowany fizjologiczną synchronizacją między dwiema osobami słuchającymi tej samej muzyki. LSL może pomóc nam w osobnym zbieraniu danych z dwóch zestawów słuchawkowych EEG, które są również zsynchronizowane z prezentacją dźwięku.

Oto kilka innych przykładów zastosowania LSL:

1. Dodawanie znaczników zdarzeń z eksperymentu do bieżących danych EEG

2. Synchronizacja czasowa danych z wielu źródeł dla jednego uczestnika (np. tętno, EMG, EEG)

3. Synchronizacja czasowa danych od wielu uczestników (np. badania hiperskanowania EEG)

1.2 Jak działa LSL?

Lab Streaming Layer to protokół do wymiany danych szeregów czasowych między wieloma urządzeniami w czasie rzeczywistym. LSL można wdrożyć za pomocą bibliotek open-source dla języków programowania takich jak Python, MATLAB, C++, Java i innych.

Podstawowa funkcjonalność opiera się na strumieniach danych LSL:

1. Urządzenie/oprogramowanie akwizycji zbiera dane i tworzy strumień danych – Dane fizjologiczne mogą być przesyłane strumieniowo do LSL z urządzeń rejestrujących EEG, urządzeń do śledzenia ruchu gałek ocznych (eye-trackery), systemów przechwytywania ruchu, monitorów tętna itp., wraz z metadanymi (częstotliwość próbkowania, typ danych, informacje o kanałach itp.) – Znaczniki zdarzeń z eksperymentów (np. przy użyciu PsychoPy) mogą być również wysyłane jako strumień danych przy użyciu LSL

2. Strumień danych jest publikowany w sieci – W ten sposób dane są wysyłane za pomocą LSL; strumień danych jest „transmitowany” do sieci – Opublikowane strumienie są dostępne w sieci i wykrywalne przez inne urządzenia obsługujące LSL w tej samej sieci – LSL przypisuje każdej paczce danych lub próbce znacznik czasu na podstawie wspólnego zegara (zgodnie z protokołem NTP) – Strumień jest przesyłany próbka po próbce (lub paczka po paczce) przez ujście („outlet”)

3. Urządzenie(a) zbierające „subskrybują” strumień(e) danych – W ten sposób dane są odbierane za pomocą LSL – Urządzenia zbierające w tej samej sieci odbierają opublikowane strumienie danych za pośrednictwem wejść („inlets”) – Każde wejście odbiera próbki strumienia i metadane tylko z jednego ujścia

4. Zapisywanie danych – Po zasubskrybowaniu strumienia danych możesz zapisać go do zmiennej w preferowanym języku programowania lub użyć dostarczonego oprogramowania LabRecorder w celu zapisania go do standardowego formatu, takiego jak .xdf.

2.0 Przegląd samouczka

W tym samouczku weźmiemy przykładową konfigurację eksperymentalną i przeprowadzimy Cię przez niezbędne kroki oraz kod do jej wdrożenia przy użyciu LSL w języku Python. Użyjemy Pythona do odtworzenia dźwięku podczas zbierania danych EEG od dwóch osób noszących zestawy słuchawkowe Emotiv. Użyjemy dwóch komputerów, z których każdy uruchamia EmotivPRO do zbierania danych EEG i będziemy transmitować każdy strumień przez oddzielne ujście LSL. Użyjemy biblioteki Python do odtworzenia pliku audio i jednoczesnego wysłania wyzwalacza przy każdym uruchomieniu pliku.

KROKI:

1. Użyj EmotivPRO do przesyłania strumieniowego danych przez ujścia LSL, w tym danych EEG (i/lub ruchu, jakości kontaktu, jakości sygnału itp.) 2. Odtwórz ścieżkę dźwiękową za pomocą skryptu Python i jednocześnie wyślij wyzwalacz przez inny LSL. Użyj LabRecorder, aby przechwycić i zapisać wszystkie trzy strumienie danych za pomocą wejścia LSL.

2.1 KROK 1 – Konfiguracja i instalacja

1. Do zbierania danych będą potrzebne obsługiwane urządzenia do akwizycji danych
   • Wszystkie urządzenia brainware Emotiv łączą się z LSL za pośrednictwem oprogramowania EmotivPRO

2. Zainstaluj EmotivPRO na swoim urządzeniu (urządzeniach). Do korzystania z LSL wymagana jest ważna licencja EmotivPRO.

3. Zainstaluj bibliotekę LSL dla języka Python za pomocą następującego polecenia:
   pip install pylsl

4. Pobierz oprogramowanie LabRecorder. Jest to prosta darmowa aplikacja, którą można uruchomić z
   wiersza poleceń lub za pomocą samodzielnego instalatora

5. Dla naszego eksperymentu: Zainstaluj niezbędne pakiety do odtwarzania dźwięku za pomocą języka Python
   pip install sounddevice soundfile

2.2 KROK 3 – Wysyłanie danych z EmotivPRO przez strumień LSL

1. Znajdź ikonę „…” w prawym górnym rogu aplikacji, przejdź do Settings (Ustawienia)

2. Znajdź sekcję „Lab Streaming Layer” i podsekcję „Outlet”

3. Wybierz wszystkie typy danych, które chcesz transmitować

4. Wybierz format danych (32-bit float lub 64-bit double)

5. Wybierz, czy wysyłać dane próbka po próbce, czy w paczkach próbek

6. Kliknij „Start”, aby rozpocząć transmisję strumienia danych LSL

2.3 KROK 4 – Użycie skryptu Python do odtwarzania dźwięku i wysyłania wyzwalaczy

1. Skopiuj i wklej poniższy blok kodu do pliku Python i zapisz go na swoim komputerze.

2. Zlokalizuj plik audio (najlepiej plik .wav), który chcesz odtworzyć, i edytuj skrypt, zmieniając
   zmienną audio_filepath na ścieżkę do pliku audio na swoim komputerze

3. Otwórz wiersz poleceń, aby wejść w interakcję z konsolą i przejdź do folderu, w którym
   zapisany jest twój plik Python

4. Wpisz: python3 filename.py
   • W zależności od instalacji Pythona, możesz użyć python zamiast python3
   
   Uwaga: Zastąp /path/to/audio.wav lokalizacją pliku audio, który chcesz odtworzyć podczas eksperymentu.

"""
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 KROK 5 – Użycie LabRecorder do przeglądania i zapisywania wszystkich strumieni LSL

1. Otwórz LabRecorder

2. Naciśnij Update. Dostępne strumienie LSL powinny być widoczne na liście strumieni
   • Powinieneś widzieć strumienie z obu aplikacji EmotivPRO (zwykle nazywane „Emotiv-
   DataStream”) oraz strumień znaczników (o nazwie „AudioMarkers”)

3. Kliknij Browse, aby wybrać lokalizację zapisu danych (i ustawić inne parametry)

4. Wybierz wszystkie strumienie i naciśnij Record, aby rozpocząć nagrywanie

3.0 Praca z danymi

LabRecorder wyjściowo generuje plik XDF (Extensible Data Format), który zawiera dane ze wszystkich strumieni.
Pliki XDF są podzielone na strumienie, a każdy z nich ma inny nagłówek opisujący jego zawartość
(nazwa urządzenia, typ danych, częstotliwość próbkowania, kanały i inne). Możesz użyć poniższego bloku kodu,
aby otworzyć plik XDF i wyświetlić podstawowe informacje.

Uwaga: Zastąp /path/to/your/file.xdf ścieżką do swojego pliku wyjściowego XDF z LabRecorder.

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 Dodatkowe zasoby

Oficjalna dokumentacja

1. Zapoznaj się z dokumentacją online, w tym z oficjalnym plikiem README w serwisie GitHub

2. Dodatkowe zasoby:
   • Kod do uruchamiania LSL z urządzeniami Emotiv wraz z przykładowymi skryptami
   • Przydatne demo LSL na YouTube
   • Repozytorium GitHub SCCN LSL dla wszystkich powiązanych bibliotek
   • Repozytorium GitHub LSL dla zbioru podmodułów i aplikacji

3. Potok analizy HyPyP dla badań hiperskanowania