Differences Between the Flywheel and BIDS Hierarchy
Introduction
The BIDS specification Common Principles defines a set of terms that are often used interchangeably with terms used to describe the Flywheel hierarchy. However, several of these terms are semantically overloaded, which creates confusion when interacting with the Flywheel + BIDS toolset.
This article describes the difference between how data is organized in Flywheel and how data is organized in BIDS.
Hierarchy Overview
Instruction Steps
Hierarchy Differences
| Term | Flywheel ← Translation → BIDS | Implications |
| Project or Dataset | Under the Information tab in your Flywheel Instance UI, you’ll find Custom Information (Figure 1A), which is where the dataset_description.json file is defined as info.BIDS metadata at the project-level. There are also Attachments (Figure 1B), which correspond to the remaining modality agnostic files of the BIDS specification. | Flywheel BIDS Curation captures the minimum set of common requirements at the project-level due to the specific nature of the data. It is recommended that the User complete this information according to the BIDS specification during the project setup stage. |
| Subject | Under the Subject tab in your Flywheel Instance UI, you’ll find a Label for the subject (Figure 2A). Using the Flywheel Default Project Curation Template, you can either use sub-XYZ or XYZ, where XYZ is an alphanumeric value, as the Label to achieve the proper sub-<label> entity expected for each file in the Flywheel Subject container. If your Label has an alternative pattern, such as patient-XXX, you’ll need to modify the Project Curation Template to parse that Label to meet the BIDS specification because the Default will result in a sub-<label> entity of sub-patient-XYZ, which is not BIDS compliant. | sub-<label> is always required on all files in the BIDS Dataset |
| Session | Under the Session tab in your Flywheel Instance UI, you’ll find a Label for the session. Using the Flywheel Default Project Curation Template, you can either use ses-XYZ or XYZ, where XYZ is an alphanumeric value, as the Label to achieve the proper ses-<label> entity expected for each file in the Flywheel Session container. If your Label has an alternative pattern, such as scan-XYZ, you’ll need to modify the Project Curation Template to parse that Label to meet the BIDS specification because the Default will result in a ses-<label> entity of ses-scan-XYZ, which is not BIDS compliant. | The BIDS specification assumes a minimum set of entities to ensure the uniqueness of filenames across the BIDS Dataset. This means some entities are required in some cases, while not in others. Most notably is the ses-<label> entity. If there are multiple sessions for a subject, then the ses-<label> entity is required; otherwise, it’s optional. However, Flywheel requires sessions to have a Session Label. Therefore, in order to adapt our Flywheel Project to a BIDS Dataset, we modify the Project Curation Template to ignore the Session Label. A demonstration of this is found below in the Remove Session Label section. |
| Acquisition | Under the Acquisition tab in your Flywheel Instance UI, you’ll find a display of acquisitions for a selected session (Figure 3). Each acquisition has an Acquisition Label, and files are sorted by their Acquisition Label. This Acquisition Label is often extracted from the SeriesDescription DICOM Tag on data import into Flywheel. However, this field is customizable on data import and mutable, making it the most commonly used data point for the translation from Flywheel to the BIDS specification. As a result, you’ll often see acquisition.label in the Project Curation Template, frequently used with a regular expression to parse out specific information for an entity’s label. For example, func_task-nback can be parsed to capture the label=nback for the task- | The BIDS specification under the Common Principles section indicates a data acquisition is a block of data acquired with a particular protocol. And while Flywheel considers an acquisition in a similar manner, there is a very important distinction when it comes to the acquisition entity (i.e., acq- |
| As an aside, BIDS sorts a subject’s acquisitions based on data type, which is shown with BIDS View in Figure 4. The BIDS specification currently defines eight data types: func, dwi, fmap, anat, meg, eeg, ieeg, and beh. | ||
| Modality | In the Flywheel file metadata (i.e., the file’s info object), there is a section with Modality defined with subsections that indicate more specifics (Figure 5A). Often, this information is used to match the file with the correct BIDS specification in the Project Curation Template rules section. These are accessed most commonly with file.classification.Intent and file.classification.Measurement. | The BIDS specification defines the modality as the category of brain data in the file, such as T1w (Figure 5B) or bold. When applicable, the modality is indicated in the suffix of the filename either as mod- |
Figure 1
Figure 2
Figure 3
Figure 4
Figure 5
Remove Session Label
To remove the ses-<label> entity from the Flywheel Project, we extend the Flywheel Default Project Curation Template to ignore the Session Label required on the Flywheel Session Container, as shown in the following code block.
{
"extends": "bids-v1",
"description": "Remove ses-<label> entity across the project.",
"definitions": {
"session": {
"description": "BIDS session template",
"properties": {
"Label": {
"type": "string",
"title": "Label",
"default": "",
"pattern": "^[0-9]+$"
},
"Subject": {
"type": "string",
"title": "Subject Code",
"default": "",
"auto_update": "<subject.code>"
}
},
"required": []
}
},
"exclude_rules": [
"bids_session"
],
"rules": [
{
"id": "bids_session",
"template": "session",
"where": {
"container_type": "session"
},
"initialize": {
"Label": {
"session.label": ""
}
}
}
]
}
For the curate-bids Gear to implement this Custom Project Curation Template, we save it to the project-level attachments with a filename that ends with project-template.json. For example, see Figure 1B where the above code block was attached to the project with the filename remove-session-extension-project-template.json.