Contents

DTI Basics
Tutorial Data Set
1. Preparations
  1. If You're at an Organized Course
  2. If You're not at an Organized Course
DTI Data Analysis Processing Stream

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).

Tutorial Data Set

This data was acquired at MGH as part of a MIND Consortium study. The raw data are in DICOM format (*.dcm) in the subject's 'orig' folder. Seventy images were acquired, 10 low-b and 60 diffusion weighted. The bvalues and gradient directions are stored in the DICOM header and are written to bvals.dat and bvects.dat, respectively, during the following analysis. 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.

This tutorial uses Freeview to view the output on several processing steps. Click here to familiarize yourself with Freeview.

Preparations

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:

setenv SUBJECTS_DIR $TUTORIAL_DATA/diffusion_recons
setenv TUTORIAL_DIR $TUTORIAL_DATA/diffusion_tutorial
set subj = Diff001

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:

tcsh
source your_freesurfer_dir/SetUpFreeSurfer.csh
setenv SUBJECTS_DIR your_tutorial_data/diffusion_recons
cd $TUTORIAL_DATA/diffusion_tutorial

Notice the command to open tcsh. If you are already running the tcsh command shell, then the 'tcsh' command is not necessary. 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.

DTI Data Analysis Processing Stream

Pre-processing

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.

DT_Recon

To begin with you will need to reconstruct the diffusion tensor data from the DICOM files acquired by the MR scanner. Additionally, it is recommended to correct for Eddy currents and any motion artifacts, which could distort the DTI data. This pre-processing step uses the 'dt_recon' command to accomplish this. 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. If your diffusion DICOM files were acquired using a non-Siemens scanner, you will have to specify the scan specific bvalues and bvector with the '--b' flag. If your DICOM files were acquired using a Siemens scanner, then this information can be extracted from the DICOM headers and are saved in the bvals.dat and bvecs.dat files. The DICOM files in this tutorial data set were acquired using a Siemens scanner.

dt_recon --i $TUTORIAL_DIR/$subj/orig/*-1.dcm --s $subj --o $TUTORIAL_DIR/$subj/dtrecon

Note: you do not need to run this command for the course. The data has already been processed. The location of the DICOM files for our subject is indicated by the '--i' flag. In the case of this tutorial, they are located in a sub-folder named 'orig' within each subject's main folder. In order to automatically establish a correspondence between the structural and diffusion scans of the same subject, we pass the subject ID information using the '--s' flag. That will allow the program to find the relevant files in '$SUBJECTS_DIR/$subj' of the structural recon. (If you do not have access to the structural recons at the time of the diffusion analysis, you can omit '--s' and use the '--no-reg' flag.) The desired location of the output is indicated with the '--o' flag. In this example, we are going to name the output folder 'dtrecon', which will be automatically created by the program.

This command has already been run for all of the subjects in the study. To see a script which could be used to run dt_recon on multiple subjects take a look at the 'DiffPreproc.csh' script on this page.

After running the 'dt_recon' command, you may want look at some of the outputs in Freeview. 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 near the top of the page.

Scroll the middle mouse buttom to zoom in and out. Click and hold the middle mouse buttom to move around the image. Use the '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 , , , ). Toggle between the two volumes by using 'Alt + C'.

freeview -v $TUTORIAL_DIR/$subj/dtrecon/fa.nii \
            $TUTORIAL_DIR/$subj/dtrecon/adc.nii

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 (*.nii) could be viewed in a similar way. To see an explanation for the various volumes, see page. Be sure to close the Freeview window when you are finished viewing the data before proceeding with the next step.

Resampling Structural Data in the Diffusion Space

In order to be able to refer to specific sub-cortical regions or areas of white matter in the diffusion data (and in the group analysis), we resample some of the segmentation volumes from the structural recon folder in the diffusion space. The registration between the diffusion and structural space has already been computed as part of the previous pre-processing step (unless you ran 'dt_recon' with the --no-reg flag). The 'registration.dat' file describes a rigid-body transformation from the diffusion to the structural space. As we would like to resample the structural volume in 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) in the diffusion space. Additionally, you may also want to repeat that process for the cortically-labelled volume segmentation (aparc+aseg.mgz).

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

Remember that in the above, it is the inverse transformation that we apply, so the role of the 'moving' and 'target' volumes are going to be inverted. The input flags should be used to reflect the original direction of the transformation, and it is the '--inv' flag that will reverse their roles. When computing the 'register.dat' transformation, it was the 'lowb.nii' volume that was moved into the structural space, so we indicate this volume by the '--mov' flag. (Note, any diffusion related volume from the dt_recon file could be used here.) The target of the original registration was in the structural space and that is indicated by the '--targ' flag. As it is the wmparc.mgz volume that we wish to resample in the diffusion space, in the above, we identify the target volume to be just that. The '--interp' flag indicates the type of interpolation that we want to use for the resampling. In the case of segmentation volumes, that option should always be set to nearest, indicating nearest neighbor interpolation. The '--o' flag indicates the desired output filename location, which in our example is 'wmparc2diff.mgz'. The rigid-body transformation matrix is stored in the 'register.dat' file and it is indicated by the '--reg' flag. You can use the same 'register.dat' file to move other structural volumes of this subject into the same diffusion space. The '--no-save-reg' flag tells 'mri_vol2vol' not to write out another registration matrix file.

This command has been run for all of the subjects in the study for you already. To see a script which could be used to run the mri_vol2vol command on multiple subjects using both the wmparc.mgz and aparc+aseg.mgz, take a look at the 'AlignAnat2Diff.csh' script on this page.

After running this command you may want look at the output in Freeview. Run the following command to view the aparc+aseg2diff.mgz overlayed on the fa.nii volume using a colormap lookup table (lut). The '$TUTORIAL_DIR', '$subj', and '$SUBJECTS_DIR' parameters need to be defined in advance. If you haven't done this already, please see the "Tutorial Data Set" section near the top of the page.

freeview -v $TUTORIAL_DIR/$subj/dtrecon/fa.nii \
            $SUBJECTS_DIR/$subj/mri/aparc+aseg2diff.mgz:colormap=lut

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

Be sure to close the Freeview window when you are finished viewing the data before proceeding with the next step.

Masking

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. We will use one of the segmentation volumes from the recon directory that is already resampled in the diffusion space (wmparc2diff.mgz) as the mask. This way all non-brain areas will be assigned to the background. This step uses the 'mri_mask' command to remove the unwanted "noise". The difference should be clear by examining a volume before and after masking (see the Freeview commands below). The command below applies a mask to the fractional anisotropy volume (fa.nii), but you may run 'mri_mask' on any other diffusion volume (i.e., adc.nii, ivc.nii)

mri_mask $TUTORIAL_DIR/$subj/dtrecon/fa.nii \
         $SUBJECTS_DIR/$subj/mri/wmparc2diff.mgz \
         $TUTORIAL_DIR/$subj/dtrecon/fa-masked.mgz

This command does not require flags to be passed, you just need to verify the order of the input arguments you are passing to it. The first argument should be the volume you wish to mask. The second argument is the volume to be used as a mask. And the third argument should be the name of the output file you would like to be created. In this example, we append '-masked' to the original unmasked volume file name so we can tell them apart.

This command has been run for all of the subjects in the study for you already. To see a script which could be used to run the mri_mask command on multiple subjects take a look at the 'DiffMasking.csh' script on this page.

After running this command you may want look at the output in Freeview. Run the following command to compare the fractional anisotropy volume (fa.nii) before and after masking using the white matter parcelation volume (wmparc2diff.mgz), which we resampled earlier in diffusion space. 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 near the top of the page.

freeview -v $TUTORIAL_DIR/$subj/dtrecon/fa.nii \
            $TUTORIAL_DIR/$subj/dtrecon/fa-masked.mgz

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 when you are finished viewing the data before proceeding with the next step.

Spatial Normalization

At this point we could run analyses with a subject's own 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. This step normalizes (resamples) the diffusion data of one subject in a specified common coordinate space. In this example, the data will be resampled in CVS space, but alternatively you could normalize your data in any other (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.

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 $TUTORIAL_DIR/$subj/dtrecon/fa-masked.mgz \
            --o $TUTORIAL_DIR/$subj/dtrecon/fa-masked.ANAT+CVS-to-avg35.mgz \
            --interp trilin --no-save-reg

The target CVS space where we want to resample our moving volume (fa-masked.mgz) is indicated with the '--targ' flag. The '--m3z' flag indicates the name of a morph file created for this subject by the mri_cvs_register command, which serves as a link between this subject's native space and the CVS space. The '--noDefM3zPath' indicates to the command not to search for the morph in a default directory ($SUBJECTS_DIR/$subj/mri/transforms), instead just use the full input filename. The '--reg' flag identifies the rigid-body motion that describes the connection between the structural and the diffusion spaces. As the CVS morph is computed using structural volumes and in the above example we are applying the CVS morph to a diffusion volume, we need to make sure that the transformation between these two spaces is also taken into account during the resampling process. The '--mov' flag indicates the moving volume, the volume we want to resample in the common CVS space for a subsequent group analysis. The '--o' flag describes the desired name of the output file. The '--interp' flag indicates the type of interpolation that we want to use for our resampling. As in the above we are using a non-segmentation volume as an input, we use the default trilinear (trilin) interpolation option. If you wanted to resampled a diffusion label volume in CVS space, you would want to use the nearest neighbor (nearest) interpolation option. Again, the '--no-save-reg' flag tells the command not to write out another copy of the registration matrix that is being applied.

This command has been run for all of the subjects in the study for you already. You would need to run it on every subject in your data set before running a group analysis. To see a script which could be used to do that, take a look at the '!AlignAnatCVSToAVG.csh' script on this page.

After running this command you may want look at the output in Freeview. Run the following command to view the target CVS space 'norm.mgz' file and the 'fa-masked.mgz' file after is has been resample in the common CVS space. 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 near the top of the page.

freeview -v $FREESURFER_HOME/subjects/cvs_avg35/mri/norm.mgz \
            $TUTORIAL_DIR/$subj/dtrecon/fa-masked.ANAT+CVS-to-avg35.mgz

Coronal view of the target CVS space (norm.mgz) we want to resample in:

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

Be sure to close the Freeview window when you are finished viewing the data before proceeding with the next step.

Group Analysis

Now that the DTI data for each subject has been reconstructed, masked and resampled in the CVS common space, we can perform a group analysis to examine between-subject differences. Before running the actual analysis command, we will need to group each subject's volume into a four-dimensional volume. We will also need to create two simple text files to indicate the comparison we want to make.

Assemble Data

In order to run the group analysis, 'mri_glmfit', you will need to first assemble your data in a particular manner. After you have chosen a coordinate space (i.e., CVS) where you want to do your analysis and have resampled all of your data in that space, you will need to create a single volume that stacks or concatenates all of the individual subject volumes. In the case of Freesurfer that would mean to create a volume with as many frames as the size of your input data set. For example, ten subjects which each have a volume of 256x256x190, would lead to a single volume with dimensions 256x256x190x10.

mkdir $TUTORIAL_DIR/GLM
set inputfiles = ($TUTORIAL_DIR/Diff???/dtrecon/fa-masked.ANAT+CVS-to-avg35.mgz)
echo $inputfiles
mri_concat --i $inputfiles --o $TUTORIAL_DIR/GLM/GroupAnalysis.fa-masked.CVS-to-avg35.Input.mgz

In the above example, we first created an output directory for the group analysis (GLM). We then created a parameter called 'inputfiles' which contains all the names of the fractional anisotropy volumes that we want to include in the analysis from this data set. The 'echo' command will print out the value of your parameter. It will give you a list of the file paths to each input volume, so that you can verify that the order of the subject volumes matches the order of the entries in your fsgd file. Note that the order of your image volumes within the data stack is important and it needs to match the order of entries in your fsgd file! The 'mri_concat' command is called to stack or concatenate the subjects' volumes into a multi-frame volume. We pass the command the input parameter 'inputfiles' containing the list of all the the fractional anisotropy volumes, and the file path and name of the desired output file (GroupAnalysis.fa-masked.CVS-to-avg35.Input.mgz).

For visualization purposes we will also create the average of the input images, so that we can overlay the group analysis results on top. We use the 'mri_average' command to create an average of the input images.

mri_average $inputfiles $TUTORIAL_DIR/GLM/Average.fa-masked.CVS-to-avg35.Input.mgz

When we run the 'mri_average' command it produces a .mgz file, which is an average of the input volumes listed in the 'inputfiles' parameter. Note that we appended 'Average' to the beginning of the output file name.

GLM Fit

For running the actual group analysis, we use the 'mri_glmfit' command. Besides the input data, we need to create an fsgd file and a contrast matrix. Together, these two files tell 'mri_glmfit' what kind of analysis we are interested in. In this case we are using gender as a between-subjects factor to examine the effect of gender on fractional anisotropy.

FSGD text file (more info):

Run this command to view the fsgd text file, or you can scroll down to view its contents as well.

gedit $TUTORIAL_DIR/scripts/group_analysis.fsgd

(You do not need to copy/paste the text below into the terminal window, the group_analysis.fsgd file has already been created for you).

GroupDescriptorFile 1
Title Group Analysis
Class Male plus blue
Class Female circle green
SomeTag
Variables             Age

Input Diff001      Female 47
Input Diff002      Male   57
Input Diff003      Female 36
Input Diff004      Male   50
Input Diff005      Male   46
Input Diff006      Male   41
Input Diff007      Male   52
Input Diff008      Female 63
Input Diff009      Female 38
Input Diff010      Female 30

DefaultVariable Age

Run this command to view the contrast matrix text file, or you can scroll down to view its contents as well.

cat $TUTORIAL_DIR/scripts/contrast.mtx

(You do not need to copy/paste the text below into the terminal window, the group_analysis.fsgd file has already been created for you).

0 0 .5 .5

Now we are ready to run the actual group analysis command, 'mri_glmfit'.

mri_glmfit --y $TUTORIAL_DIR/GLM/GroupAnalysis.fa-masked.CVS-to-avg35.Input.mgz \
           --fsgd $TUTORIAL_DIR/scripts/group_analysis.fsgd dods --C contrast.mtx \
           --glmdir $TUTORIAL_DIR/GLM/gender_age.fa-masked.CVS-to-avg35.glmdir --mgz

The location of the stacked volumes of all the subjects is indicated with the '--y' flag. We then pass the name of the fsgd text file using the '--fsgd' flag. The 'dods' flag tells the command that the fsgd is setup to have (d)ifferent (o)ffset, (d)ifferent (s)lope (more info here). Next we pass the command the name of the contrast text file using the '--C' flag. Lastly, we indicate the output directory name and the desired fileformat (default is .mgh) using the '--glmdir' and '--mgz' flags, respectively.

To see a script which could be used to do the series of command steps above, take a look at the 'GroupAnalysis.csh' script on this page.

freeview -v $TUTORIAL_DIR/GLM/Average.fa-masked.CVS-to-avg35.Input.mgz \
            $TUTORIAL_DIR/GLM/gender_age.fa-masked.CVS-to-avg35.glmdir/contrast/sig.mgz:colormap=heat

This command will display the uncorrected significance map values for the group analysis. With the 'sig' volume highlighted in the Freeview window, you can examine the siginificance values for every voxel by hovering over the voxel with your cursor. The significance value will be displayed in the lower right corner and will change dynamically as you move your cursor around the volume. The map has signed -log10(p) values. So, if the p-value = .01, -log10(p) = 2. If the contrast was positive, then the value would be +2, if negative, then the value would be -2.

Coronal view of the group analysis results depicting the effect of gender on fractional anisotropy:

Be sure to close the Freeview window when you are finished viewing the data.

Links Of Interest

TrackVis

Acknowledgements

DTI tutorial scripts created by Lilla Zollei.