PyBIDS

Citation and Resources:¶

Data from OpenNeuro¶

• Gorgolewski KJ and Storkey A and Bastin ME and Whittle IR and Wardlaw JM and Pernet CR (2022). A test-retest fMRI dataset for motor, language and spatial attention functions. OpenNeuro. [Dataset] doi: doiGorgolewski KJ et al. (2022)

Tools included in this workflow¶

pyBIDS:

• Yarkoni et al., (2019). PyBIDS: Python tools for BIDS datasets. Journal of Open Source Software, 4(40), 1294, https://doi.org/10.21105/joss.01294

• Yarkoni, T., Markiewicz, C. J., de la Vega, A., Gorgolewski, K. J., Salo, T., Gau, R., Halchenko, Y. O., Papadopoulos Orfanos, D., Esteban, O., McNamara, Q., DeStasio, K., Poline, J.-B., Johnson, H., Kalenkovich, E., Petrov, D., Nielson, D. M., James Kent, Kent, J. D., Appelhoff, S., … pierre-nedelec. (2024). PyBIDS: Python tools for BIDS datasets (0.18.1). Zenodo. Yarkoni et al. (2024)

Educational resources¶

• This example is highly inspired by the pybids documentation

Installation¶

PyBIDS simplifies the process of querying, summarizing, and managing data for neuroimaging researchers using the BIDS standard. Several Python packages for neuroimaging analysis—such as Nipype and Nilearn—are designed to integrate seamlessly with BIDS-formatted datasets

Data download¶

Querying BIDS datasets¶

Loading BIDS datasets¶

The BIDSLayout instance is a lightweight container for all of the files in the BIDS project directory. It automatically detects any BIDS entities found in the file paths, and allows us to perform simple but relatively powerful queries over the file tree. By default, defined BIDS entities include things like “subject”, “session”, “run”, and “type”.

Querying the BIDSLayout using get¶

When a BIDSLayout is initialized, it scans and indexes all files and metadata within the specified root directory. Once the indexing is complete, you can start exploring the dataset through different types of queries. The main method for this is .get(). If you call .get() without any arguments, it simply returns a list of all BIDS files in the dataset:

In this Python list, each element is a BIDSFile object. If you want to work with just file names, you can simpliy it with:

Common BIDS Entities:

The .get()method supports various arguments that let us narrow down the results based on specific criteria. Any BIDS-defined keywords - referred to as entities in PyBIDS - can be used as filters. Here are the most common ones:

suffix: The part of a BIDS filename just before the extension (e.g., ‘bold’, ‘events’, ‘physio’, etc.).

subject: The subject label

session: The session label

run: The run index

task: The task name

Query by subjects:

Query by sessions:

Query by tasks:

Here’s how we would retrieve all BOLD runs with .nii.gz extensions for subject ‘02’:

Extracting metadata¶

All the entities mentioned above are derived from the filenames in a BIDS dataset. However, sometimes we want to filter files not just by their names, but also using metadata defined in sidecar JSON files, as specified by the BIDS standard. When a BIDSLayout is initialized, it automatically indexes all associated metadata files. This means we can use any key found in a JSON file as a filter in .get(), and we can even combine these with core BIDS entities like subject, run, and task.

For example, suppose we want to retrieve all files that meet the following criteria: (a) the RepetitionTime metadata value is 2.5, (b) the task is either ‘covert_verb_generation’ or ‘finger_foot_lips’, and (c) the subject is ‘01’ or ‘02’.

Here’s how we can do that:

The BIDSFile¶

Calling .get() on a BIDSLayout returns a list of BIDSFile objects by default. These are lightweight representations of individual files within a BIDS dataset and offer convenient access to various attributes and methods. Let’s explore what a BIDSFile can do. To start, we’ll select a random file from the layout.

A BIDSFile provides a convenient interface to interact with individual files in a BIDS dataset. Depending on the file type, different attributes and methods are available. Keep in mind that some methods are only applicable to specific types of files—for example, you can’t use .get_image() on a non-image file.

Here are some commonly used attributes and methods:

.path – Full path to the file

.filename – Name of the file (excluding the directory)

.dirname – Directory where the file is located

.get_entities() – Returns a dictionary of entities (e.g., subject, task) associated with the file; metadata can be optionally included

.get_image() – Loads the file as a nibabel image (only valid for image files)

.get_df() – Loads the file into a pandas DataFrame (works for .tsv files)

.get_metadata() – Retrieves a dictionary of metadata from the related JSON sidecar(s)

.get_associations() – Lists other files that are linked to this one (e.g., JSON, events, or anatomical associations)

Exporting a BIDSLayout to a pandas Dataframe¶

If you’re looking for a high-level overview of all the files in your BIDSLayout without manually iterating through each BIDSFile and extracting their entities, the .to_df() method offers a convenient solution. It provides a structured summary of the dataset in the form of a pandas DataFrame.

BIDS Validator¶

PyBIDS includes an implicit import of the BIDSValidator class from the separate bids-validator package. This class can be used to check whether a given file path conforms to BIDS naming conventions and to infer what type of data the file represents.

However, it’s important to note that the Python-based validator may lag behind the official JavaScript implementation available online. Additionally, the Python version only validates individual file paths - it doesn’t support validation of an entire BIDS dataset. For full dataset validation, it’s recommended to use the online BIDS Validator.

Dependencies in Jupyter/Python¶

• Using the package watermark to document system environment and software versions used in this notebook, alongside the Neurodesktop version extracted from the JUPYTER_IMAGE or NEURODESKTOP_VERSION environment variables.