Storing BIDS Sidecars
Introduction
Flywheel has updated handling of dcm2niix
output. The JSON sidecar data is now uploaded alongside the appropriate NIfTI file. Previously, the sidecar data was stored in metadata on the NIfTI file.
This change was introduced so that the sidecar data is simple to find and in an expected location (rather than buried inside metadata). Additionally, the change keeps the practices aligned with newer versions of the metadata importer gear and reduces computational time for indexing and searching.
Features
Keeping sidecar data in JSON sidecar files instead of storing in metadata improves parity with common practice and allows seamless integration with BIDS apps.
Problems and Resolutions
This shift has been introduced in version 18.1 of the CLI. Files uploaded via the CLI using a previous version with fw ingest bids
can be modernized by stepping through this Jupyter notebook or using the first code cell in the notebook as the script input for the Hierarchy Curator gear. Conversely, if one wishes to keep the sidecar data as metadata in file.info
on acquisitions, the same code may be used to modify newer uploads to match existing project data. Details follow below in the instruction steps for either the Jupyter notebook or Hierarchy Curator script.
Instruction Steps
-
Determine which upload option is most appropriate for the project.
Legacy option utilizing metadata, but no JSON sidecar:
Modern option using
dcm2niix
sidecar output, but no metadata:
- The information stored in under “BIDS” in this picture contains strings that include the BIDS folder, filename, etc. which is used by BIDS export when saving this file in BIDS format, but does not contain sidecar data. The
info.BIDS
field is set when ingesting from the CLI or by the BIDS curation gear.
- The information stored in under “BIDS” in this picture contains strings that include the BIDS folder, filename, etc. which is used by BIDS export when saving this file in BIDS format, but does not contain sidecar data. The
-
Convert any files of the opposite upload option to the selected option.
Note: BIDS export will create the appropriate sidecars in either case.
The conversion can be accomplished either by (a) stepping through a Jupyter notebook or (b) using the code in notebook as the input script for the Hierarchy Curator gear.
Jupyter Notebook
Download this Jupyter notebook, modify, and step through
- Download to a local machine with Jupyter installed.
- Open a terminal and launch
jupyter notebook
. - Navigate to the download location and open the notebook.
- Modify all the indicated variables, including API key and project hash.
- Run the cells to modify the project real-time (hit refresh on your Flywheel browser instance to see the changes).
- To convert JSON sidecars to metadata, use:
- To convert metadata to JSON sidecars, use:
Hierarchy Curator
The first cell of the notebook contains the code for the Hierarchy Curator. These steps walk through how to modify the code and upload as a script for the Hierarchy Curator gear.
- Copy the first code cell of the notebook into an editor (e.g., vsCode).
-
To convert JSON sidecars to metadata, modify line 166 to:
-
To convert metadata to JSON sidecars, modify line 166 to:
-
Save and upload the script to the project
-
Select your project (or subject or session).
-
Click "Run Gear" and select the Hierarchy Curator.
-
Use the script uploaded to the project as the input for the "curator" field.
Resources
FAQs
Which option is recommended?
- Flywheel will be using the JSON sidecars and not storing sidecar data in NIfTI metadata going forward; however, the BIDS export code, BIDS curation gear, and all BIDS Apps are backwards compatible so everything will work as expected in either case.