Introduction

What is BIDS?

The Brain Imaging Data Structure (BIDS) is a standard for organizing and describing brain datasets, including MRI. The common naming convention and folder structure allow researchers to easily reuse BIDS datasets, re-apply analysis protocols, and run standardized automatic data preprocessing pipelines (and particularly, BIDS Apps). The BIDS starter-kit contains a wide collection of educational resources. Validity of the structure can be assessed with the online BIDS-Validator. The tree of a typical, valid (BIDS-compliant) dataset is shown below:

ds000003/
 ├─ CHANGES
 ├─ dataset_description.json
 ├─ participants.tsv
 ├─ README
 ├─ sub-01/
 │ ├─ anat/
 │ │ ├─ sub-01_inplaneT2.nii.gz
 │ │ └─ sub-01_T1w.nii.gz
 │ └─ func/
 │ ├─ sub-01_task-rhymejudgment_bold.nii.gz
 │ └─ sub-01_task-rhymejudgment_events.tsv
 ├─ sub-02/
 ├─ sub-03/

What is a BIDS App?

(Taken from the BIDS Apps paper)

A BIDS App is a container image capturing a neuroimaging pipeline that takes a BIDS-formatted dataset as input. Since the input is a whole dataset, apps are able to combine multiple modalities, sessions, and/or subjects, but at the same time need to implement ways to query input datasets. Each BIDS App has the same core set of command-line arguments, making them easy to run and integrate into automated platforms. BIDS Apps are constructed in a way that does not depend on any software outside of the container image other than the container engine.

BIDS Apps rely upon two technologies for container computing:

1. Docker — for building, hosting as well as running containers on local hardware (running Windows, Mac OS X or Linux) or in the cloud.
2. Singularity — for running containers on HPCs (high-performance computing).

BIDS Apps are deposited in the Docker Hub repository, making them openly accessible. Each app is versioned and all of the historical versions are available to download. By reporting the BIDS App name and version in a manuscript, authors can provide others with the ability to exactly replicate their analysis workflow.

Docker is used for its excellent documentation, maturity, and the Docker Hub service for storage and distribution of the images. Docker containers are easily run on personal computers and cloud services. However, the Docker Runtime was originally designed to run different components of web services (HTTP servers, databases etc.) using cloud resources. Docker thus requires root or root-like permissions, as well as modern versions of Linux kernel (to perform user mapping and management of network resources); though this is not a problem in context of renting cloud resources (which are not shared with other users), it makes it difficult or impossible to use in a multi-tenant environment such as an HPC system, which is often the most cost-effective computational resource available to researchers.

Singularity, on the other hand, is a unique container technology designed from the ground up with the encapsulation of binary dependencies and HPC use in mind. Its main advantage over Docker is that it does not require root access for container execution and thus is safe to use on multi-tenant systems. In addition, it does not require recent Linux kernel functionalities (such as namespaces, cgroups and capabilities), making it easy to install on legacy systems.

Analysis levels

BIDS Apps decouple the individual level analysis (processing of independent subjects) from group-level analyses aggregating participants. For the analysis of individual subjects, Apps need to understand the BIDS structure of the input dataset, so that the required inputs for the designated subject are found. Apps are designed to easily process derivatives generated by the participant-level or other Apps. The overall workflow has an entry-point and an end-point responsible of setting-up the map-reduce tasks and the tear-down including organizing the outputs for its archiving, respectively. Each App may implement multiple map and reduce steps.

A unified command-line interface

To improve user experience and ability to integrate BIDS Apps into various computational platforms, each App follows a set of core command-line arguments:

$ <entrypoint> <bids_dataset> <output_path> <analysis_level>

For instance, to run fMRIPrep on a dataset located in /data/bids_root and write the outputs to /data/bids_root/derivatives/:

$ fmriprep /data/bids_root /data/bids_root/derivatives/ participant

In this case, we have selected to run the participant level (to process individual subjects). fMRIPrep does not have a group level, but other BIDS Apps may have. For instance, MRIQC generates group-level reports with the following command-line:

$ mriqc /data/bids_root /data/bids_root/derivatives/ group

What are BIDS Derivatives?

NiPreps generate derivatives of the original data, and they fulfill the BIDS specification for the results of Apps that are created for subsequent consumption by other BIDS-Apps. These derivatives must follow the BIDS Derivatives specification (draft). An example of BIDS Derivatives filesystem tree, generated with fMRIPrep 1.5:

derivatives/
├── fmriprep/
│ ├── dataset_description.json
│ ├── logs
│ ├── sub-01.html
│ ├── sub-01/
│ │ ├── anat/
│ │ │ ├── sub-01_desc-brain_mask.nii.gz
│ │ │ ├── sub-01_dseg.nii.gz
│ │ │ ├── sub-01_label-GM_probseg.nii.gz
│ │ │ ├── sub-01_label-WM_probseg.nii.gz
│ │ │ ├── sub-01_label-CSF_probseg.nii.gz
│ │ │ ├── sub-01_desc-preproc_T1w.nii.gz
│ │ │ ├── sub-01_space-MNI152_desc-brain_mask.nii.gz
│ │ │ ├── sub-01_space-MNI152_dseg.nii.gz
│ │ │ ├── sub-01_space-MNI152_label-GM_probseg.nii.gz
│ │ │ ├── sub-01_space-MNI152_label-WM_probseg.nii.gz
│ │ │ ├── sub-01_space-MNI152_label-CSF_probseg.nii.gz
│ │ │ ├── sub-01_space-MNI152_desc-preproc_T1w.nii.gz
│ │ │ ├── sub-01_from-MNI152_to-T1w_mode-image_xfm.h5
│ │ │ ├── sub-01_from-T1w_to-MNI152_mode-image_xfm.h5
│ │ │ └── sub-01_from-orig_to-T1w_mode-image_xfm.txt
│ │ ├── figures/
│ │ └── func/
│ │   ├── sub-01_task-rhymejudgment_space-MNI152_boldref.nii.gz
│ │   ├── sub-01_task-rhymejudgment_space-MNI152_desc-preproc_bold.nii.gz
│ │   ├── sub-01_task-rhymejudgment_space-MNI152_desc-confounds_regressors.nii.gz
│ │   └── sub-01_task-rhymejudgment_space-MNI152_desc-brain_mask.nii.gz
│ ├── sub-02.html
│ ├── sub-02/
│ ├── sub-03.html
│ └── sub-03/