Witaj! W tym samouczku dowiemy się, jak używać Lab Streaming Layer (LSL) w języku Python do zbierania i synchronizowania danych EEG z urządzeń Emotiv. 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 badacze z niego korzystają

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 biblioteka o otwartym kodzie źródłowym (open-source), która umożliwia przesyłanie, odbieranie i synchronizację strumieni danych neuronalnych, fizjologicznych i behawioralnych z różnych urządzeń czujnikowych. Coraz bardziej zaawansowane, precyzyjne i mobilne urządzenia do pomiaru aktywności mózgu i ciała (takie jak systemy EEG Emotiv) wyprowadzają neuronaukę poza laboratoria w świat danych w czasie rzeczywistym. Podczas gdy pomiary mózgu, takie jak EEG i MEG, były kiedyś ograniczone do laboratoriów badawczych, urządzenia mobilne pozwalają nam zbierać wiele danych w bardziej naturalnych środowiskach i od wielu osób jednocześnie.

Badacza może interesować synchronizacja fizjologiczna 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ą dodatkowo 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 hiperskanowania 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 zaimplementować przy użyciu 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 lub oprogramowanie akwizycyjne zbiera dane i tworzy strumień danych - dane fizjologiczne mogą być przesyłane strumieniowo do LSL z urządzeń rejestrujących EEG, eye-trackerów, 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żdemu pakietowi danych lub próbce znacznik czasu na podstawie wspólnego zegara (zgodnie z protokołem Network Time Protocol) - strumień jest przesyłany próbka po próbce (lub pakiet po pakiecie) przez „wyjście” (outlet)

3. Urządzenia zbierające „subskrybują” strumienie danych - w ten sposób dane są odbierane za pomocą LSL - urządzenia zbierające w tej samej sieci odbierają opublikowane strumienie danych przez „wejścia” (inlets) - każde wejście odbiera próbki strumienia i metadane tylko z jednego wyjścia

4. Zapisywanie danych - po zasubskrybowaniu strumienia danych można zapisać go do zmiennej w preferowanym języku programowania lub użyć dostarczonego oprogramowania LabRecorder do zapisania 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 języka Python 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 w celu zbierania danych EEG, i prześlemy każdy strumień przez oddzielne wyjście LSL. Użyjemy biblioteki Pythona do odtworzenia pliku audio i jednoczesnego wysłania triggera za każdym razem, gdy plik się rozpocznie.

KROKI:

1. Użyj EmotivPRO do przesyłania danych przez wyjś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 trigger przez inne LSL. Użyj LabRecorder, aby przechwycić i zapisać wszystkie trzy strumienie danych przez wejście LSL.

2.1 KROK 1 - Konfiguracja i instalacja

1. Do zbierania danych potrzebne będą 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 swoich 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, bezpłatna aplikacja, którą można uruchomić z poziomu
   wiersza poleceń lub jako samodzielny program do pobrania

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 za pośrednictwem strumienia 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 pakietach próbek

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

2.3 KROK 4 - Użycie skryptu Python do odtwarzania dźwięku i wysyłania triggerów

1. Skopiuj i wklej następujący blok kodu do pliku python i zapisz go na swoim komputerze.

2. Znajdź plik audio (najlepiej plik .wav), który chcesz odtworzyć, i zmodyfikuj 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 linią komend i przejdź do folderu, w którym
   zapisany jest Twój plik Pythona

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