BIDS Apps (Brain Imaging Data Structure): How They Work

BIDS Apps are portable neuroimaging pipelines packaged as container images that accept a dataset organised in the Brain Imaging Data Structure (BIDS) as input. Because every app shares the same core command-line arguments, a researcher who has run one can run another with the same pattern. This page is for researchers and lab managers who need to understand the contract, choose between Docker and Singularity, and report an app run in a way others can reproduce. (“BIDS” here is the neuroimaging data standard, not procurement bids.)

What are BIDS Apps?

A BIDS App is a container image that packages a neuroimaging analysis pipeline and takes a BIDS-formatted dataset as its input (Gorgolewski et al., 2017). Because the whole dataset is the input, an app can combine information across modalities, sessions and subjects. The container holds the software and its dependencies, so the only requirement on the host machine is a container engine, Docker or Singularity. The BIDS project describes BIDS Apps as portable neuroimaging pipelines that understand BIDS datasets.

Each app lives in its own GitHub repository containing a Dockerfile and a wrapper script, and its image is built on Docker Hub. Images are versioned and historical versions remain available, which is what makes a past analysis re-runnable. The format builds on the data standard described in OpenNeuro and BIDS neuroimaging data sharing.

BIDS Apps command-line interface

All BIDS Apps share the same core interface: three positional arguments and a small set of common options. Any pipeline-specific arguments are passed through in addition.

Argument	Meaning
bids_dir (positional 1)	The input dataset. Treated as read-only and must conform to BIDS.
output_dir (positional 2)	The only directory the pipeline should write to.
analysis_level (positional 3)	participant (per-subject processing) or group (optional second stage across subjects). Multi-step apps may use labels such as participant2 or group2.
--participant_label	One or more subject labels, space-separated, written without the sub- prefix. If omitted, all subjects are processed.
--n_cpus	Number of CPUs available to the app.
--mem_mb	Memory available to the app, in megabytes.

Participant-level vs group-level analysis

The participant level is a map step: each subject is processed independently, so runs can execute in parallel, for example as separate jobs on a cluster, one per --participant_label. The group level is a reduce step: it consumes the participant-level outputs and cannot be split across subjects. A typical sequence is to finish all participant-level runs, then run the group level once on the same output_dir.

Worked example: the command pattern

The pattern below shows the argument order only; the paths are placeholders. The paper’s template app is bids/example.

# Docker: mount the dataset read-only, and a writable output folder
docker run -ti --rm \n  -v /path/to/dataset:/data:ro \n  -v /path/to/output:/out \n  bids/example /data /out participant --participant_label 01 02

# Group level, after all participants have finished
docker run -ti --rm \n  -v /path/to/dataset:/data:ro \n  -v /path/to/output:/out \n  bids/example /data /out group

Here /data is bids_dir, /out is output_dir, and the subjects processed in the first command are sub-01 and sub-02. Replace the /path/to/... segments with local folders, and consult the specific app’s own documentation for its additional options and resource needs.

Docker vs Singularity for BIDS Apps

	Docker	Singularity
Where it runs	Windows, macOS, Linux and cloud	Designed for high-performance computing (HPC) clusters
Permissions	Needs root-like permissions, which makes it hard to use on shared HPC systems	Does not need root to run
Getting the image	Pulled from Docker Hub	Docker images are converted outside the cluster (the paper uses docker2singularity)

Examples of BIDS Apps

The BIDS website lists BIDS Apps; the page, last updated 12 October 2024, listed 56 in its table of latest images. The categories below use that page’s own descriptions.

Purpose	Example apps
Preprocessing	fMRIPrep (robust fMRI preprocessing; see fMRIPrep), QSIPrep (diffusion MRI), PETPrep (PET), ASLPrep (arterial spin labelling), NiBabies (infant brain MRI)
Quality control	MRIQC (automated quality-control reports for structural and functional MRI)
Post-processing and modelling	XCP-D (post-processing of fMRIPrep, NiBabies, HCP and DCAN BOLD derivatives), FitLins (linear models on BIDS datasets)
Anonymisation	BIDSonym (pseudo-anonymisation)
Template for authors	example

Many of these operate on functional data; background on that signal is in BOLD signal.

Assumptions and common mistakes

• The dataset must be BIDS-compliant. The apps assume the BIDS layout; an invalid dataset is not a supported input.
• Do not write into bids_dir. It is the read-only input; all results go to output_dir.
• Do not include sub- in --participant_label. Use 01, not sub-01.
• Do not run the group level early. It depends on the participant-level outputs.
• Do not rely on an unpinned image name. Versions are retained, so record and pin the one you used.

How to report a BIDS App

The paper emphasises that images are versioned and that historical versions remain available, so reporting the exact version is what lets a reader repeat the run. A reporting checklist consistent with that:

• App name and the exact version or image tag used.
• The container engine (Docker or Singularity) and, where available, the image identifier.
• The analysis level(s) run and any options passed (--participant_label, --n_cpus, --mem_mb, pipeline-specific arguments).
• The dataset supplied, and that it passed BIDS validation.
• A citation for the app’s own publication where it has one, plus Gorgolewski et al. (2017) for the BIDS Apps framework.

FAQ

Do BIDS Apps need BIDS-valid data?

Yes. The input is a BIDS-formatted dataset, and the apps are built to understand that layout.

Can I run a BIDS App on a cluster?

Yes. Singularity is designed for HPC and does not need root. Convert the Docker image outside the cluster, then submit participant-level runs as independent jobs.

How many BIDS Apps are there?

The BIDS website’s list, as updated 12 October 2024, showed 56 apps in its latest-image table. The 2017 paper reported 22 at publication. The count changes as apps are added, so check the list for the current figure.

What is the difference between participant and group level?

Participant level processes each subject independently and can run in parallel; group level combines participant outputs and cannot be split.

Sources

• Gorgolewski, K. J., et al. (2017). BIDS apps: Improving ease of use, accessibility, and reproducibility of neuroimaging data analysis methods. PLoS Computational Biology, 13(3), e1005209. journals.plos.org (read 2026-11-08).
• BIDS website, BIDS Apps list: bids.neuroimaging.io/tools/bids-apps.html (page updated 12 October 2024; read 2026-11-08).

Related: MNE-Python for electrophysiology analysis.