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.
Please bear with us while we update the tutorial data set for the new version of TRACULA. The new tutorial goes beyond what was possible with the tutorial data set that was previously available for download. For now, please ignore any references to the tutorial data and try to follow along using your own data. Thank you for your patience.
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_tutorial/fs 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_tutorial/fs 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: Please make sure that you have the latest version of FreeSurfer installed, including the latest TRACULA updates, before running this tutorial.
Setting up a configuration file
Example configuration files for TRACULA are included in the FreeSurfer distribution at $FREESURFER_HOME/bin/dmrirc*example and are 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 bare minimum options that you have to set in the configuration file, as well as 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 that contains Unix (C shell) commands. 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_tutorial/fs # Output directory where trac-all results will be saved # Default: Same as SUBJECTS_DIR # set dtroot = $TUTORIAL_DATA/diffusion_tutorial/trc # Subject IDs # set subjlist = ( subject1 \ subject2 \ subject3 ) # 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/raw/subject1/dwi1/XXX-1.dcm \ $TUTORIAL_DATA/diffusion_tutorial/raw/subject2/dwi1/XXX-1.dcm \ $TUTORIAL_DATA/diffusion_tutorial/raw/subject3/dwi1/XXX-1.cdm ) # 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/raw/subject1/dwi1/gradients.txt \ $TUTORIAL_DATA/diffusion_tutorial/raw/subject2/dwi1/gradients.txt \ $TUTORIAL_DATA/diffusion_tutorial/raw/subject3/dwi1/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/raw/subject1/dwi1/bvalues.txt \ $TUTORIAL_DATA/diffusion_tutorial/raw/subject2/dwi1/bvalues.txt \ $TUTORIAL_DATA/diffusion_tutorial/raw/subject3/dwi1/bvalues.txt )
This a very simple configuration file, where only the absolutely necessary inputs are specified. We will now go through the options specified in the file above.
NOTE: A backslash (\) in a Unix script indicates that the same command continues onto the following line. It can be used as above to make the configuration file (or, indeed, any Unix script) more readable. However, it is optional; you could list all the contents of a variable in a single line instead. If you do use a backslash, it must be the very last character on its line, with no white space or other characters following it.
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_tutorial/fs
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/trc
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 = (subject1 subject2 subject3)
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/raw
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 = ( subject1/dwi1/XXX-1.dcm \ subject2/dwi1/XXX-1.dcm \ subject3/dwi1/XXX-1.dcm )
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. In that case, you do NOT need to specify anything else in your configuration file.
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 bveclist below) and the b-value table (see 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 more extensive example configuration files, which are also available as part of the FreeSurfer distribution. We will now go through some of these additional options.
Step 7: Specify a subset of scans 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 tables
You can specify the gradient table that corresponds to each of the scans in the study with bveclist. For example:
set bveclist = ( subject1/dwi1/bvecs.txt \ subject2/dwi1/bvecs.txt \ subject3/dwi1/bvecs.txt )
Use this variable to specify the location of the gradient tables, if your DWI data are not in a DICOM format that allows mri_convert to read the gradients from the header. The paths specified here are either relative paths with respect to the dcmroot directory, if the latter is specified, or absolute paths otherwise.
Each gradient table must be a simple text file, either in three-column format (one row for each volume in the corresponding DWI scan) or in three-row format (one column for each volume in the corresponding DWI scan). 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 tables
You can specify the b-value table that corresponds to each of the scans in the study with bvallist. For example:
set bvallist = ( subject1/dwi1/bvals.txt \ subject2/dwi1/bvals.txt \ subject3/dwi1/bvals.txt )
Use either this variables to specify the location of the b-value tables, if your DWI data are not in a DICOM format that allows mri_convert to read the b-values from the header. The paths specified here are either relative paths with respect to the dcmroot directory, if the latter is specified, or absolute paths otherwise.
Each b-value table must be a simple text file, with one value for each volume in the corresponding DWI scan. 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=1000.
Step 10: Specify a method for compensating for B0 inhomogeneity distortions
To specify if you want to compensate for B0 inhomogeneity distortions, use the dob0 variable. Possible options are 0 (none), 1 (using field maps), or 2 (using reverse-polarity images). Depending on which method you choose, you may need to provide additional inputs.
To skip this (default):
set dob0 = 0
To use field maps:
set dob0 = 1 set b0mlist = (subject1/fmag/XXX-1.dcm subject2/fmag/XXX-1.dcm subject3/fmag/XXX-1.dcm) set b0plist = (subject1/fphas/XXX-1.dcm subject2/fphas/XXX-1.dcm subject3/fphas/XXX-1.dcm) set echospacing = 0.7
This option calls epidewarp.fsl. To use it, your scan protocol must include a field mapping sequence. You must specify the following in the configuration file:
b0mlist: The paths to the input B0 field map magnitude DICOMs (can be absolute or relative to dcmroot)
b0plist: The paths to the input B0 field map phase DICOMs (can be absolute or relative to dcmroot)
echospacing: The echo spacing (is found in the scanner protocol printout)
The paths specified here are either relative paths with respect to the dcmroot directory, if the latter is specified, or absolute paths otherwise.
To use reverse-polarity images:
set dob0 = 2 set subjlist = ( subject1 subject1 subject2 subject2 subject3 subject3 ) set dcmlist = ( subject1/dwi1/XXX-1.dcm \ subject1/dwi2/XXX-1.dcm \ subject2/dwi1/XXX-1.dcm \ subject2/dwi2/XXX-1.dcm \ subject3/dwi1/XXX-1.dcm \ subject3/dwi2/XXX-1.dcm ) set pedir = ( AP PA AP PA AP PA ) set echospacing = 0.35 set epifactor = 140
This option calls FSL's topup. To use it, your scan protocol must include more than one DWI scan, and these scans must be collected with different phase-encode directions. These scans may or may not contain the same number of directions. For example, you may have collected your full DWI series twice, once with phase-encode direction A->P and once with phase-encode direction P->A; or you may have collected your full DWI series with phase-encode direction A->P and only the b=0 volume with phase-encode direction P->A.
Note that, because you now have more than one DWI scan per subject, each subject ID shows up more than once in the subjlist. In the example above, each subject ID shows up twice in the subjlist because there are two scans for each subject in the dcmlist (.../dwi1/... and .../dwi2/...). In this example, these are two scans that were collected with opposite phase-encode direction (AP and PA) and can thus be passed to topup to estimate the off-resonance field map.
You must also specify the following in the configuration file:
pedir: The phase-encode direction, one for each DWI scan in dcmlist (is found in the scanner protocol printout)
echospacing: The echo spacing (is found in the scanner protocol printout)
epifactor: The EPI factor (is found in the scanner protocol printout)
An example configuration file for the case where you have more than one DWI scan per session is included in the FreeSurfer distribution at $FREESURFER_HOME/bin/dmrirc.multiscan.example and is also available on the wiki.
Step 11: Specify a method for compensating for eddy-current distortions
set doeddy = 2
The default is to use eddy. Set doeddy to 0 to disable it.
Step 12: Specify the intra-subject registration method
The intra-subject registration (from each subject's DWIs to the subject's own T1-weighted image) can be done either with bbregister or with 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 T1 scan.
To specify the intra-subject registration method in the configuration file, use the intrareg variable:
set intrareg = 3
The options are 1 (FLIRT with a correlation ratio cost), 2 (FLIRT with a mutual information cost), and 3 (bbregister, which uses a boundary-based cost). The default is option 3 (bbregister).
For additional configuration options related to the intra-subject registration method, such as the degrees of freedom and the maximum rotation angle, see the example configuration files.
Step 13: Specify the inter-subject registration method
The inter-subject registration (from each subject to a common space) can be done either with affine or with nonlinear methods. Although TRACULA performs tractography in each subject's own native diffusion space, this inter-subject registration is needed to map the individual to the manually annotated training set of streamlines that TRACULA's anatomical priors are derived from. Note that the prior information extracted from this training set is not the exact coordinates of the tracts the common space, 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 space 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.
To specify the inter-subject registration method in the configuration file, use the interreg variable:
set interreg = 5
The options are 1 (affine registration from the individual T1 to the MNI T1 template with FLIRT and a correlation ratio cost), 2 (affine registration from the individual T1 to the MNI T1 template with FLIRT and a mutual information cost), 3 (affine registration from the individual T1 to a custom T1 template with mri_robust_register and a robust cost), 4 (nonlinear registration from the individual T1 to the cvs_avg35 T1 template with CVS), or 5 (nonlinear registration from the individual FA map to a custom FA template with symmetric normalization from ANTs). The default is option 5 (ANTs).
For additional configuration options related to the inter-subject registration method, such as the path to the template, see the example configuration files.
Step 14: Specify which white-matter pathways to reconstruct
To specify which of the 42 pathways included in the TRACULA tract atlas to reconstruct, use the pathlist variable:
set pathlist = ( lh.uf rh.uf cc.rostrum )
The default is to reconstruct the full set of 42 pathways. The abbreviated names for these pathways, as they should be specified in pathlist, are given in the first column of $FREESURFER_HOME/trctrain/hcp/pathlist.txt.
Step 15: Specify the number of path control points
set ncpts = ( 7 7 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 numbers of controls points have been chosen to be proportional to the length of each pathway, and are given in the last column of $FREESURFER_HOME/trctrain/hcp/pathlist.txt.
TRACULA runs a random sampling algorithm, which perturbs these control points repeatedly to draw samples from the underlying probability distribution of the pathway. The exact number of sample paths to draw can be specified in the configuration file using the nsamples variable (the default is 7500). Sample paths are retained if they fit both the diffusion data and the anatomical neighborhood priors well, and rejected otherwise. The accepted paths are added up to give the heat map that you see when you view path.pd.nii.gz (pd = probability distribution), as desribed later in this tutorial.
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 necessary input files for processing
- Set additional options depending on the specifics of your analysis