stanislavjiricek/bids

BIDS — Brain Imaging Data Structure

BIDS is the community-standard way to organize, name, and describe neuroimaging datasets. It covers MRI/fMRI, EEG, MEG, iEEG, PET, DWI, NIRS, microscopy, motion capture, and MRS. BIDS compliance unlocks the full ecosystem: bids-validator, fMRIPrep, MRIQC, pybids, MNE-BIDS, and 100+ BIDS Apps. Over 1500 public datasets on OpenNeuro use it; 3000+ papers cite it.

---

When to invoke this skill

• User asks how to structure, organize, or convert neuroimaging data
• Dataset has BIDS-like structure and you need to navigate or validate it
• User is setting up a new study and needs to know what files/folders to create
• Running /data phase: inventory, validate, or convert to BIDS
• Running /data-preprocess: loading BIDS-organized data into MNE or nibabel
• Running /data-analyze: querying the dataset with pybids or MNE-BIDS
• User mentions bids-validator errors or compliance issues

---

BIDS hierarchy at a glance

dataset/
├── dataset_description.json   ← required
├── participants.tsv            ← required
├── participants.json           ← recommended
├── README                      ← recommended
├── CHANGES                     ← recommended
├── .bidsignore                 ← optional
├── sub-<label>/
│   ├── [ses-<label>/]          ← optional; omit if single session
│   │   ├── anat/               ← T1w, T2w, FLAIR, ...
│   │   ├── func/               ← BOLD fMRI + events
│   │   ├── dwi/                ← diffusion + bval/bvec
│   │   ├── fmap/               ← field maps
│   │   ├── eeg/                ← EEG + channels + coordsystem
│   │   ├── meg/                ← MEG + channels + coordsystem
│   │   ├── ieeg/               ← iEEG + electrodes + coordsystem
│   │   ├── pet/                ← PET + blood data
│   │   ├── perf/               ← perfusion (ASL)
│   │   ├── nirs/               ← fNIRS
│   │   ├── motion/             ← motion capture
│   │   ├── mrs/                ← MR spectroscopy
│   │   └── beh/                ← behavioral-only data
│   └── scans.tsv               ← optional; lists files + acq_time
├── sourcedata/                 ← raw/pre-BIDS originals (unvalidated)
├── derivatives/                ← pipeline outputs (fMRIPrep, MNE, etc.)
└── code/                       ← analysis scripts

---

Filename entity ordering

Entities appear in this exact order — wrong order fails validation:

sub-<label>  [ses-<label>]  [task-<label>]  [acq-<label>]  [ce-<label>]
[rec-<label>]  [dir-<label>]  [run-<index>]  [echo-<index>]  [flip-<index>]
[part-<label>]  [chunk-<index>]  _<suffix>.<extension>

Examples:

sub-01_T1w.nii.gz
sub-01_ses-01_task-rest_bold.nii.gz
sub-01_ses-01_task-faces_run-1_bold.nii.gz
sub-01_task-rest_acq-multiband_bold.json
sub-01_dir-AP_epi.nii.gz
sub-01_ses-01_task-rest_eeg.edf
sub-01_ses-01_task-auditory_meg.fif

Rules: alphanumeric + hyphens + underscores only; no spaces; each entity once per filename; case-sensitive; suffix always last before extension.

---

Required top-level files

dataset_description.json (required)

{
  "Name": "My Study",
  "BIDSVersion": "1.11.1",
  "DatasetType": "raw",
  "License": "CC-BY-4.0",
  "Authors": [{"name": "Jane Doe", "email": "[email protected]"}],
  "Acknowledgements": "Funded by ...",
  "HowToAcknowledge": "Please cite: ...",
  "Funding": [{"Funder": "NIH", "Grant": "R01DA123456"}],
  "EthicsApprovals": [{"Name": "IRB", "Reference": "IRB00012345"}],
  "ReferencesAndLinks": ["https://doi.org/10.1038/..."]
}

For derivatives, add:

{
  "DatasetType": "derivative",
  "GeneratedBy": [{"Name": "fMRIPrep", "Version": "22.1.1",
                   "CodeURL": "https://github.com/nipreps/fmriprep"}],
  "SourceDatasets": [{"URL": "ds004157", "Version": "1.0.0"}]
}

participants.tsv (required)

participant_id	age	sex	group	handedness
sub-01	25	M	control	R
sub-02	28	F	patient	L

participants.json (recommended)

{
  "age": {"Description": "Age in years", "Units": "years"},
  "sex": {"Description": "Biological sex", "Levels": {"M": "male", "F": "female"}},
  "group": {"Description": "Group", "Levels": {"control": "Healthy control", "patient": "Patient"}}
}

---

Key metadata rules by modality

| Modality | Required in JSON sidecar | |----------|--------------------------| | func BOLD | TaskName, RepetitionTime | | EEG | SamplingFrequency, PowerLineFrequency | | MEG | SamplingFrequency | | iEEG | SamplingFrequency, PowerLineFrequency | | DWI | (needs .bval and .bvec files, not just JSON) | | PET | Manufacturer, BodyPart, TracerName, InjectedRadioactivity |

For full field lists → references/metadata.md

---

BIDS validation

# CLI (Node.js)
npm install -g bids-validator
bids-validator /path/to/dataset

# Web tool
# https://bids-standard.github.io/bids-validator/

# Python
pip install bids-validator
python -m bids_validator /path/to/dataset

Suppress known non-issues with .bidsignore:

*_physio.tsv.gz      # custom physio format
sourcedata/          # always excluded
tmp_*/               # temp folders

For validator error codes and fixes → references/tools.md

---

Loading BIDS in Python

from bids import BIDSLayout

layout = BIDSLayout('/path/to/dataset')
print(layout.get_subjects())          # ['01', '02', ...]
print(layout.get_tasks())             # ['rest', 'nback']

# Get all BOLD files
bold = layout.get(suffix='bold', extension='nii.gz', return_type='file')

# Get metadata
meta = layout.get_metadata('sub-01_task-rest_bold.nii.gz')
print(meta['RepetitionTime'])

For MNE-BIDS (EEG/MEG) → references/tools.md For pybids full API → references/tools.md For complete example datasets → references/examples.md

---

Derivatives

Preprocessed outputs live in derivatives/<pipeline>/:

• Use space-MNI152NLin2009cAsym entity for normalized images
• Use res-<label> for resampled resolution
• derivatives/ needs its own dataset_description.json with DatasetType: derivative

Full derivatives structure → references/structure.md

---

BIDS in neuroflow phases

/data phase

1. Inventory the data directory — identify modalities, subjects, sessions
2. Validate with bids-validator or manual check against this skill
3. Convert if needed: raw → BIDS using mne_bids.write_raw_bids() (EEG/MEG) or dcm2niix + renaming (MRI)
4. Save data-inventory.md to .neuroflow/data/ noting BIDS compliance status

/data-preprocess phase

• Load BIDS data: BIDSLayout + layout.get() or mne_bids.read_raw_bids()
• Pull sidecar metadata: sampling rate, task name, events from events.tsv
• Save preprocessed outputs to derivatives/<pipeline>/ with correct dataset_description.json

/data-analyze phase

• Query dataset structure with pybids before loading data
• Match analysis design to BIDS metadata (task labels, run indices, subject groups from participants.tsv)
• Store analysis outputs in derivatives/analysis/ or project results/

---

Reference files in this skill

| File | Contents | |------|----------| | references/structure.md | Full folder hierarchy per modality, all required/optional files, entity table | | references/metadata.md | JSON sidecar fields for MRI/EEG/MEG/iEEG/PET, events.tsv, scans.tsv | | references/tools.md | bids-validator, pybids, MNE-BIDS, fMRIPrep, MRIQC — install + usage | | references/examples.md | Complete example dataset trees + Python code snippets |

Read the relevant reference file when you need:

• All required/optional files for a specific modality → structure.md
• Which JSON fields to put in a sidecar → metadata.md
• How to use a specific BIDS tool → tools.md
• A full working example to base conversion code on → examples.md

---

Quick troubleshooting

| Symptom | Likely cause | Fix | |---------|-------------|-----| | Validator: "Not a valid BIDS filename" | Entity order wrong or unknown suffix | Check entity order (sub, ses, task, acq, run…); verify suffix against spec | | Validator: "IntendedFor missing file" | JSON references non-existent image | Check path; must be relative from dataset root | | Validator: "Missing required file" | dataset_description.json or participants.tsv absent | Create the file | | Validator: "JSON_KEY_RECOMMENDED" | Sidecar missing recommended field | Add field or use .bidsignore for now | | pybids: empty layout | Wrong root path or missing dataset_description.json | Check path; ensure root-level JSON exists | | MNE-BIDS: wrong channel types | channels.tsv type column incorrect | Fix: EEG, EOG, ECG, EMG, STIM, MISC, etc. |

For more validator error codes → references/tools.md