psychopy-bids 2026.1.1

A PsychoPy plugin for using the Brain Imaging Data Structure (BIDS) to organize and describe data.

psychopy-bids

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

• Documentation
• Gitlab Repository
• Report Issues
• Contributing Guidelines
• Code of Conduct
• PyPI Package

---

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

Recommended: Install via PsychoPy Plugin Manager

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

---

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()

---

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.