Skip to content

Logo Logo

BIDS Curation Tutorial Part 2: Running Relabeling

Introduction

Relabeling is used to rename scans programmatically.

New name for BIDS Precurate Gear

The BIDS Precurate Gear has been renamed to Relabel Container. The functionality and use has not changed.

Instruction Steps

Once the data are in NIfTI format and has classifications (T1, T2star, etc.), we can use relabeling to rename the scans across the entire project quickly and easily.

Running the relabel-container gear is optional

You do not need to run relabeling if:

  • You have ReproIn-compliant names from the scanner

    OR

  • You have chosen to alter the curation Gear templates.

Warning

Altering the templates is considerably more difficult than running the relabel-container gear.

If you already have ReproIn-compliant names or are choosing to go the route of altering an existing Gear template, you may proceed to BIDS Curation Tutorial Part 3 Running the BIDS Curation Gear.

Otherwise, please continue on to learn about ReproIn and BIDS and how to set up relabeling for your study.

Step 0: Introduction to ReproIn

ReproIn is a specification developed by the Dartmouth Brain Imaging Center for organizing and naming sequences and exam cards on an MRI scanner. As described below, it makes use of the current BIDS specification to facilitate conversion of imaging exams to valid BIDS format. For new studies, Flywheel recommends adopting the ReproIn naming convention at the scanner. However, as described in this tutorial, the Flywheel Relabel Container Gear provides a way to adopt the ReproIn naming convention post-hoc for easy conversion of MRI study data into valid BIDS format.

Step 1: Review the README for the relabel-container gear

As with many gears, the relabel-container gear is in active development and may have new features that you have not seen or used before. Additionally, since it can be a little confusing as to why the gear is run twice, the README provides information about the process. Review the README in GitLab.

In short, the first run of the relabel-container gear gathers the information on the current acquisition labels and creates the csv files necessary to update the acquisition labels (and subject and session labels if needed) for successful curation into valid BIDS format. The second run of the relabel-container gear then updates the acquisition labels to what was specified in the csv files.

Step 2: Run the relabel-container gear

Relabeling occurs for the entire project at once. The gear may be launched from the project or subject level. Either choice generates the same output but running at the project level is encouraged because it may list additional unique labels present in other subjects.

Here, the subject-level is selected by clicking the person icon and then highlighting the heading, not the individual session, for the participant.

Click the Analyses tab and Run Analysis Gear. 001-Dataset2-relabel-container.png

Search for "Relabel Container", select the latest version, and run with the defaults and no inputs. 002-Dataset2-relabel-container.png

Step 3: Edit the three spreadsheets produced by the relabel-container gear

When the Relabel Container Gear finishes running, navigate to the Analyses tab and click on the gear run. 003-Dataset2-relabel-container.png

Download the acquisitions, sessions, and subjects csv files.

004-Dataset2-relabel-container.png

Edit the "new_acquisition_label" column in acquisitions.csv file to match the ReproIn convention. Examples of the convention can be found in the BIDS Design Spreadsheet Docs or from the BIDS Study Design Spreadsheet directly.

If you are already comfortable with the BIDS specification, feel free to skip down to the section on Flywheel's version of ReproIn to get the general pattern of how to format the new acquisition labels. Otherwise, the next two sub-sections on the anatomy of BIDS and ReproIn filenames may be useful to go through.

Anatomy of BIDS directory structure and filenames

The key to successful BIDS curation with ReproIn-compliant acquisition names is understanding the basic structure of a valid BIDS directory and the anatomy of a valid BIDS filename.

The BIDS directory structure organizes individual subject/session files into sub-folders of broad acquisition types: anat, func, dwi, fmap, and perf. So, for example, all NIfTI, JSON, physiological recording, or task event files associated with any functional runs will all be stored in the sub-<label>/ses-<label>/func folder. In this way BIDS keeps all files associated with a single broad acquisition type together. 

sub-<label>/
        [ses-<label>]/
                anat/
                    sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_<suffix>
                    sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_chunk-<index>]_UNIT1
                    sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_mod-<suffix>][_chunk-<index>]_defacemask
                func/
                    sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>][_echo-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_<suffix>
                    sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>]_events
                    sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>]_[recording-<label>]_physio
                    sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>]_[recording-<label>]_stim
                dwi/
                    sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_<suffix>
                    sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>]_[recording-<label>]_physio
                    sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>]_[recording-<label>]_stim
                perf/
                    sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>]_<suffix>
                    sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>]_[recording-<label>]_physio
                    sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>]_[recording-<label>]_stim
                fmap/
                    sub-<label>[_ses-<label>][_acq-<label>][_run-<index>][_chunk-<index>]_<suffix>  #GRE magnitude/phase pair and direct fieldmap
                    sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>]_dir-<label>[_run-<index>][_chunk-<index>]_epi #PEPOLAR

The anatomy of a BIDS filename is a bit more complicated, but most aspects are preserved across all file and acquisition types. As shown in the figure below, all BIDS filenames start with the subject label and optional session label (block 1) and end with a predefined suffix (block 3) indicating the image type (e.g., T1w, T2w, bold, dwi, etc.). (See the latest stable BIDS specification for MRI data for a complete list of the current suffixes.) The remaining elements (block 2) of a BIDS filename are used to provide additional description of the sequence used to collect the data.

bids-filename-anatomy

Commonly used descriptors are dir-<label> to capture the phase-encoding direction of a sequence, echo-<index> to label echoes from a multi-echo sequence, acq-<label> to capture the sequence used, and run-<label> to number multiple, identical acquisitions (e.g., two runs of the same functional task or multiple T1w images). <label> can accept any alphanumeric string with no blank spaces and no special characters, while <index> should be integer numbers (leading zeroes are acceptable).

Underscores and dashes

- and _ are preserved specifically for use by BIDS and should not be included in any <label> or <index>.

When understanding the figure above or the official BIDS specication, note that any element of the BIDS filename enclosed in square brackets [] is optional, while any element not enclosed in square brackets is required. Also, the ordering the individual filename elements is preserved, and specifying elements out of order may result in validation errors.

BIDS func filenames

task-<label> is a required descriptor for BIDS func filenames.

So, for a T1-weighted anatomical scan, 

sub-01_T1w.nii.gz
would be the most minimal valid BIDS filename. Similarly, for a single-echo EPI BOLD functional scan, 
sub-01_task-nback_bold.nii.gz
would be the most minimal valid BIDS filename, as task-<label> is required by BIDS for files stored in func.

Warning

The BIDS specification is always being updated and refined. While we do our best to keep all Flywheel documentation and the BIDS Curation gear up-to-date, the official BIDS specification should be considered the only source for accurate information regarding the current state of BIDS directory structure and filename standards.

ReproIn

As briefly described above, ReproIn was developed by the Dartmouth Brain Imaging Center as a way to organize and name MRI sequences on the scanner to faciliate conversion in the BIDS standard. It preserves many of the aspects of the anatomy of a BIDS filename but removes the need to specify the subject-<label>[_session-<label>] directly, includes the broad acquisition category, and reverses the order of the _suffix and optional descriptors.

reproin-filename-anatomy

As illustrated by the above figure, ReproIn-compliant filenames start with the sequence type (e.g., anat, func, fmap, dwi, etc.) followed by an optional <suffix> label. Any other optional BIDS descriptors are then added.

So, reusing the simple examples from above, for a single T1w scan, the most minimal ReproIn-compliant name would be 

anat
as ReproIn is designed to extract the type of anatomical scan from the DICOM header information. Similarly, for the single-echo EPI BOLD function run, 
func_task-nback
would be the most minimal ReproIn compliant name.

Flywheel's version of ReproIn

As part of the shift away from editing existing or creating new BIDS Curation Gear templates, Flywheel has chosen the ReproIn naming scheme as the new default for the BIDS Curation Gear. The main modification from ReproIn is to require the suffix label, rather than trying to extract that information from the DICOM headers.

Back to our simple examples, when updating the "new_acquisition_label" column in acquisition_labels*.csv, the single T1w scan would be coded as 

anat-T1w
while the single-echo EPI BOLD functional run would be 
func-bold_task-nback

Putting everything together, for Dataset 2 in Part 1, the "new_acquisition_label" column should be updated to the following:

existing_acquisition_label new_acquisition_label
4 - Axial EPI-FMRI (Interleaved I to S) func-bold_task-task_acq-inter_dir-IS
5 - Axial EPI-FMRI (Sequential I to S) func-bold_task-task_acq-seq_dir-IS
6 - Axial EPI-FMRI (Interleaved S to I) func-bold_task-task_acq-inter_dir-SI
7 - Axial EPI-FMRI (Sequential S to I) func-bold_task-task_acq-seq_dir-SI
3 - EPI PE=AP func-bold_task-task_dir-AP
4 - EPI PE=PA func-bold_task-task_dir-PA
5 - EPI PE=RL func-bold_task-task_dir-RL
6 - EPI PE=LR func-bold_task-task_dir-LR

All four scans for each session are EPI-BOLD scans, and thus should all be categorized as func-bold. Next, we add the task-<label> descriptor, as this is required by the BIDS specification for all func scans. Since, the original acquisition name did not provide any details of what task was performed, we can just use a generic label task-task. The optional acq-<label> and dir-<label> descriptors are included to capture the relevant details of each scan provided in original acquisition label.

BIDS Ignore

There may be instances where you do not want to have a particular acquisition converted into BIDS format by the BIDS Curation gear. The easiest way to have an acquisition be ignored by the BIDS Curation gear is to postpend the "new_acquisition_label" with _ignore-bids or _ignore-BIDS.

Step 4: Upload the edited spreadsheets to the project or subject

Navigate to the Project-level Information tab.

005-Dataset2-relabel-container.png

Upload the edited spreadsheets to the project-level as shown below.

006-Dataset2-relabel-container.png

Step 5: Re-run the relabel-container gear with the spreadsheet inputs specified

You only need to specify inputs for the csv file(s) you edited. So, if you only edited the acquisitions.csv file, you do not need to specify the inputs for either Sessions or Subjects. The below screengrabs show specifying all three csv files as inputs for completeness.

007-Dataset2-relabel-container.png

008-Dataset2-relabel-container.png

009-Dataset2-relabel-container.png

Step 6: Check the acquisition labels

When the second run of the Relabel Container Gear finishes, check the log file for errors.

010-Dataset2-relabel-container.png

Then navigate back to either the Subjects or Sessions tab to check the relabeling results for each acquisition.

011-Dataset2-relabel-container.png

If you notice any errors, update the "new_acquisition_label" column of the acquisitions.csv file, re-upload the file to the Project level, and re-run the Relabel Container Gear including the csv files as inputs.

Fixing new_acquisition_label errors

Before fixing any errors in the "new_acquisition_label" column in the acquisitions.csv file, copy the contents of this column over to the "existing_acquisition_label" column first. Alternatively, you can re-run the relabel-container gear with no inputs and edit the new acquisitions.csv file.

Wrapping up with relabeling

Once you are satisfied that the relabeled acquisitions are in Flywheel's version of the ReproIn naming convention, you are ready to move on to BIDS Curation.