{"id":10080,"library":"pybids","title":"PyBIDS","description":"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.","status":"active","version":"0.22.0","language":"en","source_language":"en","source_url":"https://github.com/bids-standard/pybids","tags":["neuroimaging","BIDS","data management","scientific computing","MRI","fMRI"],"install":[{"cmd":"pip install pybids","lang":"bash","label":"Install latest stable version"}],"dependencies":[{"reason":"Minimum Python version for recent releases","package":"python","optional":false},{"reason":"Core dependency for numerical operations","package":"numpy","optional":false},{"reason":"Core dependency for scientific computing","package":"scipy","optional":false},{"reason":"Used for data manipulation and tabular output","package":"pandas","optional":false},{"reason":"Used for reading/writing neuroimaging file formats","package":"nibabel","optional":false},{"reason":"Enables support for cloud and other non-local file systems","package":"universal_pathlib","optional":false},{"reason":"Required for BIDS dataset validation","package":"bidsschematools","optional":false}],"imports":[{"note":"The top-level `bids` package is the correct entry point, not a submodule of `pybids`.","wrong":"from pybids.layout import BIDSLayout","symbol":"BIDSLayout","correct":"from bids import BIDSLayout"},{"note":"While `BIDSLayout` is top-level, `BIDSLayoutIndexer` is explicitly in `bids.layout`.","wrong":"from bids import BIDSLayoutIndexer","symbol":"BIDSLayoutIndexer","correct":"from bids.layout import BIDSLayoutIndexer"}],"quickstart":{"code":"import os\nfrom bids import BIDSLayout\n\n# Create a dummy BIDS directory for demonstration\ndummy_bids_dir = 'my_bids_dataset'\nos.makedirs(os.path.join(dummy_bids_dir, 'sub-01', 'ses-01', 'anat'), exist_ok=True)\nwith open(os.path.join(dummy_bids_dir, 'dataset_description.json'), 'w') as f:\n    f.write('{\"Name\": \"My Dummy Dataset\", \"BIDSVersion\": \"1.4.0\"}')\nwith open(os.path.join(dummy_bids_dir, 'sub-01', 'ses-01', 'anat', 'sub-01_ses-01_T1w.nii.gz'), 'w') as f:\n    f.write('dummy data')\n\n# Initialize the BIDSLayout\nlayout = BIDSLayout(dummy_bids_dir, validate=False)\n\n# Query for files\nt1w_files = layout.get(subject='01', suffix='T1w', extension='.nii.gz')\n\nprint(f\"Found {len(t1w_files)} T1w files for subject 01:\")\nfor f in t1w_files:\n    print(f.path)\n\n# Clean up dummy directory (optional)\n# import shutil\n# shutil.rmtree(dummy_bids_dir)","lang":"python","description":"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."},"warnings":[{"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).","message":"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.","severity":"breaking","affected_versions":"0.21.0+"},{"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.","message":"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.","severity":"breaking","affected_versions":"0.20.0+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.19.0+"},{"fix":"Upgrade to PyBIDS 0.16.4 or later to ensure boolean metadata fields are correctly interpreted.","message":"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.","severity":"gotcha","affected_versions":"0.9.0 - 0.16.3"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"This functionality was removed. All paths are now absolute. For indexer configuration, use `BIDSLayoutIndexer` when initializing `BIDSLayout`.","cause":"Attempting to disable `absolute_paths` or pass indexer arguments directly to `BIDSLayout.get()` in PyBIDS 0.20.0 or newer.","error":"TypeError: BIDSLayout.get() got an unexpected keyword argument 'absolute_paths'"},{"fix":"The main `BIDSLayout` class is available directly under the top-level `bids` package. Use `from bids import BIDSLayout`.","cause":"Using an incorrect import path for `BIDSLayout`.","error":"ImportError: cannot import name 'BIDSLayout' from 'pybids.layout'"},{"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.","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.","error":"RuntimeError: bids-validator returned non-zero exit code"},{"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'])`).","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.","error":"KeyError: 'Cannot find field with name 'my_custom_entity''"}]}