Webinar: BIDS Templating
Introduction
Learn more about the BIDS standard, how to upload your data in to Flywheel using BIDS, and an example of how to extend the default BIDS specification. Follow along with the webinar using the interactive Jupyter notebook.
Examples to Follow in the Webinar
- BIDS 101
- Flywheel BIDS Overview
- Demo: Flywheel BIDS Curation Overview in the UI
- BIDS Curation Gear
- Project Curation Template Components
- Demo: Extend the BIDS template JSON file
Instruction Steps
1. BIDS 101
- Brain Imaging Data Structure (BIDS): A filename convention and directory layout for organizing and describing neuroimaging datasets.
Tip
Download a PDF of the latest BIDS specification supported by Flywheel and take an hour to read through, paying particular attention to the Common Principles section.
Example of a BIDS formatted dataset file tree
BIDS Building Blocks
- type - a functional group of different types of data.
- func, dwi, fmap, anat, meg, eeg, ieeg, beh
<index>
- a numeric value, possibly prefixed with arbitrary number of 0s for consistent indentation- e.g.,
01
inrun-01
followingrun-<index>
specification
- e.g.,
<label>
- an alphanumeric value- e.g.,
rest
intask-rest
followingtask-<label>
specification
- e.g.,
- suffix - an alphanumeric value, located after the
key-value
pairs and before the file extension - extension - a portion of the filename after the left-most period (.) preceded by any other alphanumeric
- e.g.,
.nii.gz
- e.g.,
Filename Structure
The BIDS filename convention consists of a chain of entities or key-value
pairs, a suffix and an extension.
One entitysub-<label>
corresponds to the subject entity because it has the sub-
" key" and <label>
"value", where <label>
would in a real data file correspond to a unique identifier of that subject, such as 42
. For example, sub-42
.
Anatomy imaging data
sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>]_<modality_label>.nii[.gz]
- entities -
sub-<label>
,ses-<label>
,acq-<label>
, etc.- Brackets [ ] indicate the entity is optional
- type - anat
- suffix -
<modality_label>
- Options: T1w, T2w, T1rho, T1map, T2map, T2star, FLAIR, FLASH, PD, PDmap, PDT2, inplaneT1, inplaceT2, angio
-
extension -
.nii.gz
-
Fill in the above, along with
<index>
and<label>
for each entity to get the filename:sub-<label>
->sub-42
acq-<label>
->acq-mprage
<modality_label>
->T1w
.nii[.gz]
->.nii.gz
-
Stitch together with
_
(underscores)sub-<label>_acq-<label>_<modality_label>.nii[.gz]
->sub-42_acq-mprage_T1w.nii.gz
-
OHBM 2020: Automating BIDS Workflow with Flywheel
- Talk on BIDS support in Flywheel, including import, curate, export, & analyze
- BIDS Overview
- Documentation introducing BIDS in Flywheel
Curation is the process of producing metadata on an existing Flywheel Project so the project can then be utilized as a BIDS formatted dataset. BIDS metadata is stored in the open-ended info.BIDS attribute that is associated on every Project, Session, Acquisition, Analysis, and File Container in the Flywheel system.
2. Flywheel BIDS Overview
- Curation: The process of producing BIDS metadata that maps your Flywheel Project to the BIDS standard
- Metadata: Stored in the info.BIDS attribute on each Container
- Template: A JSON file used during curation to populate metadata
3. Demo: Flywheel BIDS Curation Overview in the UI
Flywheel | BIDS |
---|---|
4. BIDS Curation Gear
- Input:
- Project Curation Template
- Process:
- Producing BIDS metadata that maps your Flywheel Project to the BIDS standard. I.e., given a Flywheel Container, fill in and stitch together the BIDS building blocks.
- Output:
info.BIDS.<METADATA>
Flywheel BIDS Curation Overview
BIDS curation in Flywheel is built on a JSON template that dictates a metadata mapping. The JSON template provides flexibility for adapting to the continuously evolving standards of BIDS; however, this process involves project-specific modifications in order to ensure the process runs smoothly. The Flywheel implementation of BIDS empowers users to achieve BIDS compliant datasets; however, with the flexibility and constantly changing specifications, there will inevitably be a setup cost. With Flywheel, this setup cost is the construction of a Project Curation Template.
Project Curation Templates Overview
There is one default template maintained in the bids-client
repo, which is called by the curate-bids
Gear if no project-template.json
is provided as an attachment on the project. Any project can have a project-template.json
that provides the specific metadata mapping needed for BIDS curation on that project. This project-template.json
may be reformulated in its entirety or extend the default template. In any of these cases, when referring to the BIDS curation process, these templates are referred to as the Project Curation JSON Templates.
Definition:
- Project Curation Template: the master template defining the BIDS standard for the project and used by the curate-bids Gear for BIDS metadata mapping.
Tip
Some knowledge of JSON Schemas and regular expressions will be useful.
Default Project Curation Template
bids-v1.json
is stored in thebids-client
repository which contains the core functionality of all Flywheel BIDS (i.e., import, curation, export)curate-bids
Gear will default to this template if:- A custom template is not provided as project attachment
- The custom template is not JSON Schema compliant
Custom Project Curation Templates
- Attached at the project-level
- Name of file must end in project-template.json
e.g., custom-project-template.json
Recommended Approaches
- Automating BIDS Curation achieved via ReproIn Project Curation Template
- ReproIn is part of the ReproNim Center suite of tools and frameworks
- ReproIn repository -> A setup for automatic generation of shareable, version-controlled BIDS datasets from MR scanners
- ReproNim -> A center for reproducible neuroimaging computation
- Extend
bids-v1.json
- the default Project Curation Template- Modify only components of the Template that are relevant for your project
Tip
Check the log for curate-bids
Gear to make sure your Custom Project Curation Template was selected.
Default Template | Custom Metadata |
---|---|
5. Project Curation Template Components
Within the Project Curation Template are sections, most commonly, definitions and rules, along with other, more optional, sections (e.g., initializers, resolvers, etc.).
In [1]:
In [2]:
In [3]:
Within the definitions are Container Template definitions, which refer to the pattern template applied to a particular Flywheel Container.
Definition:
- Container Template: a portion of the Project Curation Template that dictates the information needed to structure one container, such as an anatomy file.
In [4]:
with open('assets/container_template_example.json') as jfile:
container_template = json.load(jfile)
In [5]:
- BIDS Metadata: the set of metadata attached to a Flywheel Container (e.g., file, acquisition, session) that contains information for the BIDS standard stored as
info.BIDS.<METADATA>
.- Defined via the Project Curation Template.
Container Template | BIDS Metadata |
---|---|
To apply the Container Template definitions, the rules are applied as follows:
- Determine if an object encountered should have that Container Template applied ( i.e., the where clause of the rule definition)
- If so, initialize the
<label>
and<index>
sections for the chain of entities, orkey-value
pairs, relevant to the data type of the object encountered to capture the BIDS metadata necessary to stitch together the BIDS filename.
In [6]:
In [7]:
6. Demo: Extend BIDS template
In [8]:
Debugging
- Check your Project Curation Template with a JSON linter to ensure proper syntax. For example: https://jsoneditoronline.org/
- Check your regular expressions against the strings you are parsing (e.g., acquisition.label). For example: https://regex101.com/
In [9]: