Skip to content

psychopy-bids

A PsychoPy plugin to work with the Brain Imaging Data Structure (BIDS).

Breaking Changes in Non-Patch Versions

Non-patch versions (e.g., v2025.1.0, v2026.0.0) are major or minor releases that can introduce substantial new features or changes, potentially breaking compatibility. For previously written experiments, it is strongly recommended to continue using the specific version of psychopy-bids they were created with. Only upgrade to a newer psychopy-bids version for new experiments.

For more details, see the Changelog.

Installation

The easiest way to install psychopy-bids is through the PsychoPy Plugin Manager:

  1. Open PsychoPy.
  2. Go to the Tools menu and select Plugin/packages manager.
  3. Search for psychopy-bids in the list.
  4. Click Install.

Alternative: Install via pip

You can install psychopy-bids using pip:

pip install psychopy-bids

For more detailed installation instructions visit the Installation Guide in the documentation.

Usage

The psychopy bids plugin can be used to create valid BIDS valid datasets by creating behavioral or task events in Psychopy. This can be done directly in python code or using the psychopy builder.

In code, the BIDSHandler can create or extend an existing BIDS dataset, including directory structure and necessary metadata files. Individual BIDS events can be added during the experiment and are passed to the BIDSHandler to write event .tsv files and accompanying .json files.

from psychopy_bids import bids

handler = bids.BIDSHandler(dataset="example_dataset", subject="01", task="A")
handler.createDataset()

events = [
    bids.BIDSTaskEvent(onset=1.0, duration=0.5, event_type="stimulus", response="correct"),
    bids.BIDSTaskEvent(onset=1.0, duration=0, trial_type="trigger")
]

handler.addEvent(events)

participant_info = {"participant_id": handler.subject, "age": 18}

handler.writeEvents(participant_info=participant_info)
handler.addEnvironment()

In Builder, add BIDS components to routines where events should be logged. Configure event fields in the component settings, select the event type, and optionally add custom columns for experiment-specific metadata.

You can now select the BIDS Event Type directly in the BIDS Event Properties, streamlining the process.

BIDS Event Component

Using features such as custom columns it is possible to create detailed event tables for BIDS data.

onset duration event_role word color pressed_key trial_type response_time trial_number response_accuracy
15.2876 1.2295 instruction instruction_text black space n/a 1.2295 n/a n/a
16.5171 n/a response n/a n/a space n/a 1.2295 n/a n/a
16.538 0.5 fixation + black n/a n/a n/a n/a n/a
17.0593 0.8105 stimulus Red green left incongruent 0.8105 1.0 correct
17.8698 n/a response Red green left incongruent 0.8105 1.0 correct
17.8972 1.0 feedback Correct! green n/a incongruent n/a 1.0 n/a
18.9272 0.5 fixation + black n/a n/a n/a n/a n/a

Please see individual tutorials for using psychopy bids in code or the psychopy builder.

Contributing

Interested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.

License

psychopy-bids was created by Christoph Anzengruber, Florian Schöngaßner & Lukas Wiertz. It is licensed under the terms of the GNU General Public License v3.0 license.

Credits

psychopy-bids was created with cookiecutter and the py-pkgs-cookiecutter template.