Hoş geldiniz! Bu eğitimde, birden fazla cihazdan Emotiv EEG verilerini toplamak ve senkronize etmek için Python'da Lab Streaming Layer (LSL) protokolünü nasıl kullanacağımızı öğreneceğiz. Python programlama dili hakkında temel düzeyde çalışma bilgisi gerektirecektir.

Neler Öğreneceksiniz?

1. Lab Streaming Layer (LSL) nedir ve araştırmacılar bunu neden kullanır?

2. Birden fazla Emotiv EEG cihazından senkronize veri nasıl toplanır?

3. Toplanan veriler nasıl dışa aktarılır ve incelenir?

1.1 LSL Nedir ve Ne İşe Yarar?

Lab streaming layer (LSL), farklı sensör donanımlarından gelen nöral, fizyolojik ve davranışsal veri akışlarını göndermek, almak ve senkronize etmek için kullanılabilen açık kaynaklı bir araç kutusudur. Giderek daha yetenekli, hassas ve mobil beyin ve vücut algılama donanım cihazları (Emotiv EEG sistemleri gibi), nörobilimi laboratuvarın dışına, gerçek zamanlı veri dünyasına taşımaktadır. EEG ve MEG gibi beyin ölçümlerinin bir zamanlar yalnızca araştırma laboratuvarlarıyla sınırlı kaldığı yerlerde, mobil cihazlar daha doğal ortamlardan ve aynı anda birden fazla kişiden birden çok veri toplamamıza olanak tanır.

Bir araştırmacı, aynı müziği dinleyen iki kişi arasındaki fizyolojik senkronizasyonla ilgilenebilir. LSL, iki EEG başlığından ayrı ayrı veri toplamamıza ve bu verilerin aynı zamanda ses sunumuyla senkronize edilmesine yardımcı olabilir.

LSL'nin diğer kullanım alanlarına bazı örnekler:

1. Bir deneyden devam eden bir EEG verisine olay işaretleyicileri eklemek

2. Tek bir katılımcı için birden fazla kaynaktan gelen verileri zaman hizalaması yapmak (örn. kalp atış hızı, EMG, EEG)

3. Birden çok katılımcıdan gelen verileri zaman hizalaması yapmak (örn. EEG Hiperskanlama Çalışmaları)

1.2 LSL Nasıl Çalışır?

Lab Streaming Layer, birden fazla cihaz arasında zaman serisi verilerinin gerçek zamanlı olarak değişimi için kullanılan bir protokoldür. LSL; Python, MATLAB, C++, Java ve diğer programlama dilleri için açık kaynaklı kütüphaneler kullanılarak uygulanabilir.

Çekirdek işlevsellik LSL veri akışları (data streams) etrafında döner:

1. Bir edinim cihazı/yazılımı veri toplar ve bir veri akışı oluşturur - Fizyolojik veriler, EEG kayıt cihazlarından, göz takip cihazlarından, hareket yakalama sistemlerinden, kalp atış hızı monitörlerinden vb. meta veriler dahil olmak üzere (örnekleme hızı, veri türü, kanal bilgisi vb.) LSL'ye aktarılabilir - Deneylerden gelen olay işaretleyicileri de (örn. PsychoPy kullanılarak) LSL kullanılarak bir veri akışı olarak gönderilebilir

2. Veri akışı ağda yayınlanır (published) - LSL kullanılarak veri bu şekilde gönderilir; veri akışı ağa "yayınlanır" - Yayınlanan akışlar ağda mevcuttur ve aynı ağdaki diğer LSL destekli cihazlar tarafından keşfedilebilir - LSL, ortak bir saate dayalı olarak (Ağ Zaman Protokolünü takiben) her bir veri parçasına veya örneğine bir zaman damgası atar. - Akış, bir "çıkış kanalı" (outlet) aracılığıyla örnek örnek (veya parça parça) iletilir

3. Toplama cihazı/cihazları veri akışına/akışlarına "abone olur" (subscribe) - LSL kullanılarak veri bu şekilde alınır - Aynı ağdaki toplama cihazları, yayınlanan veri akışlarını "giriş kanalları" (inlets) aracılığıyla alır. - Her bir giriş kanalı, yalnızca bir çıkış kanalından gelen akış örneklerini ve meta verileri alır

4. Veriyi kaydetme - Bir veri akışına abone olduktan sonra, bunu tercih ettiğiniz programlama dilinde bir değişkene kaydedebilir veya .xdf gibi standart bir formatta kaydetmek için LSL'nin sağladığı LabRecorder yazılımını kullanabilirsiniz.

2.0 Eğitime genel bakış

Bu eğitimde, örnek bir deneysel kurulumu ele alacağız ve Python'da LSL kullanarak bunu uygulamak için gerekli adımlar ve kodlar konusunda size rehberlik edeceğiz. Emotiv başlığı takan iki kişiden EEG verisi toplarken ses çalmak için Python kullanacağız. EEG verilerini toplamak ve her bir akışı ayrı bir LSL çıkış kanalı üzerinden yayınlamak için her biri EmotivPRO çalıştıran iki bilgisayar kullanacağız. Bir ses dosyasını oynatmak ve aynı anda dosya her başladığında bir tetikleyici göndermek için bir Python kütüphanesi kullanacağız.

ADIMLAR:

1. EEG verilerini (ve/veya hareket, temas kalitesi, sinyal kalitesi vb.) içeren LSL çıkışları aracılığıyla veri akışı sağlamak için EmotivPRO'yu kullanın. 2. Python betiği kullanarak bir ses parçası çalın ve aynı anda başka bir LSL aracılığıyla bir tetikleyici gönderin. Üç veri akışının tümünü bir LSL giriş kanalı aracılığıyla yakalamak ve kaydetmek için LabRecorder kullanın.

2.1 ADIM 1 - Kurulum ve yükleme

1. Veri toplamak için desteklenen veri toplama cihazlarına ihtiyacınız olacak
   • Emotiv'in tüm beyin donanımı cihazları EmotivPRO yazılımı aracılığıyla LSL'ye bağlanır

2. Cihaz(lar)ınıza EmotivPRO'yu yükleyin. LSL'yi kullanmak için geçerli bir EmotivPRO lisansına ihtiyacınız olacaktır.

3. Aşağıdaki komutla Python LSL kütüphanesini yükleyin:
   pip install pylsl

4. LabRecorder yazılımını indirin. Bu, komut satırından veya bağımsız bir indirme olarak çalıştırılabilen basit ve ücretsiz bir uygulamadır

5. Deneyimiz için: Python kullanarak ses çalmak için gerekli paketleri yükleyin
   pip install sounddevice soundfile

2.2 ADIM 3 - Verileri EmotivPRO'dan bir LSL akışı aracılığıyla gönderme

1. Uygulamanın sağ üst köşesindeki “…” simgesini bulun, Ayarlar'a (Settings) gidin

2. 'Lab Streaming Layer' bölümünü ve 'Outlet' (Çıkış Kanalı) alt bölümünü bulun

3. Yayınlamak istediğiniz tüm veri türlerini seçin

4. Veri formatını seçin (32-bit float veya 64-bit double)

5. Verilerin örnek örnek mi yoksa örnek blokları halinde mi gönderileceğini seçin

6. Bir LSL veri akışı yayınlamak için 'Start' (Başlat) seçeneğine tıklayın

2.3 ADIM 4 - Ses çalmak ve tetikleyiciler göndermek için Python betiği kullanma

1. Aşağıdaki kod bloğunu kopyalayıp bir python dosyasına yapıştırın ve bilgisayarınıza kaydedin.

2. Çalmak istediğiniz bir ses dosyasını (tercihen bir .wav dosyası) bulun ve audio_filepath değişkenini bilgisayarınızdaki ses dosyasının yoluna değiştirerek betiği düzenleyin

3. Komut satırıyla etkileşime girmek için bir komut istemi açın ve Python dosyanızın saklandığı klasöre gidin

4. Şunu yazın: python3 filename.py
   • Python kurulumunuza bağlı olarak, python3 yerine python kullanabilirsiniz
   
   Not: /path/to/audio.wav kısmını, deneyiniz sırasında çalmak istediğiniz ses dosyasının konumuyla değiştirin.

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