Term Differences of 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.
Instruction Steps
Hierarchy Overview
Hierarchy Differences
BIDS JSON Sidecars == Flywheel BIDS Metadata, which is stored in info.BIDS on each container in the Flywheel Hierarchy. Note: this means that any information required in a .json file should be located in the associated file’s info object.
| 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- | sub- |
| 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- | 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- |
| 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-
{
"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 Gearto 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.