Bids Format

BIDS Format & Project Organization

BIDS standard for any data type — naming conventions, dataset creation, validation, and project organization for single-modality through multi-modal datasets.

When to Use This Skill

• Naming or renaming files to follow BIDS conventions
• Setting up a new BIDS dataset or research project from scratch
• Converting any data (imaging, behavioral, annotations, physiology) into BIDS
• Organizing derivatives and analysis outputs
• Managing multi-modal, multi-experiment, or multi-site projects
• Preparing data for sharing on OpenNeuro or other repositories

BIDS Naming Conventions

Filename Structure

Every BIDS filename follows this pattern:

sub-<label>[_ses-<label>][_<entity>-<label>]*_<suffix>.<extension>

Example: sub-01_ses-pre_task-rest_run-02_bold.nii.gz

Entities (Key-Value Pairs)

Entities appear in a fixed order. Not all entities apply to all datatypes.

Suffixes by Datatype

Naming Rules

• Labels are alphanumeric only — no spaces, underscores, or special characters in values
• Entities are separated by underscores: sub-01_task-rest_bold.nii.gz
• Entity order is fixed — don't rearrange (sub → ses → task → acq → ce → rec → dir → run → echo → part → suffix)
• Every data file needs a JSON sidecar with the same name (except .json extension)
• TSV files also get JSON sidecars describing their columns

BIDS Data Types

BIDS supports 14 data types:

Key insight: beh/ is for standalone behavioral data (no concurrent imaging). Behavioral data during imaging (e.g., button presses during fMRI) goes in func/ as _events.tsv.

Project Directory Layout

my-project/
├── dataset_description.json    # Required: project metadata
├── README                      # Required: human-readable description
├── CHANGES                     # Optional: version history
├── LICENSE                     # Recommended: data license
├── participants.tsv            # Required: subject demographics
├── participants.json           # Required: column descriptions
├── sourcedata/                 # Raw unprocessed data (DICOMs, raw EEG, etc.)
│   └── sub-01/                 # Not required to be BIDS-formatted
├── sub-01/
│   ├── ses-01/                 # Optional session level
│   │   ├── anat/
│   │   ├── func/
│   │   ├── dwi/
│   │   ├── eeg/
│   │   ├── beh/
│   │   └── ...
│   └── sub-01_sessions.tsv
├── phenotype/                  # Questionnaires, clinical scores, assessments
│   ├── depression_scores.tsv
│   └── depression_scores.json
├── stimuli/                    # Shared stimulus files
├── code/                       # Analysis scripts, pipelines
└── derivatives/                # Pipeline outputs (each a BIDS derivative dataset)
    ├── fmriprep/
    │   ├── dataset_description.json
    │   └── sub-01/
    ├── qsiprep/
    └── custom-analysis/

When to Use sourcedata/ vs Project Root

Multi-Modal Dataset Example

A single subject with MRI, EEG, behavioral, and phenotype data:

my-multimodal-study/
├── dataset_description.json
├── participants.tsv
├── participants.json
├── phenotype/
│   ├── anxiety_scores.tsv              # Subject-level questionnaire
│   └── anxiety_scores.json
├── stimuli/
│   └── task-emotionreg_stimuli.csv
├── sub-01/
│   └── ses-01/
│       ├── anat/
│       │   ├── sub-01_ses-01_T1w.nii.gz
│       │   └── sub-01_ses-01_T1w.json
│       ├── func/
│       │   ├── sub-01_ses-01_task-emotionreg_bold.nii.gz
│       │   ├── sub-01_ses-01_task-emotionreg_bold.json
│       │   └── sub-01_ses-01_task-emotionreg_events.tsv   # In-scanner behavior
│       ├── dwi/
│       │   ├── sub-01_ses-01_dir-AP_dwi.nii.gz
│       │   ├── sub-01_ses-01_dir-AP_dwi.bval
│       │   └── sub-01_ses-01_dir-AP_dwi.bvec
│       ├── eeg/
│       │   ├── sub-01_ses-01_task-emotionreg_eeg.vhdr     # Same task, separate session
│       │   ├── sub-01_ses-01_task-emotionreg_eeg.json
│       │   ├── sub-01_ses-01_task-emotionreg_channels.tsv
│       │   └── sub-01_ses-01_task-emotionreg_events.tsv
│       └── beh/
│           ├── sub-01_ses-01_task-stroop_events.tsv        # Standalone behavioral
│           └── sub-01_ses-01_task-stroop_events.json

Required Top-Level Files

dataset_description.json

{
    "Name": "My Research Project",
    "BIDSVersion": "1.9.0",
    "DatasetType": "raw",
    "License": "CC BY 4.0",
    "Authors": ["Last, First M.", "Last2, First2"],
    "Acknowledgements": "Funding: NIH R01-XX12345",
    "GeneratedBy": [{"Name": "heudiconv", "Version": "1.1.0"}]
}

For derivatives, use "DatasetType": "derivative" and add SourceDatasets and GeneratedBy.

participants.tsv / participants.json

participant_id	age	sex	group	handedness
sub-01	28	M	control	right
sub-02	32	F	patient	left

The sidecar JSON describes each column with Description, Units, and/or Levels.

Modality-Specific Conversion Tools

Behavioral and Annotation Data

Standalone Behavioral Tasks (beh/)

sub-01/beh/
├── sub-01_task-stroop_beh.tsv       # Continuous recordings
├── sub-01_task-stroop_beh.json
├── sub-01_task-stroop_events.tsv    # Discrete events (onset, duration, trial_type, ...)
└── sub-01_task-stroop_events.json

Events During Imaging

Place _events.tsv in the same directory as the imaging file. Required columns: onset, duration.

onset	duration	trial_type	response_time	accuracy
0.0	0.5	target	0.432	1
2.5	0.5	nontarget	0.567	1

Where Annotations Go

Phenotype Directory

For questionnaires and subject-level data beyond demographics. Each TSV needs participant_id as the first column:

participant_id	bdi_total	bdi_cognitive	bdi_somatic
sub-01	12	5	7
sub-02	28	14	14

Organizing Derivatives

Every pipeline output is its own BIDS derivative dataset with a dataset_description.json.

derivatives/
├── fmriprep/           # fMRI preprocessing
├── qsiprep/            # DWI preprocessing
├── freesurfer/         # Surface reconstruction
├── mriqc/              # Quality metrics
├── xcpd/               # Post-processing (confound regression, parcellation)
├── mne-preprocess/     # EEG/MEG preprocessing
├── first-level/        # Subject-level statistical maps
└── group-analysis/     # Group-level results

Derivative naming: sub-XX_[entities]_space-<label>_desc-<label>_<suffix>.<ext>

The desc- entity distinguishes processing variants (e.g., desc-preproc, desc-filtered).

DataLad for Version Control

# Create dataset (text2git: text files in git, binaries in git-annex)
datalad create -c text2git my-project

# Save changes
datalad save -m "Add raw BIDS data for sub-01"

# Superdataset linking rawdata + derivatives
datalad create -c text2git my-project
datalad clone -d . <url-to-rawdata> inputs/rawdata
datalad clone -d . <url-to-derivatives> derivatives/fmriprep

For full DataLad workflows (RIA stores, collaboration, HPC), see references/datalad-workflows.md.

BIDS Validation

# CLI validator
pip install bids-validator  # or: npm install -g bids-validator
bids-validator /path/to/dataset

Common fixes: missing dataset_description.json, missing sidecar JSONs, unexpected files (add to .bidsignore), wrong entity ordering in filenames.

Sharing and Archiving

Before sharing checklist:

• Deface anatomical images (pydeface, mri_deface)
• Remove sourcedata/, dates from sidecars, identifiable free-text
• Validate with bids-validator
• Add LICENSE and complete dataset_description.json

Common Pitfalls

• Wrong entity order: entities must follow the fixed order (sub → ses → task → acq → ... → suffix)
• Behavioral data in wrong place: beh/ = standalone; during-scan → _events.tsv in imaging dir
• Missing JSON sidecars: every data file and TSV needs a sidecar
• Inconsistent subject IDs: same sub-XX everywhere including phenotype/ TSVs
• Forgetting phenotype/: questionnaires go at project level, not in subject directories
• Not defacing before sharing: anatomical MRIs contain identifiable facial features
• Mixing raw and derived: keep derivatives in derivatives/, never modify raw data

References

• references/modality-conversions.md — Detailed conversion guides for each modality (MRI, EEG, MEG, PET, behavioral, physio)
• references/electrophys-bids.md — EEG/MEG/iEEG/fNIRS with MNE-BIDS: formats, code, batch conversion
• references/pet-bids.md — PET-specific BIDS: required metadata, blood data, tracers
• references/datalad-workflows.md — DataLad: RIA stores, superdatasets, HPC workflows, reproducibility