Bienvenue ! Dans ce tutoriel, nous allons apprendre à utiliser Lab Streaming Layer (LSL) en Python pour collecter et synchroniser les données EEG d'Emotiv provenant de plusieurs appareils. Cela nécessitera une connaissance pratique de base du langage de programmation Python.

Ce que vous allez apprendre

1. Qu'est-ce que Lab Streaming Layer (LSL) et pourquoi les chercheurs l'utilisent

2. Comment collecter des données synchronisées à partir de plusieurs appareils EEG Emotiv

3. Comment importer et inspecter les données collectées

1.1 Qu'est-ce que LSL et à quoi ça sert ?

Le Lab streaming layer (LSL) est une boîte à outils open source qui peut être utilisée pour envoyer, recevoir et synchroniser des flux de données neuronales, physiologiques et comportementales provenant de divers matériels de capteurs. Des appareils matériels de détection cérébrale et corporelle de plus en plus performants, précis et mobiles (comme les systèmes EEG Emotiv) propulsent les neurosciences hors du laboratoire pour les amener dans le monde des données en temps réel. Alors que les mesures cérébrales telles que l'EEG et la MEG étaient autrefois confinées aux laboratoires de recherche, les appareils mobiles nous permettent désormais de collecter de multiples données dans des environnements plus naturels et sur plusieurs personnes à la fois.

Un chercheur peut s'intéresser à la synchronie physiologique entre deux personnes écoutant la même musique. LSL peut nous aider à collecter séparément les données de deux casques EEG, tout en étant également synchronisées avec la présentation du son.

Quelques exemples d'autres utilisations de LSL :

1. Ajouter des marqueurs d'événements d'une expérience à des données EEG en cours

2. Aligner temporellement les données de sources multiples pour un seul participant (par exemple, fréquence cardiaque, EMG, EEG)

3. Aligner temporellement les données de plusieurs participants (par exemple, études d'hyperscan EEG)

1.2 Comment fonctionne LSL ?

Lab Streaming Layer est un protocole pour l'échange en temps réel de données de séries temporelles entre plusieurs appareils. LSL peut être mis en œuvre à l'aide de bibliothèques open source pour des langages de programmation tels que Python, MATLAB, C++, Java et d'autres.

La fonctionnalité principale s'articule autour des flux de données LSL :

1. Un appareil/logiciel d'acquisition collecte les données et crée un flux de données - Les données physiologiques peuvent être diffusées en continu vers LSL à partir d'appareils d'enregistrement EEG, d'oculomètres, de systèmes de capture de mouvement, de moniteurs de fréquence cardiaque, etc., y compris les métadonnées (taux d'échantillonnage, type de données, informations sur les canaux, etc.) - Les marqueurs d'événements issus d'expériences (par exemple, en utilisant PsychoPy) peuvent également être envoyés sous forme de flux de données à l'aide de LSL

2. Le flux de données est publié sur le réseau - C'est ainsi que les données sont envoyées à l'aide de LSL ; le flux de données est « diffusé » sur le réseau - Les flux publiés sont disponibles sur le réseau et peuvent être découverts par d'autres appareils compatibles LSL sur le même réseau - LSL attribue à chaque bloc de données ou échantillon un horodatage basé sur une horloge commune (suivant le protocole de temps réseau Network Time Protocol). - Le flux est poussé échantillon par échantillon (ou bloc par bloc) à travers une sortie appelée « outlet »

3. Les appareils de collecte s'« abonnent » aux flux de données - C'est ainsi que les données sont reçues à l'aide de LSL - Les appareils de collecte sur le même réseau reçoivent les flux de données publiés via des entrées appelées « inlets ». - Chaque « inlet » reçoit les échantillons de flux et les métadonnées d'une seule et unique sortie « outlet »

4. Sauvegarde des données - Après vous être abonné à un flux de données, vous pouvez le sauvegarder dans une variable dans votre langage de programmation préféré, ou utiliser le logiciel LabRecorder fourni par LSL pour le sauvegarder dans un format standard tel que .xdf.

2.0 Aperçu du tutoriel

Dans ce tutoriel, nous prendrons un exemple de configuration expérimentale et vous guiderons à travers les étapes et le code nécessaires pour la mettre en œuvre à l'aide de LSL en Python. Nous utiliserons Python pour jouer un son tout en collectant des données EEG de deux personnes portant des casques Emotiv. Nous utiliserons deux ordinateurs exécutant chacun EmotivPRO pour collecter les données EEG, et diffuserons chaque flux via une sortie LSL distincte. Nous utiliserons une bibliothèque Python pour lire un fichier audio et envoyer simultanément un déclencheur (trigger) à chaque démarrage du fichier.

ÉTAPES :

1. Utilisez EmotivPRO pour diffuser des données via des sorties LSL qui incluent les données EEG (et/ou le mouvement, la qualité du contact, la qualité du signal, etc.) 2. Jouez une piste audio à l'aide d'un script Python, et envoyez simultanément un déclencheur via une autre sortie LSL. Utilisez LabRecorder pour capturer et sauvegarder les trois flux de données via une entrée LSL.

2.1 ÉTAPE 1 - Configuration et installation

1. Vous aurez besoin d'une acquisition de données prise en charge pour collecter des données
   • Tous les appareils de détection cérébrale d'Emotiv se connectent à LSL via le logiciel EmotivPRO

2. Installez EmotivPRO sur votre ou vos appareils. Vous aurez besoin d'une licence EmotivPRO valide pour utiliser LSL.

3. Installez la bibliothèque Python LSL avec la commande suivante :
   pip install pylsl

4. Téléchargez le logiciel LabRecorder. C'est une application simple et gratuite qui peut être exécutée à partir de
   la ligne de commande ou via un téléchargement autonome

5. Pour notre expérience : Installez les packages nécessaires pour lire de l'audio à l'aide de Python
   pip install sounddevice soundfile

2.2 ÉTAPE 3 - Envoyer les données d'EmotivPRO via un flux LSL

1. Repérez les « ... » dans le coin supérieur droit de l'application, puis accédez à Settings (Paramètres)

2. Trouvez la section « Lab Streaming Layer » et la sous-section « Outlet »

3. Sélectionnez tous les types de données que vous souhaitez diffuser

4. Sélectionnez le format des données (32-bit float ou 64-bit double)

5. Choisissez d'envoyer les données échantillon par échantillon (sample-by-sample) ou par blocs d'échantillons (chunks)

6. Cliquez sur « Start » pour diffuser un flux de données LSL

2.3 ÉTAPE 4 - Utiliser un script Python pour lire l'audio et envoyer des déclencheurs

1. Copiez et collez le bloc de code suivant dans un fichier Python et enregistrez-le sur votre ordinateur.

2. Localisez un fichier audio (idéalement un fichier .wav) que vous aimeriez lire et modifiez le script en changeant la
   variable audio_filepath par le chemin d'accès à votre fichier audio sur votre ordinateur

3. Ouvrez une invite de commande pour interagir avec la ligne de commande et accédez au dossier où
   votre fichier Python est stocké

4. Saisissez : python3 nom_du_fichier.py
   • Selon votre installation de Python, vous pouvez utiliser python au lieu de python3
   
   Note : Remplacez /path/to/audio.wav par l'emplacement du fichier audio que vous souhaitez lire pendant votre expérience.

"""
Exemple LSL : Lire de l'audio et envoyer un marqueur de déclenchement

Ce script crée un flux de marqueurs LSL, attend que l'utilisateur
appuie sur ENTRÉE, puis lit un fichier audio et envoie un marqueur qui
peut être synchronisé avec les données EEG collectées via LabRecorder.
"""

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


def wait_for_keypress():
    print("Appuyez sur ENTRÉE pour démarrer la lecture audio et envoyer un marqueur LSL.")
    while True:
        if input() == "":
            break


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

    print("Lecture de l'audio et envoi du marqueur LSL...")

    marker_val = [1]
    outlet.push_sample(marker_val)

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

    print("Lecture audio terminée.")


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
        )

"""
Exemple LSL : Lire de l'audio et envoyer un marqueur de déclenchement

Ce script crée un flux de marqueurs LSL, attend que l'utilisateur
appuie sur ENTRÉE, puis lit un fichier audio et envoie un marqueur qui
peut être synchronisé avec les données EEG collectées via LabRecorder.
"""

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


def wait_for_keypress():
    print("Appuyez sur ENTRÉE pour démarrer la lecture audio et envoyer un marqueur LSL.")
    while True:
        if input() == "":
            break


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

    print("Lecture de l'audio et envoi du marqueur LSL...")

    marker_val = [1]
    outlet.push_sample(marker_val)

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

    print("Lecture audio terminée.")


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
        )

"""
Exemple LSL : Lire de l'audio et envoyer un marqueur de déclenchement

Ce script crée un flux de marqueurs LSL, attend que l'utilisateur
appuie sur ENTRÉE, puis lit un fichier audio et envoie un marqueur qui
peut être synchronisé avec les données EEG collectées via LabRecorder.
"""

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


def wait_for_keypress():
    print("Appuyez sur ENTRÉE pour démarrer la lecture audio et envoyer un marqueur LSL.")
    while True:
        if input() == "":
            break


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

    print("Lecture de l'audio et envoi du marqueur LSL...")

    marker_val = [1]
    outlet.push_sample(marker_val)

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

    print("Lecture audio terminée.")


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 ÉTAPE 5 - Utiliser LabRecorder pour visualiser et sauvegarder tous les flux LSL

1. Ouvrez LabRecorder

2. Appuyez sur Update. Les flux LSL disponibles doivent être visibles dans la liste des flux
   • Vous devriez être en mesure de voir les flux provenant des deux logiciels EmotivPRO (généralement appelés "Emotiv-
   DataStream") et le flux de marqueurs (appelé "AudioMarkers")

3. Cliquez sur Browse pour sélectionner un emplacement pour stocker les données (et régler d'autres paramètres)

4. Sélectionnez tous les flux et appuyez sur Record pour démarrer l'enregistrement

3.0 Travailler avec les données

LabRecorder génère un fichier XDF (Extensible Data Format) qui contient les données de tous les flux. Les fichiers XDF sont structurés en flux, chacun ayant un en-tête différent qui décrit ce qu'il contient (nom de l'appareil, type de données, taux d'échantillonnage, canaux, et plus encore). Vous pouvez utiliser le bloc de code ci-dessous pour ouvrir votre fichier XDF et afficher quelques informations de base.

Note : Remplacez /path/to/your/file.xdf par le chemin d'accès de votre fichier de sortie LabRecorder XDF.

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

# Indiquez ici le chemin de votre fichier de sortie LSL.
data_path = "/chemin/vers/votre/fichier.xdf"

# Chargez le fichier XDF.
streams, fileheader = pyxdf.load_xdf(data_path)

print("En-tête de fichier XDF :", fileheader)
print("Nombre de flux trouvés :", len(streams))

for i, stream in enumerate(streams):
    print("\nFlux", i + 1)
    print("Nom du flux :", stream["info"]["name"][0])
    print("Type de flux :", stream["info"]["type"][0])
    print("Nombre de canaux :", stream["info"]["channel_count"][0])

    sfreq = float(stream["info"]["nominal_srate"][0])
    print("Taux d'échantillonnage :", sfreq)

    print("Nombre d'échantillons :", len(stream["time_series"]))
    print("5 premiers points de données :", stream["time_series"][:5])

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

    print("Noms des canaux :", channel_names)

    channel_types = "eeg"

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

# Indiquez ici le chemin de votre fichier de sortie LSL.
data_path = "/chemin/vers/votre/fichier.xdf"

# Chargez le fichier XDF.
streams, fileheader = pyxdf.load_xdf(data_path)

print("En-tête de fichier XDF :", fileheader)
print("Nombre de flux trouvés :", len(streams))

for i, stream in enumerate(streams):
    print("\nFlux", i + 1)
    print("Nom du flux :", stream["info"]["name"][0])
    print("Type de flux :", stream["info"]["type"][0])
    print("Nombre de canaux :", stream["info"]["channel_count"][0])

    sfreq = float(stream["info"]["nominal_srate"][0])
    print("Taux d'échantillonnage :", sfreq)

    print("Nombre d'échantillons :", len(stream["time_series"]))
    print("5 premiers points de données :", stream["time_series"][:5])

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

    print("Noms des canaux :", channel_names)

    channel_types = "eeg"

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

# Indiquez ici le chemin de votre fichier de sortie LSL.
data_path = "/chemin/vers/votre/fichier.xdf"

# Chargez le fichier XDF.
streams, fileheader = pyxdf.load_xdf(data_path)

print("En-tête de fichier XDF :", fileheader)
print("Nombre de flux trouvés :", len(streams))

for i, stream in enumerate(streams):
    print("\nFlux", i + 1)
    print("Nom du flux :", stream["info"]["name"][0])
    print("Type de flux :", stream["info"]["type"][0])
    print("Nombre de canaux :", stream["info"]["channel_count"][0])

    sfreq = float(stream["info"]["nominal_srate"][0])
    print("Taux d'échantillonnage :", sfreq)

    print("Nombre d'échantillons :", len(stream["time_series"]))
    print("5 premiers points de données :", stream["time_series"][:5])

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

    print("Noms des canaux :", channel_names)

    channel_types = "eeg"

4.0 Ressources supplémentaires

Documentation officielle

1. Consultez la documentation en ligne, y compris le fichier README officiel sur GitHub

2. Ressources supplémentaires :
   • Code pour exécuter LSL en utilisant les appareils Emotiv, avec des exemples de scripts
   • Démo LSL utile sur YouTube
   • Dépôt GitHub SCCN LSL pour toutes les bibliothèques associées
   • Dépôt GitHub LSL pour une collection de sous-modules et d'applications

3. Pipeline d'analyse HyPyP pour les études d'hyperscan