Logo Logo

BIDS Curation Tutorial Part 3: Running the BIDS Curation Gear

Instruction Steps

Now that we have prepared our data and converted the scans to NIfTI format, we can run the BIDS Curation gear. Flywheel currently supports BIDS version 1.8.0. However, templates can be extended to support later BIDS versions and BIDS Extension Proposals (BEPs).

Step 1: Run the BIDS Curation gear
Step 2: Review BIDS Curation log and project custom information
Step 3: Review BIDS curated acquisitions
Step 4: Review the BIDS Curation gear output csv files

Step 1: Run the BIDS Curation gear

The BIDS Curation gear, like all BIDS Application Gears, can be run at the session, subject, or project level of the Flywheel hierarchy. The key to running at one of these levels is to first navigate to the desired level and then find the right Run Gear or Run Analysis Gear button.

Users are encouraged to run the BIDS Curation Gear at the Project level, as the output summary csv files will contain all subjects and sessions. Running at either the session or subject level may mean having to parse the results of multiple output csv files to check for curation errors.

In the next few subsections, we will cover in detail how to run the BIDS Curation Gear at the project level from start to finish. We will then briefly describe how to run the gear at both the subject and session levels.

Curating a Project

To run the BIDS Curation gear on the entire project, select the Analyses tab at the top and click on the Run Analysis Gear button.
Then, search for BIDS Curation and select the desired version (usually latest). Since Flywheel has adopted the ReproIn naming convention as the new default, there is no need to select an input template file.
Click on the Configuration tab to make sure that the base_template is reproin. The save_sidecar_as_metadata option should currently default to auto. This option checks how BIDS JSON sidecar data is currently saved for the project and use that. For new projects, BIDS JSON sidecar data are now saved in JSON sidecar files. Older and/or on-going projects may have these data saved out in the Custom Information metadata fields. This config option also has the option to force how the BIDS JSON sidecar data are saved by selecting either yes or no. Once you are satisfied with the config options, click Run Gear.
Once the BIDS Curate Gear has finished running (you may need to refresh the page to check the status), click on the gear name in the list of analyses and click on the Gear Logs tab.
Scroll through the gear log to check for any error messages. You can also review how files were recognized (or not) and which rule was used to determine the BIDS information. The BIDS Curation Gear steps through the entire project hierarchy beginning at the project level. It first matches the project container using the " bids_project" rule and sets BIDS Custom Information on the project container.

Curating a Session

Click on the Session tab at the top and then select a specific session. Then click the Run Gear button and select Analysis Gear.
Follow the instructions above for "Curating a Project" for selecting the BIDS Curation Gear, running the gear with the default configurations, and checking the log file.

Curating a Subject

Select the Subject view button and then select a specific subject. Then navigate to the Analyses tab. Finally, click on the Run Analyses Gear button. It is easy to forget to select a subject. If you do, you'll be running the gear on the currently selected session.
Follow the instructions above for "Curating a Project" for selecting the BIDS Curation Gear, running the gear with the default configurations, and checking the log file.

Step 2: Review BIDS Curation project custom information

Let's see how the BIDS information looks for the project. Refresh the page and click the Information tab at the top. You can see BIDS under Custom Information.

Since the latest version of the BIDS Curation Gear now saves out the BIDS JSON sidecar data in JSON sidecar files, there is minimal custom information saved as metadata.

In the below screengrab, we can see that the Project was curated using the bids_project rule and that the JSON sidecar file data are saved in JSON sidecar files.

Scrolling down to Attachments, you will see the standard BIDS dataset_description.json and README.txt files.

If you hover on the right-hand side of each file and click on the three dots, a pull-down menu will appear allowing you to open and edit either or both files within the Flywheel UI.

Below we have opened the dataset_description.json file for editing:

Step 3: Review BIDS curated acquisitions

Review BIDS curation results for Dataset 1

From Sessions/Acquisitions tab, check out Info for nifti file(s):
Note that under BIDS in Custom Information only BIDS filename information is saved out as metadata. Scrollling down through the BIDS information, you will see a checkbox labeled valid. If this is checked, then the filename and organization should be considered valid by the BIDS validator. However, this valid does not reflect having run the BIDS validator on the project.
If we check one of the scout acquisition(s), we will see that there is no BIDS information. This means that these acquisitions were correctly ignored by BIDS Curate gear, because we updated the File Classifier results so that only Intent was Localizer.
We can also preview the overall organization of the BIDS directory from the Flywheel UI. From the three dot pull-down menu to the right of Run Gear button, you can toggle on/off a BIDS view to preview the BIDS directory structure and filenames.
From this view, we can quickly see that the one T1w acquisition was correctly named and added to the anat folder. Also, that all of the functional runs were correctly named and added to the func folder. Scrolling down to sourcedata would show that all of the dicom.zip files were added there. Scrolling down towards the bottom shows that all of the scout acquisitions were correctly categorized as non-BIDS.

Review BIDS curation results for Dataset 2

From Sessions/Acquisitions tab, check out Info for nifti file(s):
Note that under BIDS in Custom Information only BIDS filename information is saved out as metadata. For the first session, we can see that the optional BIDS filename parameter of Dir was set correctly. Similarly for the second session, we see that both Acq and Dir were both set correctly. Scrollling down through the BIDS information, you will see a checkbox labeled valid. If this is checked, then the filename and organization should be considered valid by the BIDS validator. However, this valid does not reflect having run the BIDS validator on the project.
We can also preview the overall organization of the BIDS directory from the Flywheel UI. From the three dot pull-down menu to the right of Run Gear button, you can toggle on/off a BIDS view to preview the BIDS directory structure and filenames.
From this view, we can quickly see that all of the functional runs were correctly named and added to the func folder. Scrolling down to sourcedata shows that all of the dicom.zip files were added there.

Step 4: Review the BIDS Curation Gear output csv files

If you ran the BIDS Curation Gear at the Project level, then there will be five output csv files created as Results.

Navigating to the Project-level Analyses tab, click on the curate-bids gear run to show the list of Results. You should see the below list of csv files:

The details of what information is contained in these csv files is covered in BIDS Curation Tutorial Part 5 Interpreting the Curation Report.

Finishing up with BIDS Curation

BIDS validation

Please note that due to how data are stored in Flywheel instances, it is not possible to directly run the BIDS Validator on a project. It is recommended that users either run the latest version of the BIDS Validator outside of Flywheel, or be prepared to correct validation errors that may be caught when running BIDS-apps gears, such as fMRIPrep.

Although, we did not encounter any errors during the BIDS Curation of the two example datasets, the next section covers how to find and fix common errors during BIDS Curation using the output curation reports. With the new adoption of the ReproIn naming scheme, most errors can be avoided by careful file classification and acquisition label renaming. Continue to BIDS curation tutorial part 4: curation reports to learn about the information contained in these reports and how to fix common errors.