This tutorial will take you through the steps necessary to run TRACULA (TRActs Constrained by UnderLying Anatomy). You will learn how to set up a configuration file, how to run the analyses, and how to view the results.
If you are 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 each new terminal window you open throughout this tutorial. Copy and paste the commands below to get started:
export 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 to paste the command (or use keyboard shortcut Ctrl+Shift+v). Press enter to run the command.
These two commands set the SUBJECTS_DIR variable to the directory where the recon-all structural data is stored and then navigates into the directory with the TRACULA data. You can now skip ahead to the tutorial (below the gray line).
If you are 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:
## bash export FREESURFER_HOME=/path/to/freesurfer source $FREESURFER_HOME/SetUpFreeSurfer.sh export TUTORIAL_DATA=<path_to_your_tutorial_data> export SUBJECTS_DIR=$TUTORIAL_DATA/diffusion_recons cd $SUBJECTS_DIR ## tcsh setenv FREESURFER_HOME /path/to/freesurfer source $FREESURFER_HOME/SetUpFreeSurfer.csh setenv TUTORIAL_DATA <path_to_your_tutorial_data> setenv SUBJECTS_DIR $TUTORIAL_DATA/diffusion_recons cd $SUBJECTS_DIR
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.
IMPORTANT: Check to make sure you have the latest version of FreeSurfer available before running this tutorial as Tracula is updated with new FreeSurfer version. To see the latest Tracula updates, click here.
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 written in C shell, so you can create it with any text editor (gedit, vi, emacs, etc). On a Mac, run open -e to open a text file. 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/dmrirc.tutorial &
NOTE: on Macs, run the following command:
open -e $TUTORIAL_DATA/diffusion_tutorial/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 # If original DICOMs don't exist, these can be in other image format # but then the gradient table and b-value table must be specified (see below) # set dcmlist = ( $TUTORIAL_DATA/diffusion_tutorial/elmo.2005/orig/656000-11-1.dcm \ $TUTORIAL_DATA/diffusion_tutorial/elmo.2008/orig/97000-000017-000001.dcm \ $TUTORIAL_DATA/diffusion_tutorial/elmo.2012/orig/MR.22.214.171.124.1126.96.36.199.35006.2012121819455034689828982 ) # Diffusion gradient tables (if there is a different one for each scan) # Must be specified if they cannot be read from the DICOM headers # The tables must have either three columns, where each row is a gradient vector # or three rows, where each column is a gradient vector # There must be as many gradient vectors as volumes in the diffusion data set # Default: Read from DICOM header # set bveclist = ( $TUTORIAL_DATA/diffusion_tutorial/elmo.2005/orig/gradients.txt \ $TUTORIAL_DATA/diffusion_tutorial/elmo.2008/orig/gradients.txt \ $TUTORIAL_DATA/diffusion_tutorial/elmo.2012/orig/gradients.txt ) # Diffusion b-value tables (if there is a different one for each scan) # Must be specified if they cannot be read from the DICOM headers # There must be as many b-values as volumes in the diffusion data set # Default: Read from DICOM header # set bvallist = ( $TUTORIAL_DATA/diffusion_tutorial/elmo.2005/orig/bvalues.txt \ $TUTORIAL_DATA/diffusion_tutorial/elmo.2008/orig/bvalues.txt \ $TUTORIAL_DATA/diffusion_tutorial/elmo.2012/orig/bvalues.txt ) set runlist = (1 2 3) set doeddy = 1 set dorotbvecs = 1 set usemaskanat = 1 set thrbet = 0.3 set doregflt = 0 set doregbbr = 1 set doregmni = 1 set doregcvs = 0 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 ) set ncpts = (6 6 5 5 5 5 7 5 5 5 5 5 4 4 5 5 5 5)
This a very simple configuration file, where only the basic inputs are specified. We will now go through the options specified in the file above.
Do not run the rest of the commands on this page!
These are just the commands that would go into a configuration file, and are listed and explained here as an example.
Step 2: Specify the FreeSurfer subject directory
setenv SUBJECTS_DIR $TUTORIAL_DATA/diffusion_recons
This 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 the list of 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 the 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 the list of input DWIs
set dcmlist = ( elmo.2005/orig/656000-11-1.dcm \ elmo.2008/orig/97000-000017-000001.dcm \ elmo.2012/orig/MR.188.8.131.52.1184.108.40.206.35006.2012121819455034689828982 )
Use this variable to specify the input DWI data, one entry per subject. The file names are assumed to 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 DICOM files where the diffusion-encoding gradients and b-values are stored in a standard location in the DICOM header, these will be read from the header. For non-standard DICOM formats or for files formats other than DICOM, you will need to specify the location of the diffusion-encoding gradient table (see bvecfile or bveclist below) and the b-value table (see bvalfile or bvallist below).
In addition to the basic options in the simple configuration file above, there are several other options that you can use to customize data processing for your study. These are listed in a more extensive example configuration file, which is also available as part of the FreeSurfer distribution. We will now go through some of these additional options.
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 a specific 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.
Step 8: Specify the diffusion-encoding gradient table
You can specify either a different gradient table for each of the scans in the study (with bveclist) or a single gradient table for all scans in the study (with bvecfile).
To specify a different gradient table for each of the scans in the study:
set bveclist = ( /path/to/subject/bvecs.txt \ /path/to/subject/bvecs.txt \ /path/to/subject/bvecs.txt )
Note that the naming convention does not need to be bvecs.txt. Your bvec file can be named gradients.txt, as in the dmrirc.tutorial file, above. However, you need to make sure this file is formatted correctly (continue reading to the end of this section for more info).
To specify a single gradient table for all scans in the study:
set bvecfile = /path/to/bvecs.txt
Use either one of these variables to specify the location of the gradient table(s), if your DWI data is not in a DICOM format that allows mri_convert to read the gradients from the header.
A gradient table must be saved in a simple text file either in three-column format (one row for each volume in the DWI series) or in three-row format (one column for each volume in the DWI series). An example is shown below:
0 0 0 0 0 0 0 0 0 0.707 0 0.707 -0.707 0 0.707 0 0.707 0.707 0 0.707 -0.707 0.707 0.707 0 -0.707 0.707 0
In this example the first 3 rows of the gradient table are all zero, indicating that 3 low-b (non-diffusion-weighted) volumes were acquired first, while the remaining 6 rows correspond to 6 diffusion-weighted volumes acquired with different diffusion-encoding gradients.
Step 9: Specify the b-value table
You can specify either a different b-value table for each of the scans in the study (with bvallist) or a single b-value table for all scans in the study (with bvalfile).
To specify a different b-value table for each of the scans in the study:
set bvallist = ( /path/to/subject/bvals.txt \ /path/to/subject/bvals.txt \ /path/to/subject/bvals.txt )
Note that the naming convention does not need to be bvals.txt. Your bvec file can be named bvalues.txt, as in the dmrirc.tutorial file, above. However, you need to make sure this file is formatted correctly (continue reading to the end of this section for more info).
To specify a single b-value table for all scans in the study:
set bvalfile = /path/to/bvals.txt
Use either one of these variables to specify the location of the b-value table(s), if your DWI data is not in a DICOM format that allows mri_convert to read the b-values from the header.
The b-value table must be saved in a simple text file, one value for each volume in the DWI series. An example is shown below:
0 0 0 1000 1000 1000 1000 1000 1000
In this example the DWI series would include 3 non-diffusion-weighted (b=0) images, followed by 6 diffusion-weighted images acquired with b=1000mm^-2.
Step 10: Specify if eddy-current compensation will be performed
set doeddy = 1
Use this variable to specify if eddy-current compensation (commonly referred to as eddy-current correction) will be performed as part of DWI pre-processing. This compensation consists of an affine registration of all DWIs to the first image in the series using FSL's eddy_correct, which is meant to mitigate distortions due to eddy currents and head motion. By default this variable is set to 1, so eddy-current compensation is performed. Set it to 0 to disable it.
Step 11: Specify if the gradients will be rotated to match eddy-current compensation
set dorotbvecs = 1
Use this variable to specify if the vectors in the diffusion-encoding gradient table will be rotated to match the rotations applied to the corresponding images by the eddy-current compensation. This is recommended if eddy-current compensation is performed.
Step 12: Specify if an anatomical brain mask will be used
set usemaskanat = 1
Use this variable to specify if the T1-weighted scan will be used to extract the brain mask instead of the DWI scan. If this is set to 1, which is the default, the brain mask will be obtained by dilating the aparc+aseg.mgz from the FreeSurfer segmentation and then mapping it to DWI space. The aparc+aseg.mgz is used because it is created towards the end of the FreeSurfer processing steam and is therefore a more accurate volume to use as a mask. Dilating the aparc+aseg.mgz involves increasing the volume by a few voxels. To use a mask derived by thresholding the DWI scan instead, set this to 0.
Step 13: Set the threshold for DWI-based brain mask extraction
set thrbet = 0.3
Use this variable to set the threshold for creating a brain mask from the DWIs using FSL's Brain Extraction Tool (BET). This value is specified as a fraction of the maximum image intensity, so it must be a number between 0 and 1. The default is 0.3. Note that by default the brain mask used by TRACULA is extracted from the T1-weighted images, not the DWIs, in which case this variable will not have much of an effect on the analysis (see usemaskanat above).
Step 14: Specify the intra-subject registration method
There are two options for registering each subject's DWIs to the subject's own T1-weighted image: bbregister or FSL's FLIRT. They both perform affine registration but bbregister also uses the FreeSurfer surface reconstruction to optimize the affine registration between the diffusion and anatomical scan.
The following selects the default option, which is to use bbregister and not FLIRT:
set doregflt = 0 set doregbbr = 1
To use FLIRT and not bbregister, set doregflt to 1 and doregbbr to 0. If you do not have a preference and want the analysis performed with both options for comparison purposes, set both of these variables to 1 (this will take longer and create two sets of outputs).
Step 15: Specify the inter-subject registration method
There are two options for registering each subject to the tract atlas used by TRACULA: affine registration to the MNI template (MNI152) or nonlinear registration to the CVS template (cvs_avg35). Although TRACULA performs tractography in each subject's own native diffusion space, this inter-subject registration is needed to map the individual to the tract atlas that TRACULA's anatomical priors are derived from. Note that the prior information extracted from this atlas is not the exact spatial location of the tracts, but the IDs of the anatomical segmentation labels that the tracts go through or next to. Thus, a rough spatial alignment is sufficient for these anatomical priors to be accurate. However, another purpose for which the mapping to a common template is used is to choose an initial guess of the tract location to initialize TRACULA. If the study subject's anatomy is significantly different from that of a normal population, this initialization may be more accurate when nonlinear registration is used.
The following selects the default options, which is to use MNI and not CVS registration:
set doregmni = 1 set doregcvs = 0
To use CVS and not MNI registration, set doregcvs to 1 and doregmni to 0 (this will take much longer). If you do not have a preference and want the analysis performed with both options for comparison purposes, set both of these variables to 1 (this will take even longer).
It is possible to specify the location of MNI template. If it is not specified, this will be assumed by default:
set mnitemp = $FSLDIR/data/standard/MNI152_T1_1mm_brain.nii.gz
It is also possible to specify the location of CVS template. If it is not specified, this will be assumed by default:
set cvstemp = cvs_avg35 set cvstempdir = $FREESURFER_HOME/subjects
Step 16: Specify which white-matter pathways to reconstruct
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 )
Use this variable to specify which of the 18 pathways included in the TRACULA tract atlas to reconstruct. The default is to reconstruct all 18 pathways, defined below:
- lh.cst_AS: Left corticospinal tract
- rh.cst_AS: Right corticospinal tract
- lh.ilf_AS: Left inferior longitudinal fasciculus
- rh.ilf_AS: Right inferior longitudinal fasciculus
- lh.unc_AS: Left uncinate fasciculus
- rh.unc_AS: Right uncinate fasciculus
- fmajor_PP: Corpus callosum - forceps major
- fminor_PP: Corpus callosum - forceps minor
- lh.atr_PP: Left anterior thalamic radiations
- rh.atr_PP: Right anterior thalamic radiations
- lh.ccg_PP: Left cingulum - cingulate gyrus endings
- rh.ccg_PP: Right cingulum - cingulate gyrus endings
- lh.cab_PP: Left cingulum - angular bundle
- rh.cab_PP: Right cingulum - angular bundle
- lh.slfp_PP: Left superior longitudinal fasciculus - parietal endings
- rh.slfp_PP: Right superior longitudinal fasciculus - parietal endings
- lh.slft_PP: Left superior longitudinal fasciculus - temporal endings
- rh.slft_PP: Right superior longitudinal fasciculus - temporal endings
Step 17: Specify the number of path control points
set ncpts = (6 6 5 5 5 5 7 5 5 5 5 5 4 4 5 5 5 5)
Use this variable to specify the number of control points that will be used to model each of the pathways in pathlist as a spline. Any number greater than 2 is a valid choice but, as a rule of thumb, a fairly straight pathway can be modeled using only a few control points, whereas a highly curved pathway may require more control points. The default, as shown above, is to use 7 for the forceps major, 6 for the corticospinal tract, 4 for the angular bundle, and 5 for all other pathways.
In TRACULA the control points are perturbed (moved just a little bit) many times to create a distribution of curves. The exact number of perturbations is defined by the nsamples in the config file - the default is set to 7500. For each of these curves, we find which explain the diffusion data well and which do not. Those that do are accepted and the others are rejected. The accepted curves are all added up to give you the heat map that you see when you view path.pd.nii.gz (pd = probability distribution).
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.
By the end of this page, you should know how to:
- Create a configuration file
- Supply the correct steps/parameters for processing
- Set additional options depending on the specifics of your analysis