with one click
bids
// BIDS (Brain Imaging Data Structure) conventions for organizing neuroimaging datasets. Use when creating, reading, validating, or navigating BIDS-compliant directory trees, file names, metadata sidecars, or derivatives.
// BIDS (Brain Imaging Data Structure) conventions for organizing neuroimaging datasets. Use when creating, reading, validating, or navigating BIDS-compliant directory trees, file names, metadata sidecars, or derivatives.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | bids |
| description | BIDS (Brain Imaging Data Structure) conventions for organizing neuroimaging datasets. Use when creating, reading, validating, or navigating BIDS-compliant directory trees, file names, metadata sidecars, or derivatives. |
| user-invocable | false |
dataset/
āāā dataset_description.json # REQUIRED
āāā README[.md|.rst|.txt] # REQUIRED
āāā participants.tsv # RECOMMENDED
āāā participants.json # RECOMMENDED (column descriptions)
āāā CHANGES # OPTIONAL
āāā LICENSE # OPTIONAL
āāā CITATION.cff # OPTIONAL
āāā .bidsignore # OPTIONAL (like .gitignore for validator)
āāā code/ # Scripts and analysis code
āāā stimuli/ # Stimulus files
āāā sourcedata/ # Pre-conversion source files (DICOM, etc.)
āāā phenotype/ # Participant-level measures (shared, not per-subject)
āāā derivatives/ # Processed outputs
ā āāā <pipeline-name>/
ā āāā dataset_description.json # REQUIRED per derivative
ā āāā sub-<label>/...
āāā sub-<label>/
āāā [ses-<label>/]
āāā anat/ # Anatomical MRI
āāā func/ # Functional MRI
āāā dwi/ # Diffusion
āāā fmap/ # Field maps
āāā perf/ # Perfusion / ASL
āāā eeg/ # EEG
āāā meg/ # MEG
āāā ieeg/ # Intracranial EEG
āāā beh/ # Behavioral
āāā pet/ # PET
āāā ... # Other BIDS datatypes
.-prefixed) are reserved for system use and excluded from validation.phenotype/ lives at dataset root (not per-subject).sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_run-<index>][_desc-<label>]_<suffix>.<extension>
+). No spaces.run-): non-negative integers, optionally zero-padded (run-01).sub-s1 and sub-S1 CANNOT coexist.| # | Entity | Key | Value Type | Example |
|---|---|---|---|---|
| 1 | Subject | sub- | label | sub-01 |
| 2 | Session | ses- | label | ses-pre |
| 3 | Task | task- | label | task-rest |
| 4 | Acquisition | acq- | label | acq-highres |
| 5 | Run | run- | index | run-02 |
| 6 | Echo | echo- | index | echo-1 |
| 7 | Part | part- | label | part-mag |
| 8 | Description | desc- | label | desc-preproc |
| 9 | Space | space- | label | space-MNI152NLin2009cAsym |
Full entity ordering is in the BIDS Entities Appendix.
| Datatype | Suffixes |
|---|---|
anat/ | T1w, T2w, FLAIR, T1map, T2map, T2starmap, PDw |
func/ | bold, sbref |
dwi/ | dwi, sbref |
fmap/ | epi, magnitude, phase, phasediff |
eeg/ | eeg, events, channels, electrodes, coordsystem, photo |
perf/ | asl, m0scan |
Every data file can have a companion .json sidecar with the same base name:
sub-01_ses-01_task-rest_bold.nii.gz
sub-01_ses-01_task-rest_bold.json ā metadata sidecar
Sidecars can live at ANY directory level. Lower levels override higher levels (key by key for JSON, full replacement for TSV):
task-rest_bold.json ā dataset-wide defaults
sub-01/func/sub-01_task-rest_bold.json ā subject-specific overrides
A sidecar applies to a data file if:
n/a. (dot)snake_case, lowercase first letterparticipant_id age sex condition
sub-01 25 M ACTIVE
sub-02 30 F SHAM
participant_id column is REQUIRED (values like sub-01)participants.json describes columns with LongName, Description, Levels, Unitsonset duration trial_type
0.0 0.5 go
2.3 0.5 stop
onset (seconds from run start) and duration are REQUIRED columnsRequired columns: name, type, units
Optional: sampling_frequency, reference, low_cutoff, high_cutoff, notch, status, status_description
Valid EEG channel types: EEG, EOG, ECG, EMG, VEOG, HEOG, MISC, REF, TRIG, STIM
Required columns: name, x, y, z
Optional: type, material, impedance
Requires companion *_coordsystem.json with EEGCoordinateSystem, EEGCoordinateUnits.
{
"Name": "My Study",
"BIDSVersion": "1.9.0"
}
{
"Name": "My Study",
"BIDSVersion": "1.9.0",
"DatasetType": "raw",
"License": "CC0",
"Authors": ["Last, First", "Last2, First2"],
"Funding": ["NIH R01-XX-XXXXX"],
"DatasetDOI": "doi:10.xxxx/xxxxx"
}
{
"Name": "My Pipeline Output",
"BIDSVersion": "1.9.0",
"DatasetType": "derivative",
"GeneratedBy": [
{
"Name": "my-pipeline",
"Version": "1.0.0",
"CodeURL": "https://github.com/org/pipeline"
}
],
"SourceDatasets": [
{
"URL": "file:///path/to/raw/dataset"
}
]
}
| Format | Extensions | Notes |
|---|---|---|
| BrainVision | .vhdr, .vmrk, .eeg | Recommended; triplet required |
| European Data Format | .edf | Single file; EDF+ OK |
| EEGLAB | .set (+ .fdt) | MATLAB format |
| Biosemi | .bdf | Single file; BDF+ OK |
*_eeg.json)| Field | Type | Example |
|---|---|---|
EEGReference | string | "FCz" or "average" |
SamplingFrequency | number | 512 |
PowerLineFrequency | number or "n/a" | 60 |
SoftwareFilters | object or "n/a" | {"Anti-aliasing": {"half-amplitude cutoff (Hz)": 500}} |
TaskName, EEGChannelCount, EOGChannelCount, ECGChannelCount, RecordingType ("continuous", "epoched", "discontinuous"), EpochLength, RecordingDuration, CapManufacturer, EEGGround, HardwareFilters, Manufacturer
electrodes.tsv)channels.tsv)RepetitionTime (or RepetitionTimeExcitation), EchoTimeTaskName, RepetitionTime, EchoTime; RECOMMENDED: SliceTiming, PhaseEncodingDirectionEchoTime, plus .bval/.bvec filesEchoTime, RepetitionTime, FlipAngleB0FieldIdentifier/B0FieldSource for linking to target scans.nii.gz (recommended) or .nii for imaging data.json sidecarderivatives/<pipeline-name>/
āāā dataset_description.json # DatasetType: "derivative"
āāā descriptions.tsv # OPTIONAL ā documents desc- labels
āāā sub-01/
āāā ses-01/
āāā func/
āāā sub-01_ses-01_task-rest_space-MNI152_desc-preproc_bold.nii.gz
āāā sub-01_ses-01_task-rest_space-MNI152_desc-preproc_bold.json
desc-<label> distinguishes processing variants of the same source.space-<label> indicates spatial reference (e.g., MNI152NLin2009cAsym, T1w, orig).bold, T1w, etc.).Sources field with BIDS URIs to input files.bids::<relative-path> # current dataset
bids:<dataset-name>:<relative-path> # named dataset (via DatasetLinks)
n/a or empty stringYYYY-MM-DDThh:mm:ss[.000000][Z|+hh:mm]
Example: 2009-06-15T13:45:30+01:00
Privacy: shift dates consistently per subject; set shifted year to 1925 or earlier.
Follow SI; use CMIXF-12 notation for prefixes:
uV (microvolts), mV (millivolts), Hz, mm, ms, oC (degrees Celsius)/ (even on Windows)When writing Python code for BIDS datasets:
from pathlib import Path
def bids_path(root, sub, ses=None, datatype="eeg", suffix="eeg",
ext=".set", task=None, acq=None, run=None, desc=None,
space=None, derivative=None):
"""Build a BIDS-compliant file path."""
sub = sub.removeprefix("sub-")
base = Path(root)
if derivative:
base = base / "derivatives" / derivative
base = base / f"sub-{sub}"
if ses:
ses = ses.removeprefix("ses-")
base = base / f"ses-{ses}"
base = base / datatype
# Entities in spec-defined order
parts = [f"sub-{sub}"]
if ses:
parts.append(f"ses-{ses}")
if task:
parts.append(f"task-{task}")
if acq:
parts.append(f"acq-{acq}")
if run is not None:
parts.append(f"run-{run}")
if desc:
parts.append(f"desc-{desc}")
if space:
parts.append(f"space-{space}")
parts.append(suffix)
return base / ("_".join(parts) + ext)
Use the BIDS Validator to check compliance:
# npm
npx bids-validator /path/to/dataset
# Docker
docker run -v /path/to/dataset:/data bids/validator /data
# Python
pip install bids-validator
Common validation pitfalls:
dataset_description.json