BIDS curation tutorial part 3: running the BIDS Curation gear

Now that we have prepared our data and converted the scans to NIfTI format, we can run the BIDS Curation gear.  Note that Flywheel currently supports BIDS version 1.4.1.  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 1: Run the BIDS Curation gear

If you are running the V2.X version of the gear please see Running Version 2.X below.

Running Version 1.X

If you are running a version of the curation gear before V2.X, you can run on an individual session or else curate the whole project:

1. Click the Sessions icon. 
   
2. Select the Acquisitions tab, and click Run Gear.
   
3. Select Utility Gear, and choose BIDS Curation.  
   
4. This gear has no inputs. You can run it on a particular session or on the whole project.
   
5. Keep the default configuration.
   If you want to see the options are available, click the Configuration tab.
6. The Gear is set to run on the entire project (which is what we want), reset is off and the Default template is selected.
   • • reset: Enable if you want to re-curate your project. This option erases all previous curation information and starts over. 
     • template_type: A menu of the different templates you can choose.  If you have named your acquisitions by setting the SeriesDescription DICOM tag at the scanner console to the ReproIn standard, you will need to select the ReproIn from the list. The default template is BIDS-v1.  Choose Custom if you want to supply your own template.
7. Click Run Gear.

 

Running Version 2.X

The updated gear is an Analysis Gear instead of a Utility Gear.  See the README for the new gear for more details and "Changes from BIDS Curation V1 to V2" for a description of the differences from the old version (e.g. curation templates are now gear inputs).  A description of the inputs and configuration can be found in the Curating a Project section below.

The V2.X 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 find the right "Run Gear" or "Run Analysis Gear" button.  You first select the level to run at and then click the run button.

 

Curating a Session

Click on the "Sessions" tab at the top and then select a specific session:

 

Then press the "Run Gear" button on the right.  If you don't see this button, select the "Acquisitions" tab at the top (highlighted in blue above).  Then select "Analysis Gear":

A complete description of the input and configuration is covered below in the Curating a Project section or see the README in the gear repository.

 

Curating a Subject

Select the Subject view button and then select a specific subject:

It is easy to forget to select a subject.  If you do, you'll be running the gear on the currently selected session. 

 

Next, select the "Analyses" tab at the top right.  Note that there is another "Analyses" tab at the top left, that is for the project (described below).

 

Next, click on the "Run Analyses Gear" button and you'll be able to select the "BIDS Curation" gear.  (You won't have the choice of choosing a Utility Gear.)

 

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 and select the BIDS Curation gear.  

 

Then, Select the "Inputs" tab and click on the "template" input.

 

Click on the project name (if the template json file is attached to the project). Here, the project is "ReproIn."

 

Next, look in the list of "Files".  Here, there are a lot of files so there is a scroll bar.

 

Click on your template file, here it is called "reproin.json."

 

Click on that file and then hit the "Select File" button.

 

Then you should see your template file has been chosen as an input to the gear.  You can then choose Configuration options and/or hit "Run Gear."

 

Step 2: Review BIDS Curation log and project custom information

1. Go to the Provenance tab to view the jobs. Once the job completes, click View Logs for the "curate-bids" job.
2. 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.
3. 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 and an attached CSV file. 
   
   The CSV file contains the source and destination directories of the files that were uploaded to the project (when we uploaded data from part 1 of tutorial). 
4. Click the expand  button next to BIDS to view the section. Here you can see the BIDS Custom Information that was set by the curate-bids gear.
   This shows the default BIDS project information that was installed by the project curation template.  When BIDS curation is complete, this information is will be completely filled out. When Flywheel exports BIDS data, it converts metadata into the proper file and folder structure specified by the BIDS Standard.  The metadata on the project (shown above) will be written to the dataset-description.json file as described in the BIDS Standard here. 

Step 3: Review BIDS curated acquisitions

1. Let's take a look at how the acquisitions were curated.  Click the Sessions tab at the top of the oage, and then select the Acquisitions tab.
   
2. Now that the data has been curated for BIDS, toggle on the BIDS View.  Refresh your browser window if you do not see any changes.
3. Select a session. Note that the acquisitions are all under nonBids. This means the Default project curation template did not recognize any of the scans in the first session.
4. Review the other session. For example:
   Here we can see that: 
   • The functional MRI scans were recognized by the Default template
   • The NIfTI files were properly put into the func BIDS folder
   • The DICOM archives were all properly put into the sourcedata folder.
5. Hover over the gear icon to see which acquisition corresponds to this BIDS path:
   
   
   Note the BIDS file name for example, sub-DEV_ses-20180918114023_task-{file.info.BIDS.Task}_bold.nii.gz.  When you see {file.info.BIDS.Task}, it means that the BIDS curation template was not able to determine the proper value for the Task.  BIDS curation did not succeed in this case because the Default template expects to see "_task-taskname" in the acquisition label (SeriesDescription DICOM tag).
6. Select the information icon to see all of the BIDS information for a particular file. The classification for Modality, Features, Intent, and Measurement for this file look good. 
   
   
   
7.  Next to BIDS, click   to see that information for this file:
   
   Here next to error_message you can see Task '' does not match '^[a-zA-Z0-9]+$' , which shows the regular expression the template used that failed to match with a file. It also shows the full name of the acquisition file, "4_Axial_EPI_FMRI_Interleaved_I_to_S.nii.gz" (near the top-left). 
8. We can also view this same information outside of BIDS View:
   1. Disable BIDS View to see the "4_Axial_EPI_FMRI_Interleaved_I_to_S.nii.gz" file.
   2. Select the click Information icon . 
      
      Continue to BIDS curation tutorial part 4: troubleshooting and debugging to fix the errors from the BIDS curation gear.