Witaj! W tym samouczku dowiemy się, jak używać Lab Streaming Layer (LSL) w języku Python do zbierania i synchronizowania danych EEG Emotiv z wielu urządzeń. Będzie to wymagało podstawowej wiedzy praktycznej 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 przesyłania, odbierania i synchronizowania strumieni danych neuronowych, fizjologicznych i behawioralnych z różnych urządzeń sensorycznych. Coraz bardziej wydajne, precyzyjne i mobilne urządzenia do pomiaru aktywności mózgu i ciała (takie jak systemy EEG Emotiv) wyprowadzają neuronaukę poza laboratorium, w świat 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 synchronizacją fizjologiczną między dwiema osobami słuchającymi tej samej muzyki. LSL może pomóc nam zbierać dane z dwóch zestawów słuchawkowych EEG osobno, które są również zsynchronizowane z prezentacją dźwięku.

Oto kilka przykładów innych zastosowań LSL:

1. Dodawanie znaczników zdarzeń z eksperymentu do trwającego badania EEG

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

3. Wyrównywanie czasowe danych od wielu uczestników (np. badania hiperskanningowe EEG)

1.2 Jak działa LSL?

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

Główna funkcjonalność opiera się na strumieniach danych LSL:

1. Urządzenie/oprogramowanie akwizycyjne zbiera dane i tworzy strumień danych - Dane fizjologiczne mogą być przesyłane strumieniowo do LSL z urządzeń rejestrujących EEG, trackerów wzroku, systemów przechwytywania ruchu, monitorów tętna itp., w tym metadane (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ą przesyłane przy użyciu 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żdemu blokowi 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 blok po bloku) przez ujście (outlet)

3. Urządzenie(a) zbierające „subskrybują” strumień(ie) danych - W ten sposób dane są odbierane przy użyciu 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 dokonaniu subskrypcji strumienia danych możesz zapisać go do zmiennej w preferowanym języku programowania lub użyć dostarczonego oprogramowania LabRecorder firmy LSL, aby zapisać go w standardowym formacie, takim 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 ma uruchomiony 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 za każdym razem, gdy plik się rozpoczyna.

KROKI:

1. Użyj EmotivPRO do przesyłania strumieniowego danych przez ujścia LSL, które obejmują dane EEG (i/lub ruch, jakość kontaktu, jakość sygnału itp.) 2. Otwórz ścieżkę dźwiękową za pomocą skryptu Python i jednocześnie prześlij wyzwalacz przez inny LSL. Użyj LabRecorder do przechwytywania i zapisywania wszystkich trzech strumieni danych przez wejście LSL.

2.1 KROK 1 - Konfiguracja i instalacja

1. Będziesz potrzebować obsługiwanych urządzeń do akwizycji danych do zbierania danych
   • Wszystkie urządzenia brainware Emotiv łączą się z LSL za pomocą oprogramowania EmotivPRO

2. Zainstaluj EmotivPRO na swoim urządzeniu (urządzeniach). Do korzystania z LSL potrzebna będzie ważna licencja EmotivPRO.

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

4. Pobierz oprogramowanie LabRecorder. Jest to prosta, bezpłatna aplikacja, którą można uruchomić z
   wiersza poleceń lub pobrać jako samodzielny program

5. Dla naszego eksperymentu: Zainstaluj niezbędne pakiety do odtwarzania dźwięku za pomocą Pythona
   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-bitowy float lub 64-bitowy double)

5. Wybierz, czy wysyłać dane próbka po próbce, czy w blokach 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. Znajdź 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 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 odtwarzać podczas eksperymentu.

"""
Przykłąd LSL: Odtwarzanie dźwięku i wysyłanie znacznika wyzwalacza

Ten skrypt tworzy strumień znaczników LSL, czeka na naciśnięcie klawisza ENTER przez użytkownika,
a następnie odtwarza plik audio i wysyła znacznik, który
może być zsynchronizowany z danymi EEG zebranymi za pomocą programu LabRecorder.
"""

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


def wait_for_keypress():
    print("Naciśnij ENTER, aby rozpocząć odtwarzanie dźwięku i wysłać znacznik LSL.")
    while True:
        if input() == "":
            break


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

    print("Odtwarzanie dźwięku i wysyłanie znacznika LSL...")

    marker_val = [1]
    outlet.push_sample(marker_val)

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

    print("Zakończono odtwarzanie dźwięku.")


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
        )

"""
Przykłąd LSL: Odtwarzanie dźwięku i wysyłanie znacznika wyzwalacza

Ten skrypt tworzy strumień znaczników LSL, czeka na naciśnięcie klawisza ENTER przez użytkownika,
a następnie odtwarza plik audio i wysyła znacznik, który
może być zsynchronizowany z danymi EEG zebranymi za pomocą programu LabRecorder.
"""

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


def wait_for_keypress():
    print("Naciśnij ENTER, aby rozpocząć odtwarzanie dźwięku i wysłać znacznik LSL.")
    while True:
        if input() == "":
            break


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

    print("Odtwarzanie dźwięku i wysyłanie znacznika LSL...")

    marker_val = [1]
    outlet.push_sample(marker_val)

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

    print("Zakończono odtwarzanie dźwięku.")


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
        )

"""
Przykłąd LSL: Odtwarzanie dźwięku i wysyłanie znacznika wyzwalacza

Ten skrypt tworzy strumień znaczników LSL, czeka na naciśnięcie klawisza ENTER przez użytkownika,
a następnie odtwarza plik audio i wysyła znacznik, który
może być zsynchronizowany z danymi EEG zebranymi za pomocą programu LabRecorder.
"""

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


def wait_for_keypress():
    print("Naciśnij ENTER, aby rozpocząć odtwarzanie dźwięku i wysłać znacznik LSL.")
    while True:
        if input() == "":
            break


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

    print("Odtwarzanie dźwięku i wysyłanie znacznika LSL...")

    marker_val = [1]
    outlet.push_sample(marker_val)

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

    print("Zakończono odtwarzanie dźwięku.")


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 programu 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 programów EmotivPRO (zwykle nazywane „Emotiv-
   DataStream”) oraz strumień znaczników (nazwany „AudioMarkers”)

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

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

3.0 Praca z danymi

LabRecorder generuje plik XDF (Extensible Data Format), który zawiera dane ze wszystkich strumieni. Pliki XDF są podzielone na strumienie, z których każdy 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 wyjściowego pliku XDF z programu LabRecorder.

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

# Tutaj podaj ścieżkę do swojego pliku wyjściowego LSL.
data_path = "/path/to/your/file.xdf"

# Wczytaj plik XDF.
streams, fileheader = pyxdf.load_xdf(data_path)

print("Nagłówek pliku XDF:", fileheader)
print("Liczba znalezionych strumieni:", len(streams))

for i, stream in enumerate(streams):
    print("\nStrumień", i + 1)
    print("Nazwa strumienia:", stream["info"]["name"][0])
    print("Typ strumienia:", stream["info"]["type"][0])
    print("Liczba kanałów:", stream["info"]["channel_count"][0])

    sfreq = float(stream["info"]["nominal_srate"][0])
    print("Częstotliwość próbkowania:", sfreq)

    print("Liczba próbek:", len(stream["time_series"]))
    print("Pierwsze 5 punktów danych:", stream["time_series"][:5])

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

    print("Nazwy kanałów:", channel_names)

    channel_types = "eeg"

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

# Tutaj podaj ścieżkę do swojego pliku wyjściowego LSL.
data_path = "/path/to/your/file.xdf"

# Wczytaj plik XDF.
streams, fileheader = pyxdf.load_xdf(data_path)

print("Nagłówek pliku XDF:", fileheader)
print("Liczba znalezionych strumieni:", len(streams))

for i, stream in enumerate(streams):
    print("\nStrumień", i + 1)
    print("Nazwa strumienia:", stream["info"]["name"][0])
    print("Typ strumienia:", stream["info"]["type"][0])
    print("Liczba kanałów:", stream["info"]["channel_count"][0])

    sfreq = float(stream["info"]["nominal_srate"][0])
    print("Częstotliwość próbkowania:", sfreq)

    print("Liczba próbek:", len(stream["time_series"]))
    print("Pierwsze 5 punktów danych:", stream["time_series"][:5])

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

    print("Nazwy kanałów:", channel_names)

    channel_types = "eeg"

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

# Tutaj podaj ścieżkę do swojego pliku wyjściowego LSL.
data_path = "/path/to/your/file.xdf"

# Wczytaj plik XDF.
streams, fileheader = pyxdf.load_xdf(data_path)

print("Nagłówek pliku XDF:", fileheader)
print("Liczba znalezionych strumieni:", len(streams))

for i, stream in enumerate(streams):
    print("\nStrumień", i + 1)
    print("Nazwa strumienia:", stream["info"]["name"][0])
    print("Typ strumienia:", stream["info"]["type"][0])
    print("Liczba kanałów:", stream["info"]["channel_count"][0])

    sfreq = float(stream["info"]["nominal_srate"][0])
    print("Częstotliwość próbkowania:", sfreq)

    print("Liczba próbek:", len(stream["time_series"]))
    print("Pierwsze 5 punktów danych:", stream["time_series"][:5])

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

    print("Nazwy kanałów:", channel_names)

    channel_types = "eeg"

4.0 Dodatkowe zasoby

Oficjalna dokumentacja

1. Zapoznaj się z dokumentacją online, w tym z oficjalnym plikiem README na GitHubie

2. Dodatkowe zasoby:
   • Kod do uruchomienia LSL przy użyciu urządzeń Emotiv, wraz z przykładowymi skryptami
   • Przydatne demo LSL na YouTube
   • Repozytorium GitHub SCCN LSL dla wszystkich powiązanych bibliotek
   • Repozytorium GitHub LSL dla kolekcji podmodułów i aplikacji

3. Potok analizy HyPyP dla badań hiperskanningowych