ברוכים הבאים! במדריך זה נלמד כיצד להשתמש ב-Lab Streaming Layer (LSL) בפייתון כדי לאסוף ולסנכרן נתוני EEG של Emotiv ממספר מכשירים. הדבר ידרוש ידע בסיסי מעשי בשפת התכנות פייתון.

מה שתלמדו

1. מה זה Lab Streaming Layer (LSL) ומדוע חוקרים משתמשים בו

2. כיצד לאסוף נתונים מסונכרנים ממספר מכשירי EEG של Emotiv

3. כיצד לייבא ולבחון נתונים שנאספו

1.1 מה זה LSL ולמה הוא טוב?

שכבת הזרמת מעבדה (LSL) היא ארגז כלים בקוד פתוח שניתן להשתמש בו כדי לשלוח, לקבל ולסנכרן זרמי נתונים עצביים, פיזיולוגיים והתנהגותיים מחומרת חיישנים מגוונת. מכשירי חומרת חישת מוח וגוף ניידים, מדויקים ובעלי יכולת הולכת וגוברת (כמו מערכות ה-EEG של Emotiv) מביאים את מדעי המוח אל מחוץ למעבדה אל עולם הנתונים בזמן אמת. במקום שבו מדידות מוח כמו EEG ו-MEG הוגבלו בעבר למעבדות מחקר, מכשירים ניידים מאפשרים לנו לאסוף נתונים מרובים בסביבות טבעיות יותר, וממספר אנשים בו-זמנית.

חוקר עשוי להתעניין בסינכרון פיזיולוגי בין שני אנשים המאזינים לאותה מוזיקה. LSL יכול לעזור לנו לאסוף נתונים משתי קסדות EEG בנפרד, שמסונכרנים גם הם להצגת הסאונד.

כמה דוגמאות לשימושים אחרים ב-LSL:

1. הוספת סמני אירועים מניסוי לנתוני EEG מתמשכים

2. יישור זמן של נתונים ממקורות מרובים עבור משתתף בודד (למשל דופק, EMG, EEG)

3. יישור זמן של נתונים ממספר משתתפים (למשל, מחקרי EEG Hyperscanning)

1.2 כיצד LSL עובד?

Lab Streaming Layer הוא פרוטוקול להחלפה בזמן אמת של נתוני סדרות עיתיות בין מספר מכשירים. ניתן ליישם את LSL באמצעות ספריות קוד פתוח עבור שפות תכנות כמו פייתון, MATLAB, C++, Java ואחרות.

הפונקציונליות המרכזית סובבת סביב זרמי נתונים של LSL:

1. מכשיר/תוכנת רכישה אוספים נתונים ויוצרים זרם נתונים - ניתן להזרים נתונים פיזיולוגיים ל-LSL ממכשירי הקלטת EEG, מעקבי עיניים, מערכות לכידת תנועה, מזהי דופק וכו', כולל מטא-נתונים (קצב דגימה, סוג נתונים, מידע על ערוצים וכו') - ניתן לשלוח סמני אירועים מניסויים (למשל באמצעות PsychoPy) גם כזרם נתונים באמצעות LSL

2. זרם הנתונים מפורסם לרשת - כך נשלחים נתונים באמצעות LSL; זרם הנתונים "משודר" לרשת - זרמים מפורסמים זמינים ברשת וניתנים לגילוי על ידי מכשירים תומכי LSL אחרים באותה רשת - LSL מקצה לכל מקטע נתונים או דגימה חותמת זמן המבוססת על שעון משותף (בעקבות פרוטוקול Network Time Protocol). - הזרם נדחף דגימה-אחר-דגימה (או מקטע-אחר-מקטע) דרך "מוצא" (outlet)

3. מכשירי איסוף "נרשמים" לזרמי הנתונים - כך מתקבלים נתונים באמצעות LSL - מכשירי איסוף באותה רשת מקבלים זרמי נתונים מפורסמים באמצעות "מבואות" (inlets). - כל מבוא מקבל את דגימות הזרם והמטא-נתונים ממוצא אחד בלבד

4. שמירת נתונים - עם ההרשמה לזרם נתונים, תוכלו לשמור אותו במשתנה בשפת התכנות המועדפת עליכם, או להשתמש בתוכנת LabRecorder המצורפת של LSL כדי לשמור אותו בפורמט סטנדרטי כגון .xdf.

2.0 סקירה כללית של המדריך

במדריך זה, ניקח דוגמה של מערך ניסיוני וננחה אתכם בשלבים ובקוד הדרושים ליישומו באמצעות LSL בפייתון. נשתמש בפייתון כדי להשמיע סאונד בזמן איסוף נתוני EEG משני אנשים המרכיבים קסדות של Emotiv. נשתמש בשני מחשבים שכל אחד מהם מריץ EmotivPRO כדי לאסוף את נתוני ה-EEG, ונשדר כל זרם דרך מוצא LSL נפרד. נשתמש בספריית פייתון כדי להפעיל קובץ שמע ובמקביל לשלוח טריגר בכל פעם שהקובץ מתחיל.

שלבים:

1. השתמשו ב-EmotivPRO כדי להזרים נתונים דרך מוצאי LSL הכוללים נתוני EEG (ו/או תנועה, איכות מגע, איכות אות וכו') 2. השמיעו רצועת שמע באמצעות סקריפט פייתון, ובמקביל שלחו טריגר דרך LSL אחר. השתמשו ב-LabRecorder כדי ללכוד ולשמור את כל שלושת זרמי הנתונים דרך מבוא LSL.

2.1 שלב 1 - הגדרה והתקנה

1. תזדקקו למכשירי איסוף נתונים נתמכים לצורך איסוף הנתונים
   • כל מכשירי ה-brainware של Emotiv מתחברים ל-LSL באמצעות תוכנת EmotivPRO

2. התקינו את EmotivPRO במכשירים שלכם. תזדקקו לרישיון EmotivPRO תקף כדי להשתמש ב-LSL.

3. התקינו את ספריית LSL לפייתון באמצעות הפקודה הבאה:
   pip install pylsl

4. הורידו את תוכנת LabRecorder. זוהי אפליקציה פשוטה וחינמית שניתן להריץ מתוך
   שורת הפקודה או באמצעות הורדה עצמאית

5. עבור הניסוי שלנו: התקינו את החבילות הדרושות להשמעת שמע באמצעות פייתון
   pip install sounddevice soundfile

2.2 שלב 3 - שלחו את הנתונים מ-EmotivPRO באמצעות זרם LSL

1. אתרו את ה-"..." בפינה הימנית העליונה של האפליקציה, וניווטו אל הגדרות (Settings)

2. מצאו את המקטע 'Lab Streaming Layer' ואת תת-המקטע 'Outlet'

3. בחרו את כל סוגי הנתונים שברצונכם לשדר

4. בחרו את פורמט הנתונים (32-bit float או 64-bit double)

5. בחרו אם לשלוח נתונים דגימה-אחר-דגימה או במקטעי דגימות (chunks)

6. לחצו על 'Start' כדי לשדר זרם נתונים של LSL

2.3 שלב 4 - השתמשו בסקריפט פייתון כדי להשמיע שמע ולשלוח טריגרים

1. העתיקו והדביקו את קטע הקוד הבא לקובץ פייתון ושמרו אותו במחשב שלכם.

2. אתרו קובץ שמע (רצוי קובץ .wav) שברצונכם להשמיע ועירכו את הסקריפט על ידי שינוי
   המשתנה audio_filepath לנתיב של קובץ השמע במחשב שלכם

3. פתחו את שורת הפקודה וניווטו לתיקייה שבה
   קובץ הפייתון שלכם שמור

4. הזינו: python3 filename.py
   • בהתאם להתקנת הפייתון שלכם, ייתכן שתשתמשו ב-python במקום ב-python3
   
   הערה: החליפו את /path/to/audio.wav במיקום של קובץ השמע שברצונכם להשמיע במהלך הניסוי שלכם.

"""
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 שלב 5 - השתמשו ב-LabRecorder כדי להציג ולשמור את כל זרמי ה-LSL

1. פתחו את LabRecorder

2. לחצו על Update. זרמי ה-LSL הזמינים צריכים להופיע ברשימת הזרמים
   • אתם אמורים להיות מסוגלים לראות זרמים משני מכשירי ה-EmotivPRO (בדרך כלל נקראים "Emotiv-DataStream") ואת זרם הסמנים (הנקרא "AudioMarkers")

3. לחצו על Browse כדי לבחור מיקום לשמירת הנתונים (ולקביעת פרמטרים אחרים)

4. בחרו את כל הזרמים ולחצו על Record כדי להתחיל בהקלטה

3.0 עבודה עם הנתונים

תוכנת LabRecorder מייצאת קובץ XDF (Extensible Data Format) המכיל נתונים מכל הזרמים. קובצי XDF מובנים בתוך זרמים, שלכל אחד מהם כותרת שונה המתארת את מה שהוא מכיל (שם המכשיר, סוג הנתונים, קצב הדגימה, ערוצים ועוד). תוכלו להשתמש בקטע הקוד שלהלן כדי לפתוח את קובץ ה-XDF שלכם ולהציג מידע בסיסי.

הערה: החליפו את /path/to/your/file.xdf בנתיב הקובץ של קובץ הפלט LabRecorder XDF שלכם.

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 משאבים נוספים

תיעוד רשמי

1. עיינו בתיעוד המקוון, כולל קובץ ה-README הרשמי ב-GitHub

2. משאבים נוספים:
   • קוד להרצת LSL באמצעות מכשירי Emotiv, עם סקריפטים לדוגמה
   • הדגמת LSL שימושית ב-YouTube
   • מאגר SCCN LSL ב-GitHub עבור כל הספריות הנלוות
   • מאגר LSL ב-GitHub עבור אוסף של תת-מודולים ואפליקציות

3. נתיב ניתוח HyPyP עבור מחקרי Hyperscanning