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, which allows you to try out examples directly in your browser.
3:04 – BIDS 101
10:42 – Flywheel BIDS Overview
12:56 – Demo: Flywheel BIDS Curation Overview in the UI
16:20 – BIDS Curation Gear
21:40 – Project Curation Template Components
31:48 – Demo: Extend bids-v1.json
Follow along with the examples in the webinar
1. BIDS 101
Brain Imaging Data Structure (BIDS):
A filename convention and directory layout for organizing and describing neuroimaging datasets.
⏱ PROTIP ⏱: Download a PDF of the latest BIDS specification and take an hour to read through, paying particular attention to the Common Principles section.
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
<label> - an alphanumeric value
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
The BIDS filename convention consists of a chain of entities or
key-value pairs, a suffix and an extension.
sub-<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,
- Brackets [ ] indicate the entity is optional
type - anat
Options: T1w, T2w, T1rho, T1map, T2map, T2star, FLAIR, FLASH, PD, PDmap, PDT2, inplaneT1, inplaceT2, angio
Fill in the above, along with
<label>for each entity to get the filename:
Stitch together with
- Talk on BIDS support in Flywheel, including import, curate, export, & analyze
- 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.
The process of producing BIDS metadata that maps your Flywheel Project to the BIDS standard
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
4. BIDS Curation Gear
Project Curation Template
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
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.
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.
Project Curation Template: the master template defining the BIDS standard for the project and used by the curate-bids Gear for BIDS metadata mapping.
⏱ PROTIP ⏱: Some knowledge of JSON Schemas and regular expressions will be useful.
bids-v1.jsonis stored in the
bids-clientrepository which contains the core functionality of all FLywheel BIDS (i.e., import, curation, export)
curate-bidsGear will default to this template if:
A custom template is not provided as project attachment
The custom template is not JSON Schema compliant
Attached at the project-level
Name of file must end in project-template.json
Automating BIDS Curation achieved via ReproIn Project Curation Template
bids-v1.json- the default Project Curation Template
Modify only components of the Template that are relevant for your project
⏱ PROTIP ⏱: Check the log for
curate-bids Gear to make sure your Custom Project Curation Template was selected.
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.).
with open('assets/bids-v1.json') as jfile: bids_v1_template=json.load(jfile)
Within the definitions are Container Template definitions, which refer to the pattern template applied to a particular Flywheel Container.
Container Template: a portion of the Project Curation Template that dictates the information needed to structure one container, such as an anatomy file.
with open('assets/container_template_example.json') as jfile:
container_template = json.load(jfile)
bids_v1_template = json.load(jfile)
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.
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
<index>sections for the chain of entities, or
key-valuepairs, relevant to the data type of the object encountered to capture the BIDS metadata necessary to stitch together the BIDS filename.
6. Demo: Extend bids-v1.json
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/