Metadata-Version: 2.4
Name: psychopy-bids
Version: 2025.2.0.dev34
Summary: A PsychoPy plugin for using the Brain Imaging Data Structure (BIDS) to organize and describe data.
Author-email: Christoph Anzengruber <christoph.anzengruber@uni-graz.at>, Florian Schöngaßner <florian.schoengassner@uni-graz.at>, Lukas Wiertz <lukas.wiertz@uni-graz.at>
License: GNU General Public License v3 (GPLv3)
Project-URL: project, https://pypi.org/project/psychopy-bids
Project-URL: changelog, https://gitlab.com/psygraz/psychopy-bids/-/blob/release/CHANGELOG.md
Project-URL: documentation, https://psychopy-bids.readthedocs.io/en/stable
Project-URL: repository, https://gitlab.com/psygraz/psychopy-bids
Keywords: psychopy,bids,psychology,data organization
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.4.3
Requires-Dist: hedtools>=0.5.0
Requires-Dist: packaging>=20.0
Requires-Dist: seedir>=0.4.0
Provides-Extra: docs
Requires-Dist: mkdocs; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: mkdocstrings; extra == "docs"
Requires-Dist: mkdocstrings-python; extra == "docs"
Requires-Dist: mkdocs-jupyter; extra == "docs"
Requires-Dist: mkdocs-roamlinks-plugin; extra == "docs"
Requires-Dist: seedir; extra == "docs"
Requires-Dist: pytkdocs[numpy-style]; extra == "docs"
Provides-Extra: dev
Requires-Dist: autopep8; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: bandit; extra == "dev"
Requires-Dist: codespell; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: psychopy; extra == "dev"
Dynamic: license-file

# psychopy-bids

A [PsychoPy](https://www.psychopy.org) plugin to work with the [Brain Imaging Data Structure (BIDS)](https://bids-specification.readthedocs.io).

- **[Documentation](https://psychopy-bids.readthedocs.io)**  
- **[Gitlab Repository](https://gitlab.com/psygraz/psychopy-bids)**  
- **[Report Issues](https://gitlab.com/psygraz/psychopy-bids/issues)**  
- **[Contributing Guidelines](https://gitlab.com/psygraz/psychopy-bids/-/blob/release/CONTRIBUTING.md)**  
- **[Code of Conduct](https://gitlab.com/psygraz/psychopy-bids/-/blob/release/CONDUCT.md)**  
- **[PyPI Package](https://pypi.org/project/psychopy-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](https://gitlab.com/psygraz/psychopy-bids/-/blob/release/CHANGELOG.md).

---

## 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:

```console
pip install psychopy-bids
```

---

## Usage

The psychopy bids plugin can be used to create valid BIDS valid datasets by creating [behavioral](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/behavioral-experiments.html#example-_behtsv) or [task events](https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/05-task-events.html) 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.

```py
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](https://gitlab.com/psygraz/psychopy-bids/-/blob/release/CONTRIBUTING.md). Please note that this project is released with a [Code of Conduct](https://gitlab.com/psygraz/psychopy-bids/-/blob/release/CONDUCT.md). 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`](https://cookiecutter.readthedocs.io/en/latest/) and the `py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter).
