Introduction/Overview

This lesson walks you through each step of processing a dataset in ezBIDS.

Practice

In the accompanying practice lesson, you'll go through the steps yourself. You might want to intermix this lesson and the practice, depending on how you learn (e.g., start with the practice, and then go back and look at the videos and descriptions for each stage of ezBIDS processing). Consider watching the first video and then figuring out what works for you.

Introduction to ezBIDS

ezBIDS is part of the suite of online tools at brainlife.io. It is still being developed, but it is the most approachable way I know to correctly convert DICOMS to BIDS and certainly a wonderful way to start learning about that conversion process. ezBIDS can handle multiple subjects, but you'll need a good internet connection and patience to upload lots of data!

ezBIDS PROS

• No Installation: It does not require that you install anything on your computer.
• Easy: "ezBIDS eliminates the need for the command line and heuristic/configuration setup."
• Data Discovery: ezBIDS tries to guess what kind of scans your DICOMs are (and it does a pretty good job).
• Secure:

ezBIDS runs on a secure VM running on the Jetstream HIPAA-aligned cloud computing infrastructure."
https://brainlife.io/ezbids/

ezBIDS CONS

• You cannot save settings to reapply later, which means you have to specify the settings each time you upload a batch of DICOMS.
• ezBIDS does not handle uncommon sequences, like ASL (though I have requested this feature and they are looking into it).

Watch this 3.5-minute video clip introducing ezBIDS.

DICOM Upload

• The first step is to Upload DICOMS. The step is highlighted in green on the upper left.
  (Before uploading, consider removing scouts, derived images and other images of no interest (like poor quality or incorrect images that you do not want to convert). This should help reduce the upload pressure.
• To upload, just drag the DICOM folder onto the page.
• Do not close/refresh this page until all files are uploaded!
• Depending on how much data you have (e.g., multiple subjects), the process can take several hours.
• ezBIDS reports "Analysis complete" when it has finished the initial upload and analysis. This just means it has looked at your DICOM data, it does not mean it has converted your data.
  • Check that the correct number of items is in the Object List. Each object is a link to the JSON metadata
• ezBIDS does not require your DICOM series to be in separate subfolders (though it does not mind if they are). ezBIDS will do data discovery: It will look at each DICOM image and categorize it as belonging to a series if any of the following four fields are unique:
  • Series description,
  • Echo Number,
  • Image type and
  • Multiband Acceleration factor

Watch this 6-minute video discussing DICOM Upload

Navigating Between Steps

ezBIDS divides the processing into steps, marked in green on the left sidebar. At any time, you can toggle between the current step and other steps in the process using the buttons at the bottom of the page (you cannot simply click the step in the sidebar).

Watch this 30-second video clip

Dataset Description

You have the opportunity to provide information for the dataset_description file. This is a JSON text file with a fairly straightforward format, so you could also do this later. The fields with red asterisks are required (but there are defaults filled in).

See BIDS examples: Dataset Description

Here is the dataset_description.json file created in this video:

Once the data_description.json is created, you can edit the contents by adding or revising values, i.e., either between double quotes or in square brackets). Just use a text editor like notepad or VSCode (not Word).

Watch this 30-second video clip.

Subjects/Sessions

Next, ensure that the subject and session are correct. For this older dataset, the subject number should be 188, instead of sub188, since sub- will be prepended to the subject number (and sub-sub188 looks silly).

By default, ezBIDS uses PatientName as the subject number. On the upper right,  Reset the Subject mapping   provides the option to revise the subject identifiers, for example, maybe you want your subjects to be numbered consecutively starting at 1.

Choices are

• Use PatientName,
• Use PatientID,
• Numerical (1,2,3).

You can also manually specify any subject number you want.

There is no session in this video. If you had multiple subjects and or sessions to process, you could exclude any of them here.

Watch this 3.5-minute video clip

Series Mapping: Introduction

In the Series Mapping Step, sequences are marked that need attention. Red marks are especially important. Yellow marks are warnings. In the video, the ASL sequences are marked in yellow, because ezBIDS cannot distinguish them. Object #14 has an error marked in red that must be addressed.

It is important to fill in as much information as possible in the Series Mapping tab, because this will apply to all subjects and sessions (it can handle the possibility that some series are missing from some subjects or sessions, so don't worry about that.)

You can exclude sequences here or in the Dataset Review.
Watch this 1.25-minute video clip.

Series Mapping: Field Maps

The reason we acquire field maps is to use them to correct EPI images, especially fMRI images. ezBIDS allows us to add the IntendedFor JSON field that lists the files each field map is intended to correct.

For this dataset, ezBIDS did not recognize the field maps, so we need to modify the settings and provide all of the appropriate information.
For each image, we can see it in three planes and see the associated JSON file. Providing more information allows the JSON file to be updated so that the phasediff JSON file has both EchoTime1 and EchoTime2 values! The image and metadata for each series can be examined in the web interface.

Note that for the U of A Siemens research scanner, the Field maps always include Magnitude 1, Magnitude 2, and the PhaseDiff images. ezBIDS will correctly order these images in the interface (Magnitude 1, Magnitude 2, and the PhaseDiff). Additionally, the phasediff image looks quite different than the magnitude images.

Watch this 3.25-minute video clip.

Series Mapping: Functional Data

For each of the 4 BOLD (fMRI) series, we need to provide the task name and run number. After we supply this required information, ezBIDS removes the notifications from the sequence name and adds the task and run information for that sequence.

Watch this 1.5-minute video clip.

Series Mapping: DWI RPE

• We collected a reverse phase encoded B0 image for correcting the distortion in our DWI image. This image is classified as a field map epi image by BIDS (though, technically, it is not a field map).
• Like the phase and magnitude field maps, we need to fill out the IntendedFor field for the RPE (reverse phase encode) image.
• The RPE image also requires information about the direction of acquisition. Fortunately, that is included in the original DICOM name, so it is easy to retrieve.

Watch this 1.75-minute video clip.

Events

If you have task-based fMRI (func) data, then you may optionally provide information about the task timing. This information is provided as text files for each run, and should include at least onset (in seconds), duration (in seconds), and trial type (a condition name associated with each row). Although it is possible to add more columns, like response times, the following tab-separated text file is appropriate and consistent with the BIDS event specification.

Watch this 3-minute video clip.

Dataset Review

The Dataset review not only provides you with an opportunity to correct event information (as illustrated above) but allows you to review all of the sequences and make final adjustments or exclude a sequence.

For a more complex dataset, ezBIDS may complain:

Despite the complaint, it will generate the BIDS files you requested (that is, you do not have to exclude these).

If two objects have the same specification, however, ezBIDS will refuse, e.g.

Watch this 3-minute video clip.

Defacing

After the Dataset review, you can choose whether or not to deface. Once defacing is complete, you can examine the results and decide whether or not to use the defaced data. NiiVue is good for this. It is possible to deface T1w, FLAIR, and T2w images.

Watch this 3-minute video clip.

Particpant Info

After defacing, you can ensure that demographic information is correct, and even add more.
Watch this 30-second video clip.

Finalize and Download BIDS

Finally, you are given the opportunity to download the BIDS directory. You can also send the data to brainlife.io for further processing, or upload it to OpenNeuro for sharing (if it has been defaced).

The Finalize step also provides you with the opportunity to save all acquisitions set to "exclude" in an excluded bids directory. This means that you'll have the NIfTI files and JSON sidecars, although the names of files in the excluded directory will not be BIDS-compliant.

Watch this 30-second video clip.

• Avesani P, McPherson B, Hayashi S, Caiafa CF, Henschel R, Garyfallidis E et al. (2019) The open diffusion data derivatives, brain data upcycling via integrated publishing of derivatives and reproducible open cloud services. Sci Data 6: 69. This is a case study using brainlife.io.
• BIDScoin This is another tool for conversion. It also does data discovery like ezBIDS!
• BIDS Validator Site
• brainlife.io
• BIDS event specification

Summary

• In this lesson, you learned about using an online tool, ezBIDS, to convert your DICOM images to BIDS. The tool continues to evolve, so it may be somewhat different (better) by the time you use it.

PROS

• The tool is secure, and given a good internet connection, it ought to be able to handle a whole directory of participants.
• It has advantages over dcm2niix in that it produces BIDS-validated results and provides considerable assistance in characterizing your data.
• ezBIDS is the first step in using Brainlife.io tools, which look like they will become increasingly valuable.

CONS

• As of this writing (2022/12/03), I don't know any way to re-use the processing choices. The ability to re-use processing choices would be helpful if you converted data as you were collecting it (which is a good idea).
• ezBIDS is limited in the datatypes it can handle and tends to lag behind the BIDS Specification.

The next tool you will learn about is heudiconv. HeuDiConv setup is more complex than either of the conversion tools you've used to this point. However, HeuDiConv is infinitely flexible, compatible with DataLad, and leaves behind excellent and detailed provenance information (i.e., it documents exactly what was done so you can review or recreate it).

TO DO Checklist

✅ Participate in the Discussion of DICOM to BIDS Conversion
● DICOM to BIDS Conversion.
● Student Supplied Threads: DICOM to BIDS Conversion