Why This Matters

Before we can analyze fMRI data, we need to convert it from the raw medical imaging format (DICOM) into the standardized neuroimaging format (NIfTI). While doing so, we also need to structure the data in a BIDS compliant way (see Gorgolewski et al., 2016, Scientific Data). This process is crucial because:

• DICOM files are designed for medical use and include a lot of metadata that we don’t need for analysis.
• NIfTI files are the standard format for fMRI data analysis, supported by all major neuroimaging software (e.g., fMRIPrep, MRIQC, AFNI, SPM, FSL).
• Standardized conversion and BIDS structuring ensures that our data is properly organized for preprocessing pipelines like fMRIPrep, improving reproducibility and collaboration.

In this training, you'll learn how to use HeuDiConv, a powerful and flexible tool for converting raw DICOMs to BIDS-formatted NIfTI files. While HeuDiConv can be frustrating to use at first, it provides essential control over how data is structured and labeled.

Seriously, HeuDiConv is powerful, but a giant pain in the neck. I've tried to take a lot of the pain out of using it. But, just so you get an idea... here's a meme I made at 2am many years ago after struggling to get my HeuDiConv code to work.

Step 1: Read the HeuDiConv Documentation (~1 Hour)

Before diving into the hands-on portion, take some time to read about how HeuDiConv works.

Read: HeuDiConv Documentation

• Focus on the tutorials. Particularly:
  • Quickstart
  • [Custom Heuristics(https://heudiconv.readthedocs.io/en/latest/custom-heuristic.html)
  • NOTE: You do NOT have to do their tutorials. Just read how the code works
• See also the external tutorials at the bottom of this page
  • NOTE: Some of these tutorials may not be up to date with the latest releases of heudiconv.
• If you run into unfamiliar terms, don’t stress—you’ll understand them better once you start working with actual data.

Final note: HeuDiConv uses subject IDs in a zero-padded format (sub-001, sub-002). Your data will be structured automatically, but it's good to be aware of this convention.

Step 2: Practice Converting Data (~2 Hours)

Accessing the Training Data

For this practice session, you will convert the DICOMs for one participant stored on the lab server. This training can be done on your laptop, but you'll need Docker installed and you'll need to do a lot of troubleshooting. Easier is to do it on a lab workstation.

The training data are located at: /mnt/ccsl_nas/heudiconv_training

Start by reading the README.txt file in that directory. It will guide you through all the steps. The code is heavily commented, which makes it look messy. But the goal is to make things really explicit.

NOTE: If this is your first time running Anaconda on your workstation, you may get an error that looks like this when you try to call $ jypyter notebook from a terminal:

Command 'jupyter' not found, but can be installed with:
apt install jupyter-core
Please ask your administrator

You do NOT need to install jypyter. It is already installed in a location that allows for multiple users to access the same installation. All you need to do is add Anaconda to your PATH. In short, PATH lets you call a program from anywhere in a terminal using a relative link. Follow this guide to learn how to add Anaconda to path.

NOTE: When uploading your files to the browser-based BIDS validator, you'll need to use the file GUI to access where the server is mounted. You can do this as follows:

• Click "Select Dataset Files"
• Click "+ Other locations"
• Click "Computer"
• Click "mnt"
• Click "ccsl_nas"
• Navigate to your new directory with the BIDS files
• You can always find the lab server following this procedure

Cool Trick: You can make the lab server easier to find in the future. Follow these steps:

• On the sidebar, open the file browser
• Click "+ Other Locations"
• Click "Ubuntu"
• Click "mnt"
• Click and drag "ccsl_nas" to the file browser sidebar until you see "New Bookmark". Release your mouse click
• The server will now always be easily accessible from the file browser

Step 3: Check Your Work (~30 Minutes)

Navigate through your new directories. See how the data are structured. Try to open files and get a sense for what is in them. These are the raw data you will now start working with extensively. Given what you know about the BIDS structure, does everything look right? Note files that the BIDS validator gave warnings for. Look at them. Can you figure out why there was a warning?

Use fsleyes to look at an image:

$ fsleyes sub-005_task-game_run-01_bold.nii.gz

Step 4: OPTIONAL Install FSL on your laptop (~1 Hour)

While not required, installing additional software on your laptop can be helpful if you want to analyze data outside the lab.

FSL is a major fmri software package that our lab uses extensively. It is already installed on the lab workstations. But you might want it on your laptop, especially if you plan to work from home sometimes. To install FSL, follow these directions.