Brain Imaging Data Structure (BIDS)

BIDS is a community-driven standard for naming and organizing neuroimaging and associated data, designed to facilitate sharing, collaboration, and reproducibility in neuroscience research. There is very detailed documentation in their website (see the BIDS Getting Started page). BIDS has a very active community. Besides the BIDS specification there is a BIDS ecosystem of associated tools (e.g., to validate you follow the specifications). Most analysis software for neuroimaging includes features and documentation for working with BIDS formatted data.

Note: ALL links provided in this document are to the ‘official’ BIDs documentation.

Check the following documentation highlights and the Section 2 with a workflow for getting started.

1 BIDS documentation highlights

1.1 Data folder structure

Check that the hierarchical folder structure and naming conventions are followed. Data must be arranged in a hierarchical folder structure. The four main levels described in the BIDS Folders Guide are:

🗀 project
 ├──🗀 subject         
     ├── 🗀 session (if applicable)
          ├── 🗀 datatype

1.2 Names

Name the folders as described in BIDS Folders Guide. E.g., sub-<participant label>, ses-<session label> and eeg for data type (see more data type labels in the Guide )

Although the subdirectories should be named according to BIDS, the individual data file names may be determined by the specific application used when acquiring or processing the data.

Details about filenaming principles and specifications are provided here.

An example of the template provided by BIDS for an EEG participant’s folder is the following:

sub-<label>/
    [ses-<label>/]
        eeg/
            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_eeg.<extension>
            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_eeg.json
            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_events.json
            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_events.tsv
            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_physio.json
            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_physio.tsv.gz
            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_stim.json
            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_stim.tsv.gz

1.3 Files types

The main file types in BIDS are:

JSON metadata

.json metadata files with key:value metadata They are placed at multiple levels. See some code examples to create .json files here are examples from the bids-example page.

Example of a JSON at a data set level at folder eeg_face13 /dataset_description.json

{
    "Name": "faceFO",
    "License": "ODbL (https://opendatacommons.org/licenses/odbl/summary/)",
    "Authors": [
        "James A. Desjardins",
        "Sidney J. Segalowitz"
    ],
    "HowToAcknowledge": "Desjardins, J. A., & Segalowitz, S. J. (2013). Deconstructing the early visual electrocortical responses to face and house stimuli. Journal of Vision, 13(5), 22-22.",
    "Funding": [
        "NSERC funding to Sidney Segalowitz"
    ],
    "ReferencesAndLinks": [
        "http://jov.arvojournals.org/article.aspx?articleid=2121634"
    ],
    "DatasetDOI": "10.1167/13.5.22",
    "BIDSVersion": "1.1.1"
}

Example of a JSON at the level of subject recording: eeg_face13/sub-003/eeg/sub-003_task-faceFO_eeg.json

    {
        "TaskName": "faceFO",
        "TaskDescription": "Visual presentation of oval cropped face and house images both upright and inverted. Rare left or right half oval checkerboards were presetned as targets for keypress response.",
        "InstitutionName": "Brock University",
        "InstitutionAddress": "500 Glenridge Ave, St.Catharines, Ontario",
        "EOGChannelCount": 7,
        "EMGChannelCount": 0,
        "MiscChannelCount": 128,
        "TriggerChannelCount": 0,
        "PowerLineFrequency": 60,
        "EEGPlacementScheme": "Custom equidistant 128 channel BioSemi montage established in coordination with Judith Schedden McMaster Univertisy",
        "Manufacturer": "BioSemi",
        "ManufacturersModelName": "ActiveTwo",
        "HardwareFilters": "n/a",
        "SoftwareFilters": "n/a",
        "SoftwareVersions": "NI ActiView 532-Lores",
        "CapManufacturer": "ElectroCap International",
        "CapManufacturersModelName": "10032",
        "EEGChannelCount": 0,
        "EEGReference": "common",
        "RecordingType": "continuous",
        "RecordingDuration": 2265,
        "SamplingFrequency": 512,
        "ECGChannelCount": 0
    }

Tables with metadata

Tab-separated value .tsvfiles. E.g., with electrode locations or events. They may be accompanied by a JSON file. See tabular files in BIDS documentation.

Data files

Raw data files

BIDS has methods-specific format recommendations for each type of data (fmri, eeg., meg, etc.). See for example the details about EEG files.

Derivatives

Derivatives are outputs of preprocessing pipelines, they involve data and metadata sufficient for reuse any subsequent processing or analysis. Because processing and analysis approaches can always be developed, derivatives are never fully specified, but BIDS-style conventions for these files are recommended. See details in the Tour of BIDS Derivative and the more advanced page in the specification of derivatives.

2 Workflow for getting started

BIDS can be overwhelming but Each step counts. BIDS cannot specify all possible scenarios, but try as much as possible to follow the BIDS specifications when possible or at least follow a BIDS style structuring as much as possible

Plan and document folder structure, folder names and filenaming convention based on BIDS as soon as possible, preferably before starting data collection
- Start sketching how the folder tree of raw data will look
- Write down the naming scheme of raw data file names
- Think about the derivatives (e.g., preprocessing) files. This might change as you run preprocessing pipelines. Update your documentation when needed.
Check what tabular metadata files (.tsv) you need e.g., electrde coordinates, events.
- Write a script to save the information required into .tsv format
What structured metadata (.json) files are required?
- Define the fields in the file in a template, as text, JSON or in a table.
- Write code to produce JSON files.
- Probably easier to start setting up one JSON ‘data set description’ file that will describe all data.
- Then move into subject / recording specific .JSON files.

Note

Contact if you need help automating the JSON file generation or you have other questions about how to apply BIDS to your data.

--- title: "Brain Imaging Data Structure (BIDS) " subtitle: 'Minimal steps to get started' date-modified: last-modified title-block-banner: true author: - name: LiRI Data Stewards - name: | [services@linguistik.uzh.ch](mailto:services@linguistik.uzh.ch) #tbl-colwidths: [25,75] number-sections: true number-depth: 3 format: html: embed-resources: true toc: true toc-depth: 4 #monobackgroundcolor: rgb(255 255 128 / 0.6) code-tools: true docx: default markdown: default pdf: keep-tex: true toc: true --- BIDS is a community-driven standard for naming and organizing neuroimaging and associated data, designed to facilitate sharing, collaboration, and reproducibility in neuroscience research. There is very detailed documentation in their website (see the [BIDS Getting Started page](https://bids.neuroimaging.io/getting_started/index.html)). BIDS has a very active community. Besides the [BIDS specification](https://bids-specification.readthedocs.io/en/stable/#the-brain-imaging-data-structure) there is a [BIDS ecosystem](https://bids.neuroimaging.io/#specification-vs-ecosystem) of associated tools (e.g., to validate you follow the specifications). Most analysis software for neuroimaging includes features and documentation for working with BIDS formatted data. Note: ALL links provided in this document are to the 'official' BIDs documentation. Check the following documentation highlights and the @sec-workflows with a workflow for getting started. ## BIDS documentation highlights ### Data folder structure Check that the hierarchical folder structure and naming conventions are followed. Data must be arranged in a hierarchical folder structure. The four main levels described in the [BIDS Folders Guide](https://bids.neuroimaging.io/getting_started/folders_and_files/folders.html) are: ``` yaml 🗀 project ├──🗀 subject ├── 🗀 session (if applicable) ├── 🗀 datatype ``` ### Names Name the folders as described in [BIDS Folders Guide](https://bids.neuroimaging.io/getting_started/folders_and_files/folders.html). E.g., `sub-<participant label>`, `ses-<session label>` and `eeg` for data type (see more data type labels in the [Guide](https://bids.neuroimaging.io/getting_started/folders_and_files/folders.html) ) Although the subdirectories should be named according to BIDS, the individual data file names may be determined by the specific application used when acquiring or processing the data. Details about filenaming principles and specifications are provided [here](https://bids-specification.readthedocs.io/en/stable/common-principles.html#filenames). An example of the [template](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/electroencephalography.html) provided by BIDS for an EEG participant's folder is the following: ```yaml sub-<label>/ [ses-<label>/] eeg/ sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_eeg.<extension> sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_eeg.json sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_events.json sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_events.tsv sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_physio.json sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_physio.tsv.gz sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_stim.json sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_stim.tsv.gz ``` ### Files types The main [file types in BIDS](https://bids.neuroimaging.io/getting_started/folders_and_files/files.html) are: #### JSON metadata `.json` metadata files with `key:value` metadata They are placed at multiple levels. See some code examples to create .json files [here](https://bids.neuroimaging.io/getting_started/folders_and_files/metadata/json.html) are examples from the [bids-example page](https://github.com/bids-standard/bids-examples/blob/master/eeg_face13). Example of a JSON at a data set level at folder `eeg_face13 /dataset_description.json` ``` json { "Name": "faceFO", "License": "ODbL (https://opendatacommons.org/licenses/odbl/summary/)", "Authors": [ "James A. Desjardins", "Sidney J. Segalowitz" ], "HowToAcknowledge": "Desjardins, J. A., & Segalowitz, S. J. (2013). Deconstructing the early visual electrocortical responses to face and house stimuli. Journal of Vision, 13(5), 22-22.", "Funding": [ "NSERC funding to Sidney Segalowitz" ], "ReferencesAndLinks": [ "http://jov.arvojournals.org/article.aspx?articleid=2121634" ], "DatasetDOI": "10.1167/13.5.22", "BIDSVersion": "1.1.1" } ``` Example of a JSON at the level of subject recording: `eeg_face13/sub-003/eeg/sub-003_task-faceFO_eeg.json` ``` json { "TaskName": "faceFO", "TaskDescription": "Visual presentation of oval cropped face and house images both upright and inverted. Rare left or right half oval checkerboards were presetned as targets for keypress response.", "InstitutionName": "Brock University", "InstitutionAddress": "500 Glenridge Ave, St.Catharines, Ontario", "EOGChannelCount": 7, "EMGChannelCount": 0, "MiscChannelCount": 128, "TriggerChannelCount": 0, "PowerLineFrequency": 60, "EEGPlacementScheme": "Custom equidistant 128 channel BioSemi montage established in coordination with Judith Schedden McMaster Univertisy", "Manufacturer": "BioSemi", "ManufacturersModelName": "ActiveTwo", "HardwareFilters": "n/a", "SoftwareFilters": "n/a", "SoftwareVersions": "NI ActiView 532-Lores", "CapManufacturer": "ElectroCap International", "CapManufacturersModelName": "10032", "EEGChannelCount": 0, "EEGReference": "common", "RecordingType": "continuous", "RecordingDuration": 2265, "SamplingFrequency": 512, "ECGChannelCount": 0 } ``` #### Tables with metadata Tab-separated value `.tsv`files. E.g., with electrode locations or events. They may be accompanied by a JSON file. See [tabular files](https://bids-specification.readthedocs.io/en/stable/common-principles.html#tabular-files) in BIDS documentation. #### Data files ##### Raw data files BIDS has methods-specific format recommendations for each type of data (fmri, eeg., meg, etc.). See for example the details about [EEG](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/electroencephalography.html#electroencephalography) files. ##### Derivatives Derivatives are outputs of preprocessing pipelines, they involve data and metadata sufficient for reuse any subsequent processing or analysis. Because processing and analysis approaches can always be developed, derivatives are never fully specified, but BIDS-style conventions for these files are recommended. See details in the [Tour of BIDS Derivative](https://bids.neuroimaging.io/getting_started/folders_and_files/derivatives.html#tour-of-a-bids-derivative) and the more advanced page in the [specification of derivatives](https://bids-specification.readthedocs.io/en/stable/derivatives/introduction.html). ## Workflow for getting started {#sec-workflows} BIDS can be overwhelming but *Each step counts*. BIDS cannot specify all possible scenarios, but try as much as possible to follow the BIDS specifications when possible or at least follow a BIDS style structuring as much as possible - [ ] *Plan and document* **folder structure, folder names** and **filenaming convention** based on BIDS as soon as possible, preferably before starting data collection - Start sketching how the folder tree of raw data will look - Write down the naming scheme of raw data file names - Think about the derivatives (e.g., preprocessing) files. This might change as you run preprocessing pipelines. Update your documentation when needed. - [ ] Check what **tabular metadata files (.tsv)** you need e.g., electrde coordinates, events. - Write a script to save the information required into .tsv format - [ ] What **structured metadata (.json)** files are required? - Define the fields in the file in a template, as text, JSON or in a table. - Write code to produce JSON files. - Probably easier to start setting up one JSON 'data set description' file that will describe all data. - Then move into subject / recording specific `.JSON` files. ::: {.callout-note collapse="false" } Contact [services\@linguistik.uzh.ch](mailto:services@linguistik.uzh.ch) if you need help automating the JSON file generation or you have other questions about how to apply BIDS to your data. :::