PyBIDS

0.22.0 · active · verified Fri Apr 17

PyBIDS is a Python library that provides an interface for interacting with datasets organized according to the Brain Imaging Data Structure (BIDS) specification. It allows users to query, manage, and extract information from BIDS datasets, supporting local and cloud-based paths. The current version is 0.22.0, and the library maintains an active release cadence with minor feature releases every few months and frequent bug-fix updates.

Common errors

```
TypeError: BIDSLayout.get() got an unexpected keyword argument 'absolute_paths'
```
cause Attempting to disable `absolute_paths` or pass indexer arguments directly to `BIDSLayout.get()` in PyBIDS 0.20.0 or newer.

fix This functionality was removed. All paths are now absolute. For indexer configuration, use `BIDSLayoutIndexer` when initializing `BIDSLayout`.
```
ImportError: cannot import name 'BIDSLayout' from 'pybids.layout'
```
cause Using an incorrect import path for `BIDSLayout`.

fix The main `BIDSLayout` class is available directly under the top-level `bids` package. Use `from bids import BIDSLayout`.
```
RuntimeError: bids-validator returned non-zero exit code
```
cause The BIDS dataset being indexed or validated contains structural errors or does not conform to the BIDS specification, and `validate=True` (default) was used in `BIDSLayout` initialization.

fix Inspect the output of the validator for specific errors. Rectify issues in your BIDS dataset. Alternatively, initialize `BIDSLayout(..., validate=False)` to skip validation, but be aware this may lead to issues if the data is severely malformed.
```
KeyError: 'Cannot find field with name 'my_custom_entity''
```
cause Attempting to query a BIDSLayout for a custom entity that is not defined in the BIDS specification patterns or custom patterns provided to the layout.

fix Ensure your custom entity is correctly defined in a custom BIDS pattern file and loaded into the `BIDSLayout` instance upon initialization (e.g., `BIDSLayout(..., config=['my_custom_config.json'])`).

Warnings

breaking PyBIDS versions 0.21.0 and higher require Python 3.10+. Support for Python 3.9 was dropped. Additionally, minimum versions for core scientific dependencies (NumPy, SciPy, NiBabel, Pandas) were raised.
Fix: Upgrade your Python environment to 3.10 or newer. Ensure all scientific computing dependencies (NumPy, SciPy, NiBabel, Pandas) meet or exceed the specified minimum versions (e.g., NumPy >=1.24, Pandas >=2.0).
breaking As of PyBIDS 0.20.0, several previously deprecated behaviors now raise errors. Specifically, passing indexer arguments directly to `BIDSLayout` or `BIDSLayout.get()` (e.g., `indexer_args`) and disabling `absolute_paths` mode in `BIDSLayout()` or `BIDSLayout.get()` are no longer allowed.
Fix: To control indexing behavior, create an explicit `BIDSLayoutIndexer` instance and pass it to the `BIDSLayout` constructor. Ensure all file paths are handled as absolute paths, as disabling this mode is no longer supported.
gotcha PyBIDS 0.19.0 added support for '+' signs in BIDS labels and suffixes, anticipating BIDS specification updates. However, files using these '+' signs will not pass validation if using `bidsschematools` versions prior to the official BIDS specification update.
Fix: Be aware that while `pybids` can index these files, BIDS validation tools might flag them as invalid until the BIDS specification and `bidsschematools` are updated to reflect this change.
gotcha In PyBIDS versions 0.9.0 through 0.16.3, boolean metadata fields with a value of `False` were incorrectly read as `True` when using SQL indexing.
Fix: Upgrade to PyBIDS 0.16.4 or later to ensure boolean metadata fields are correctly interpreted.

Install

pip install pybids Install latest stable version

Imports

BIDSLayout
wrong:
```
from pybids.layout import BIDSLayout
```
correct:
```
from bids import BIDSLayout
```
The top-level `bids` package is the correct entry point, not a submodule of `pybids`.
BIDSLayoutIndexer
wrong:
```
from bids import BIDSLayoutIndexer
```
correct:
```
from bids.layout import BIDSLayoutIndexer
```
While `BIDSLayout` is top-level, `BIDSLayoutIndexer` is explicitly in `bids.layout`.

Quickstart

This quickstart demonstrates how to initialize a `BIDSLayout` for a BIDS-compliant dataset and query for specific files using entity key-value pairs. It includes creating a minimal dummy BIDS structure to make the example runnable without an existing dataset.

import os
from bids import BIDSLayout

# Create a dummy BIDS directory for demonstration
dummy_bids_dir = 'my_bids_dataset'
os.makedirs(os.path.join(dummy_bids_dir, 'sub-01', 'ses-01', 'anat'), exist_ok=True)
with open(os.path.join(dummy_bids_dir, 'dataset_description.json'), 'w') as f:
    f.write('{"Name": "My Dummy Dataset", "BIDSVersion": "1.4.0"}')
with open(os.path.join(dummy_bids_dir, 'sub-01', 'ses-01', 'anat', 'sub-01_ses-01_T1w.nii.gz'), 'w') as f:
    f.write('dummy data')

# Initialize the BIDSLayout
layout = BIDSLayout(dummy_bids_dir, validate=False)

# Query for files
t1w_files = layout.get(subject='01', suffix='T1w', extension='.nii.gz')

print(f"Found {len(t1w_files)} T1w files for subject 01:")
for f in t1w_files:
    print(f.path)

# Clean up dummy directory (optional)
# import shutil
# shutil.rmtree(dummy_bids_dir)

view raw JSON →