Top | Next

TRACULA Tutorial

This tutorial will take you through the steps necessary to run TRACULA (TRActs Constrained by UnderLying Anatomy) on a set of subjects. You will learn how to set up a configuration file, how to run TRACULA, and how to view the results.

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
cd $TUTORIAL_DATA/diffusion_tutorial

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.


Setting Up A Configuration File

An example configuration file for TRACULA is included in the FreeSurfer distribution at $FREESURFER_HOME/bin/dmrirc.example and it is also available on the wiki. The configuration file is a Unix shell script where you set variables to specify the location of the input data and various processing preferences. If you run TRACULA without a configuration file, then you will only be able to use the default processing options. Below we explore the options that are set in the tutorial configuration file and some additional options that you may want to set depending on the specifics of your analysis.

Step 1: Create a configuration file. This is a simple text file, so you can create it with any text editor (gedit, vi, emacs, etc). For the purposes of this tutorial, we have already created a configuration file called dmrirc.tutorial. Open this file to see the example and follow along as we explain the commands:

gedit $TUTORIAL_DATA/diffusion_tutorial/scripts/dmrirc.tutorial &

Note that lines preceded by the # sign are "comments" and so will not be run as commands. The # symbol can be handy for adding descriptions of what each command will do, or to "comment out" commands that you want to disable temporarily. The tutorial configuration file looks like this:

# FreeSurfer SUBJECTS_DIR
# T1 images and FreeSurfer segmentations are expected to be found here
#
setenv SUBJECTS_DIR $TUTORIAL_DATA/diffusion_recons

# Output directory where trac-all results will be saved
# Default: Same as SUBJECTS_DIR
#
set dtroot = $TUTORIAL_DATA/diffusion_tutorial

# Subject IDs
#
set subjlist = ( elmo.2005 \
                 elmo.2008 \
                 elmo.2012 )

# Input diffusion DICOMs (file names relative to dcmroot)
# If original DICOMs don't exist, these can be in other image format
# but then bvecfile and bvalfile must be specified
#
set dcmroot = $TUTORIAL_DATA/diffusion_tutorial
set dcmlist = ( elmo.2005/orig/656000-11-1.dcm \
                elmo.2008/orig/97000-000017-000001.dcm \
                elmo.2012/orig/MR.1.3.12.2.1107.5.2.32.35006.2012121819455034689828982 )

This is the simplest configuration file possible, where only the most basic inputs are specified. We will now go through the options specified in the file above.


Step 2: Specify the FreeSurfer subject directory

setenv SUBJECTS_DIR $TUTORIAL_DATA/diffusion_recons

The SUBJECTS_DIR variable must be set to the directory where all the subjects' FreeSurfer reconstructions are located. It is assumed that FreeSurfer has already been run on the subjects' T1-weighted data. TRACULA will use the aparc+aseg.mgz from each subject's FreeSurfer reconstruction - this is where the "underlying anatomy" part of TRACULA comes from.


Step 3: Specify the TRACULA output directory

set dtroot = $TUTORIAL_DATA/diffusion_tutorial

Use this variable to specify the directory where the TRACULA outputs for all subjects will be saved. If this is not specified, results will be saved under $SUBJECTS_DIR by default.


Step 4: Specify subject IDs

set subjlist = (elmo.2005 elmo.2008 elmo.2012)

Use this variable to specify the ID of all the subjects you want to process with TRACULA. This can be a single subject, or it can be multiple subjects for batch processing.


Step 5: Specify location of diffusion DICOM files

set dcmroot = $TUTORIAL_DATA/diffusion_tutorial

Use this variable to specify the directory under which the diffusion DICOM files for all subjects can be found.


Step 6: Specify list of input DWIs

set dcmlist = ( elmo.2005/orig/656000-11-1.dcm \
                elmo.2008/orig/97000-000017-000001.dcm \
                elmo.2012/orig/MR.1.3.12.2.1107.5.2.32.35006.2012121819455034689828982 )

Use this variable to specify the input DWI data, one entry per subject. The file names are assumed be relative to the directory specified in dcmroot above. If DICOM files are available, you just need to specify the first DICOM file in the series that contains the DWIs, assuming the remaining DICOM files from the same series are in the same directory. If your DWIs are in a format other than DICOM, you can still specify the DWI volumes here, as long as they are in a format that can be read by mri_convert. For DICOMs acquired with the standard Siemens diffusion sequences, the diffusion-encoding gradient table and the b-value table will be determined based on information in the DICOM header. For DICOM files acquired with other sequences or for files formats other than DICOM, you will need to specify the location of the diffusion-encoding gradient table and the b-value table (see below).


Step 7: Specify which subjects to analyze

set runlist = (2 3)

Use this variable if you only want to run the analysis on a subset of the subjects included in subjlist. The example above would run the analysis only on the second and third subject. This is useful if, e.g., you need to rerun part of the analysis on a few of your subjects only. If this variable is not set, the analysis will be run on all subjects by default.


Step7.1: Specifying Diffusion bvalue Table The b-value file must be in single-column format with one value for each volume in the diffusion data set. For example, if your data set includes 3 non-diffusion-weighted (b=0) images followed by 6 diffusion-weighted images acquired with b=1000mm^-2, then you would create a bvals.txt file that looks like this: (You do not need to copy/paste the text below into the terminal window, the b-value file has already been created for you).

0
0
0
1000
1000
1000
1000
1000
1000

In the configuration file, you would need to specify the location of the b-value file, like so:

set bvalfile = /path/to/bvals.txt


Step7.2: Specifying Diffusion Gradient Table The diffusion gradient table file must be in three-column format, one row for each volume in the diffusion data set. The first three rows of the gradient table example below are 0s because as in the example above, 3 low-b (non-diffusion-weighted) volumes were collected. The remaining values are determined based on the scanner. (You do not need to copy/paste the text below into the terminal window, the gradient table file has already been created for you).

 0  0  0
 0  0  0
 0  0  0
 1  0  1
-1  0  1
 0  1  1
 0  1 -1
 1  1  0
-1  1  0

As with the bvals.txt, the gradient table must also be specified in the configuration file as the following:

set bvecfile = /path/to/bvecs.txt


Step8: Perform Eddy Current Correction

set doeddy = 1

This step specifies if TRACULA will perform eddy current correction on the image data. This correction compensates for distortions caused due to eddy currents from gradient coils and slight head motion. It performs an affine registration of each volume in the dataset to the low-b volume. Setting this variable (and most of those remaining in this tutorial) to 1 means that this step will be done. If you do not want it to be done, set it to 0.


Step9: Rotate Diffusion Gradients

set dorotbvecs = 1

This step specifies if TRACULA will rotate the diffusion gradient table to match the eddy current compensation.


Step10: Set BET Threshold

set thrbet = 0.3

This step sets the threshold for skull stripping in FSL's Brain Extraction Tool (BET) to get the skull-stripped low-b images. This value is specified as a fraction of the maximum image intensity and can range from 0.0 to 1.0. The default is 0.3.


Step11: Set Registration Method For Resampling Diffusion To T1 To register the diffusion data to the structural data, you can choose either FSL's FLIRT or FreeSurfer's bbregister (or do both for comparison purposes) from within the configuration file. If you would like to use only FLIRT to perform the diffusion-to-T1 registration, set the FLIRT variable (doregflt) to 1 and the bbregister variable (doregbbr) to 0:

set doregflt = 1
set doregbbr = 0

To perform the diffusion-to-T1 registration using only bbregister, do the opposite:

set doregflt = 0
set doregbbr = 1

When both these variables are set to '1', TRACULA computes transformations using both FLIRT and bbregister.


Step12: Registration To A Common Template With this step, you specify which common template to register the diffusion data to (MNI template). Although tractography is performed in the subject's native diffusion place, this inter-subject registration is needed to map the individual to the training set where TRACULA's anatomical priors are derived from. To register diffusion data to MNI space, set doregmni to 1 and specify the location of the template:

set doregmni = 1

Setting the path of the MNI template, this is the default:

set mnitemp = $FSLDIR/data/standard/MNI152_T1_1mm_brain.nii.gz


Step13: Set Up A Training File The training file consists of a collection of normal subjects whose major white matter bundles were delineated manually by trained raters. These manual labels serve as an atlas for guiding the automated tractography in TRACULA. These training subjects are supplied with your FreeSurfer distribution and the full list, used by default, is $FREESURFER_HOME/trctrain/trainlist.txt. You would specify this file with the command below:

set trainfile = $TUTORIAL_DATA/diffusion_tutorial/subj,train,difftutorial23.txt


Step14: Specify Paths To Reconstruct This option allows us to specify the paths we want to reconstruct for the given subject. The default is to reconstruct the complete set of paths, defined below.

set pathlist = (lh.cst_AS rh.cst_AS \
        lh.ilf_AS rh.ilf_AS \
        lh.unc_AS rh.unc_AS \
        fmajor_PP fminor_PP \
        lh.atr_PP rh.atr_PP \
        lh.cab_PP rh.cab_PP \
        lh.ccg_PP rh.ccg_PP \
        lh.slfp_PP rh.slfp_PP \
        lh.slft_PP rh.slft_PP)


Step15: Specify Number Of Path Control Points This option allows us to specify the number of control points along the length of the tract. A fairly straight pathway may be well-defined by a few control points, whereas a highly curved pathway may require more control points. The default is 5 but you may choose any number greater than 2 using the variable below.

set ncpts = 5


Now that the configuration file is all set, you can run TRACULA! Hit Next below to move on to the next part of the tutorial.

Top | Next