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.