Skip to content

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

  1. Determine which upload option is most appropriate for the project.

    Legacy option utilizing metadata, but no JSON sidecar:
    Metadata option

    Modern option using dcm2niix sidecar output, but no metadata: Sidecar file
    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.

  2. 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

  1. Download to a local machine with Jupyter installed.
  2. Open a terminal and launch jupyter notebook.
  3. Navigate to the download location and open the notebook.
  4. Modify all the indicated variables, including API key and project hash.
  5. 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:
hc.curate_project(fw.get(project_hash), update_metadata=True, 
make_sidecar=False, report_only=False)
  • To convert metadata to JSON sidecars, use:
hc.curate_project(fw.get(project_hash), update_metadata=False, 
make_sidecar=True, report_only=False)

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.

  1. Copy the first code cell of the notebook into an editor (e.g., vsCode).

  2. To convert JSON sidecars to metadata, modify line 166 to:

    def curate_acquisition(self, acquisition: flywheel.Acquisition, 
update_metadata=True, make_sidecar=False, report_only=False)

  3. To convert metadata to JSON sidecars, modify line 166 to:

    def curate_acquisition(self, acquisition: flywheel.Acquisition, 
update_metadata=False, make_sidecar=True, report_only=False)

  4. Save and upload the script to the project
    upload script

  5. Select your project (or subject or session).

  6. Click "Run Gear" and select the Hierarchy Curator.
    select gear

  7. Use the script uploaded to the project as the input for the "curator" field.
    input selection

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.