psychopy-bids¶
A PsychoPy plugin to work with the Brain Imaging Data Structure (BIDS).
- Website
- Documentation
- Source Code
- Report Issues
- Contributing Guidelines
- Code of Conduct
- PyPI Package
⚠️ Breaking Changes in v2025 ⚠️¶
This release introduces breaking changes that may affect your existing workflows. It is highly recommended to always use the same version of psychopy-bids
for experiments that have already been written. If an experiment was created with a specific version of psychopy-bids
(e.g., vX.X.X
), you should continue using that version to ensure compatibility and reproducibility. Only upgrade to a newer version for new experiments.
Please review the following resources for detailed information:
Installation¶
For more detailed installation instructions, including guidance on setting up a virtual environment and additional configuration options, 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 the builder, you can now use the newly added BIDS components to add events to a BIDS dataset. The previously used components—BIDS Task Event and BIDS Beh Event—are deprecated and retained only for backward compatibility.
You can now select the BIDS Event Type directly in the BIDS Event Properties, streamlining the process.
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. 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.