Skip to content

PsychoPy Builder Tutorial

Getting started

This section demonstrates the purpose of the psychopy-bids plugin in Builder.

The goal is to log participant-relevant experiment events into BIDS-compatible event tables.

In a minimal PsychoPy example, a fixed text is presented to the participant. The flow includes a text routine and one BIDS export routine.

Example Experiment

You can link another component to automatically capture onset, duration, response time, and event type attributes. If custom values are needed, you can enable Manually set values and override selected fields.

Please note: if Response Time is enabled for a component that does not expose .rt, a runtime warning is shown.

Event Properties

The onset is the moment the component appears on screen. Duration is computed from component stop minus component start (or routine stop fallback where relevant).

Event Properties

To include richer metadata, add custom columns under the More tab using dictionary syntax.

Event Properties

The final events table contains one row per event.

Linked Components

Using linked components allows dynamic capture of key runtime properties.

  1. Enter a valid component name in Link Component.
  2. Select the linked attributes you want in the exported table.
How linked values are derived Note: this is primarily for understanding and manual override scenarios. 
onset = {linked_component_name}.tStartRefresh
If `.tStopRefresh` exists: 
duration = {linked_component_name}.tStopRefresh - {linked_component_name}.tStartRefresh
If `.tStopRefresh` does not exist: 
duration = thisExp.thisEntry['{routine_name}.stopped'] - {linked_component_name}.tStartRefresh

response_time = {linked_component_name}.rt

event_type = type({linked_component_name}).__name__

Configuring BIDS Export

Add one BIDS Export routine near the end of the experiment flow.

In this routine, define:

  • dataset name
  • data type (beh, func, eeg, ieeg, meg, nirs, motion, mrs, pet)
  • optional session and acquisition labels
  • run behavior (True, False, or fixed string label)
  • optional sidecar, HED generation, stimuli, code, and environment export

Run behavior

  • runs=True: auto-incremented labels (run-001, run-002, ...)
  • runs=False: no run entity
  • runs="4a": fixed run label

Session behavior

If the routine session field is empty, the export falls back to expInfo['session'].

Optional Onset Synchronization

Use BidsOnsetRoutine when timing must be synchronized to an external trigger.

Recommended placement: before the first routine that emits BIDS events.

Expected output

After a successful run, expect:

  • dataset-level metadata at root (dataset_description.json, participants.tsv, README, CHANGES, LICENSE)
  • event files under sub-<label>/[ses-<label>/]<data_type>/
  • optional sidecar file(s)
  • optional stimuli/ and code/ folders

Validate output quickly

  1. Open generated .tsv files and verify column consistency.
  2. Confirm onset and duration values match experiment timing.
  3. Check sidecar descriptions for custom columns.
  4. Run a BIDS validator before sharing data.

Common pitfalls

  • Response Time requires a linked component with .rt.
  • Invalid custom-column dictionary syntax fails at runtime.
  • Inconsistent custom columns across routines create sparse tables.
  • Unexpected run names are usually due to the runs setting.