PsychoPy

This guide details how to synchronise your Mentalab Explore device with PsychoPy experiments, focusing on high-precision synchronization of event markers using LabStreamingLayer (LSL) in combination with Mentalab Hypersync. This is the recommended approach for robust and accurate data alignment.

Legacy wired trigger methods are listed at the bottom.

Prerequisites

Before starting, ensure you have the following hardware and software:

Hardware

Mentalab Explore Pro Device: An Explore Pro biosignal acquisition system.
Mentalab Hypersync Add-on: This hardware is essential for accurately synchronizing LSL markers from PsychoPy with the Explore device’s data stream.
Computer: To run PsychoPy, LSL, and data recording software.

Software

PsychoPy: A recent version of PsychoPy.
Python: PsychoPy’s scripting language.
PyLSL (pylsl): The Python library for LabStreamingLayer. Install via pip:
```
pip install pylsl
```

Recommended Method: Synchronization via PyLSL and Mentalab Hypersync

This method uses LSL to transmit event markers from your PsychoPy experiment. This guide contains instruction for sending LSL markers from your PsychoPy experiment. For all following steps, please refer to the Hypersync instructions delivered to you with your Hypersync hardware.

How it Works

PsychoPy Experiment: Your PsychoPy script generates experimental events (e.g., stimulus onset, response).
PyLSL Markers: At each event, Python sends an event marker via an LSL stream.
Mentalab Hypersync: The Mentalab Hypersync suite is used to merge ExG data with the event markers via LSL. Please follow the instructions delivered to you with your Hypersync hardware.

Integrating LSL Markers into your PsychoPy Experiment

Add Python code to your PsychoPy script to establish an LSL outlet and dispatch markers. We are happy to provide an example P300 experiment as reference.

Key Python Code Snippets for LSL

Import necessary pylsl classes:

from pylsl import StreamInfo, StreamOutlet

Define Stream Information (StreamInfo): This object describes your marker stream so Hypersync can find it.

# Define the stream information for markers
marker_stream_info = StreamInfo(name='PsychopyExperimentMarkers', 
                                type='Markers', 
                                channel_count=1,
                                nominal_srate=0.0, 
                                channel_format='int32',
                                source_id='YourExperimentUniqueID') #
# name: A recognizable name (e.g., 'PsychopyExperimentMarkers')
# type: Conventionally 'Markers'
# channel_count: 1 for single integer markers
# nominal_srate: 0.0 for irregular events
# channel_format: 'int32' for integer markers
# source_id: A unique ID for this stream source

Create an LSL Outlet (StreamOutlet): This object sends markers into the LSL network.

# Create the LSL outlet
marker_outlet = StreamOutlet(marker_stream_info) #
print("LSL Marker Outlet created. Stream Name: PsychopyExperimentMarkers") #

Pushing a Marker (marker_outlet.push_sample()): Send a marker when an event occurs. The argument must be a list or tuple.
```
# Example: Sending marker for stimulus onset
label_value = 11 # Example: 11 for a target stimulus
marker_outlet.push_sample([label_value]) # Send LSL marker for stimulus onset
print(f"LSL Marker Sent: {label_value}") #
```
It’s critical to send the marker as close as possible to the event’s actual occurrence (e.g., immediately after win.flip() for visual stimuli).

These steps will create an LSL Marker stream, that can be recorded using LabRecorder. To ensure accurate synchronisation, you must use Mentalab Hypersync and follow the instructions provided alongside your Hypersync hardware.

Alternative (Legacy) Methods: Wired Triggers

While LSL with Hypersync is preferred as it enables fully wireless and highly accurate event marking, direct wired connections are also possible. Please refer to our Event Triggers page for further information.

Stimulation

Analysis