Back to list of all tutorials
Back to course page
Back to Multimodal Tutorial List

Other Multimodal Tutorials: Multimodal Registration, Individual fMRI Integration, Surface-based Group fMRI Analysis

The purpose of this tutorial is to give you experience with the integration of Diffusion Tensor Imaging (DTI) with FreeSurfer. The data were collected at MGH as part of the MIND project.

If you are looking for the Tracula tutorial, you can find it here.

DTI Basics

It is assumed that you already have some basic knowledge of DTI and its analysis. This paragraph is supplied as a summary for completeness. DTI attempts to measure the diffusion of water molecules in the tissue. Within the brain, white matter tracts tend to act like little straws that constrain the direction of diffusion. DTI analysis measures the orientation of this diffusion and the "strength" of this orientation. The strength of preferred orientation is often measured by fractional anisotropy (FA) and diffusivity is often measured by the Apparent Diffusion Coefficient (ADC).

Prior to DTI analysis, it is customary to motion correct, and sometimes eddy current correct, the diffusion weighted images. This is done by selecting one of the images as a template (usually a low-b volume). This forces all the DTI-related maps to be in-line with the template. Consequently, this template should be used as the registration target.

Tutorial Data Set

This data was acquired at MGH as part of a MIND Consortium study. Seventy images were acquired, 10 low-b and 60 diffusion weighted. The diffusion data are located in the '$TUTORIAL_DATA/diffusion_tutorial' directory and the corresponding FreeSurfer anatomical analysis (recon) is located in the '$TUTORIAL_DATA/diffusion_recons' directory.


If You're at an Organized Course

If you are taking one of the formally organized courses, everything has been set up for you on the provided laptop. The only thing you will need to do is run the following commands in every new terminal window (aka shell) you open throughout this tutorial. Copy and paste the commands below to get started:

export SUBJECTS_DIR=$TUTORIAL_DATA/diffusion_recons
export TUTORIAL_DIR=$TUTORIAL_DATA/diffusion_tutorial
cd $TUTORIAL_DIR/$subj/dtrecon

To copy: Highlight the command in the box above, right click and select copy (or use keyboard shortcut Ctrl+c), then use the middle button of your mouse to click inside the terminal window (this will paste the command). Press enter to run the command.

These two commands set the SUBJECTS_DIR variable to the directory where the data is stored and then navigates into this directory. You can now skip ahead to the tutorial (below the gray line).

If You're not at an Organized Course

If you are NOT taking one of the formally organized courses, then to follow this exercise exactly be sure you've downloaded the tutorial data set before you begin. If you choose not to download the data set you can follow these instructions on your own data, but you will have to substitute your own specific paths and subject names. These are the commands that you need to run before getting started:

source your_freesurfer_dir/SetUpFreeSurfer.csh
export TUTORIAL_DATA=your_tutorial_data
export SUBJECTS_DIR=$TUTORIAL_DATA/diffusion_recons
export TUTORIAL_DIR=$TUTORIAL_DATA/diffusion_tutorial
cd $TUTORIAL_DIR/$subj/dtrecon

If you are not using the tutorial data you should set your SUBJECTS_DIR to the directory in which the recon(s) of the subject(s) you will use for this tutorial are located.

This tutorial uses Freeview to view the output on several processing steps. Click here to familiarize yourself with Freeview if you are not already.

DTI Data Analysis Processing Stream


The following steps are necessary to prepare the diffusion data for various types of analyses. On each step there is a description of the command and how it relates to the overall processing stream, the actual command you would use, and how to visualize the output. Similar pre-processing steps can be accomplished by using Tracula, although output will be generated using different file names and file types. You may find that you prefer one method over the other depending on the types of analyses and degree of involvement you want to have.


To get started, one would have to reconstruct the diffusion tensor data from images collected. Additionally, it is recommended to correct for eddy currents and any motion artifacts, which could distort the DTI data. The 'dt_recon' command can be used to accomplish this pre-processing. It generates multiple NIFTI volumes that will be used in later steps. By default, the dt_recon command assumes that the FreeSurfer anatomical analysis (recon) has already been completed.

The following command is the first step in processing your diffusion data with dt_recon:

Don't run this command if you're at an organized course.

It will take a while and has already been done for you.

dt_recon --b bvals.dat bvecs.dat --i $TUTORIAL_DIR/$subj/orig/*-1.dcm --s $subj --o $TUTORIAL_DIR/$subj/dtrecon


Run 'ls' to see what outputs dt_recon makes.


Viewing the Data

After running the dt_recon command and confirming the diffusion data is registered with the anatomical data (you learned how to do this in the Multimodal Tutorial), you may want to look at some of the outputs in Freeview. For example, you could run the following command to view the fractional anisotropy volume (fa.nii) and the apparent diffusion coefficient volume (adc.nii). The '$TUTORIAL_DIR' and '$subj' parameters need to be defined in advance. If you haven't done this already, please see the Tutorial Data Set section above.

freeview -v fa.nii adc.nii

Scroll the middle mouse button to zoom in and out. Click and hold the middle mouse button to move around the image. Use the 'Up' and 'Down' arrows (or 'Page Up' and 'Page Down' keys)'Page Up' and 'Page Down' keys to move back and forth through the volume slices. Use the orientation buttons to switch the plane ( FreeviewGuide/FreeviewGeneralUsage/FreeviewQuickStart/view_sagittal.gif , FreeviewGuide/FreeviewGeneralUsage/FreeviewQuickStart/view_coronal.gif , FreeviewGuide/FreeviewGeneralUsage/FreeviewQuickStart/view_axial.gif , FreeviewGuide/FreeviewGeneralUsage/FreeviewQuickStart/view_3d.gif ). Toggle between the two volumes by using 'Alt + C'.

Coronal view of the fractional anisotropy volume (fa.nii):

Coronal view of the apparent diffusion coefficient volume (adc.nii):

All other volumetric data sets generated by dt_recon may be viewed with Freeview. To see an explanation of the various outputs, see the dt_recon page.

The FA map can also be viewed as a heatmap on the subject's anatomical data with the white matter parcellation (wmparc.mgz) as the segmentation:

*NOTE: You must close the open Freeview window (visualizing the adc and fa maps), before you can open another one from the same terminal.

freeview -v $SUBJECTS_DIR/$subj/mri/brain.mgz \
            $SUBJECTS_DIR/$subj/mri/orig.mgz \
            $SUBJECTS_DIR/$subj/mri/wmparc.mgz:colormap=lut:opacity=0.2 \
            fa.nii:reg=register.dat:colormap=heat:heatscale=.2,.2,1 -colorscale -viewport coronal


  1. The FA is a value between 0 and 1, so the thresholds are set to 0.2 and 1.
  2. When the window first comes up, there will be a lot of activity outside the brain. To remove this, with the FA volume selected, set the Mask drop-down menu to brain.

  3. In the image below, you can see that white matter tends to have a higher FA.


Close Freeview when you are done.

Resampling Structural Data in the Diffusion Space

In order to analyze specific sub-cortical or white matter regions in the diffusion data, we can resample the subcortical segmentations created by recon-all from the structural data into the diffusion space. The registration between the diffusion and structural space has already been computed when you ran the dt_recon command above. The registration can be found in the 'register.dat' file.

The 'register.dat' file describes a rigid-body transformation from the diffusion to the structural space. But to resample the structural volume into the diffusion space, we will need to apply the inverse of this transformation to our input volumes. We use the 'mri_vol2vol' command for this task. In the example below, we resample the white-matter parcellation volume (wmparc.mgz) into the diffusion space. Additionally, you may also want to repeat that process for the cortically-labeled volume (aparc+aseg.mgz).

mri_vol2vol --mov lowb.nii \
            --targ $SUBJECTS_DIR/$subj/mri/wmparc.mgz \
            --inv --interp nearest --o $SUBJECTS_DIR/$subj/mri/wmparc2diff.mgz \
            --reg register.dat --no-save-reg


As always, check the registration with the template. In this case, the template is the low-b image:

freeview -v $SUBJECTS_DIR/$subj/mri/orig.mgz \
            lowb.nii:reg=register.dat \
         -f $SUBJECTS_DIR/$subj/surf/lh.white:edgecolor=green \
            $SUBJECTS_DIR/$subj/surf/rh.white:edgecolor=green \
         -viewport coronal

Use Alt+V to toggle between the lowb and the orig, using the surfaces as a guide to make sure they are aligned.

The registration should be accurate. For more information on registration, see the Registration Tutorial.

Close Freeview when you are done.

The AlignAnat2Diff.csh script mentioned above also resamples the aparc+aseg for the same subject. To view the results, run:

freeview -v fa.nii \


Coronal view of the cortically-labelled volume (aparc+aseg2diff.mgz) overlayed on the fractional anistropy volume (fa.nii):


Close Freeview when you are done.


You may have noticed that there is some unwanted "noise" or "speckles" in the diffusion images when we view them in Freeview. This can be removed by masking out the space surrounding the brain. For a mask, we will use one of the segmentation volumes from the recon directory that was already resampled into the diffusion space (wmparc2diff.mgz). To apply the mask to the diffusion data and remove the unwanted "noise", we will use the 'mri_mask' command.

mri_mask fa.nii \
         $SUBJECTS_DIR/$subj/mri/wmparc2diff.mgz \


Run the freeview command below to compare the fractional anisotropy volume (fa.nii) before and after masking:

freeview -v fa.nii \

Use Alt+c to quickly alternate between the two volumes and see the difference.

Coronal view of the unmasked fractional anisotropy volume (fa.nii):


Coronal view of the masked fractional anisotropy volume (fa-masked.mgz):


Be sure to close the Freeview window before proceeding with the next step.

FA ROI Analysis

We have already resampled the white-matter parcellation and subcortical segmentation into the subject's diffusion space. We will now use mri_segstats to get FA statistics for each of the following ROIs (index/name pairs are found in the LUT):

 251 CC_Posterior (Posterior Corpus Callosum)
3024 wm-lh-precentral
3030 wm-lh-superiortemporal
3021 wm-lh-pericalcarine
  12 Left-Putamen
   4 Left-Lateral-Ventricle

The wm-lh-precentral, wm-lh-superiortemporal, wm-lh-pericalcarine are created by the gyral white matter parcellation. Now run mri_segstats:

mri_segstats \
    --seg $SUBJECTS_DIR/$subj/mri/wmparc2diff.mgz \
    --ctab $FREESURFER_HOME/FreeSurferColorLUT.txt \
    --id 251 --id 3021 --id 3024 --id 3030 --id 12 --id 4 \
    --i fa.nii --sum fa.stats

Click here to see the output, or open the fa.stats file in a text editor (it should be located in the directory you are currently in). You'll find the CC has an average FA of about 0.61; gyral parcellations are between 0.2-0.5; the left putamen is about 0.25; and the ventricle is about 0.12. This is as expected because the CC is highly directional with no crossing fibers so we would expect the CC to have the highest FA. The gyral white matter is also directional but has fibers crossing in them, so one expects the FA to be lower than CC. The gray matter (putamen) is still lower. Diffusion in the ventricle is isotropic, so we expect the ventricle to have the lowest FA.

Spatial Normalization

At this point we could run analyses on a subject's DTI and structural data, but we could not do a voxel-based group analysis with multiple subjects, because the data sets are not yet aligned in a common coordinate space. In other words, a certain coordinate location in one subject's volume does not necessarily correspond to the same anatomical location in any of our other subjects. We want to normalize (resample) the diffusion data of each subject into a specified common coordinate space.

In the example below, the data will be resampled into CVS space, but alternatively you could normalize your data in any other coordinate system (for example, MNI or Talairach). As a result of running mri_cvs_register on the structural acquisitions, a .m3z morph file ('combined_tocvs_avg35_elreg_afteraseg-norm.m3z') is created which describes the transformation for each subject that is necessary to move from an individual's native space to that of the common CVS space.

Don't run this command if you're at an organized course.

This command currently requires greater than 4GB of memory to run. We have already run it for you.

mri_vol2vol --targ $FREESURFER_HOME/subjects/cvs_avg35/mri/norm.mgz \
            --m3z $SUBJECTS_DIR/$subj/cvs/combined_tocvs_avg35_elreg_afteraseg-norm.m3z \
            --noDefM3zPath --reg $TUTORIAL_DIR/$subj/dtrecon/register.dat \
            --mov fa-masked.mgz \
            --o fa-masked.ANAT+CVS-to-avg35.mgz \
            --interp trilin --no-save-reg


To view the 'norm.mgz' file (which is in the target CVS space) and the 'fa-masked.mgz' file after is has been resampled in the common CVS space, run:

freeview -v $FREESURFER_HOME/subjects/cvs_avg35/mri/norm.mgz \

Use Alt+c to alternate between the two volumes.

Coronal view of the target CVS space (norm.mgz) we resampled into:


Coronal view of the masked fractional anisotropy volume after it was resampled into CVS space (fa-masked.ANAT+CVS-to-avg35.mgz):


Once all the subjects in your study are put into the same coordinate system, you are ready to begin your group analysis on the resampled subjects.

Links Of Interest



DTI tutorial scripts created by Lilla Zollei.

Other Multimodal Tutorials: Multimodal Registration, Individual fMRI Integration, Surface-based Group fMRI Analysis

Back to list of all tutorials
Back to course page
Back to Multimodal Tutorial List