Back to list of all tutorials | Back to course page | Next

TRACULA tutorial

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.

Preparations

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/tracula_tutorial/fs
cd $TUTORIAL_DATA/tracula_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 are 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 TRACULA 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/tracula_tutorial/fs
cd $TUTORIAL_DATA/tracula_tutorial

## 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/tracula_tutorial/fs
cd $TUTORIAL_DATA/tracula_tutorial

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 TRACULA, before running this tutorial.

Setting up a configuration file

If your data are organized according to the BIDS standard, you can run dmri_bids_config to generate the TRACULA configuration file automatically (see step 1a below). Otherwise, you will have to create the TRACULA configuration file yourself (see step 1b below).

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 1a: Create a configuration file (if your data are in BIDS format). Run the following command, specifying the top-level location of your BIDS-formatted dataset (here, $TUTORIAL_DATA/tracula_tutorial/bids) and the name of the configuration file that will be created (here, dmrirc.tutorial):

dmri_bids_config --in $TUTORIAL_DATA/tracula_tutorial/bids --c dmrirc.tutorial

You can skip the following steps and move on to the next page in the tutorial, or keep reading if you want to know how to modify the configuration file to change any of the analysis options.

Step 1b: Create a configuration file (if your data are not in BIDS format). The configuration file is a simple text file, so you can create it or modify 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/tracula_tutorial/dmrirc.tutorial &

NOTE: on Macs, run the following command:

open -e $TUTORIAL_DATA/tracula_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/tracula_tutorial/fs

# Output directory where trac-all results will be saved
#
set dtroot = ($TUTORIAL_DATA/tracula_tutorial/trc)

# Subject IDs
#
set subjlist = (sub-BANDA001 sub-BANDA001 sub-BANDA002 sub-BANDA002)

# Input DWI volumes (file names relative to dcmroot)
#
set dcmroot = ($TUTORIAL_DATA/tracula_tutorial/bids)
set dcmlist = (sub-BANDA001/dwi/sub-BANDA001_run-dir98_AP_dwi.nii.gz sub-BANDA001/dwi/sub-BANDA001_run-dir98_PA_dwi.nii.gz sub-BANDA002/dwi/sub-BANDA002_run-dir98_AP_dwi.nii.gz sub-BANDA002/dwi/sub-BANDA002_run-dir98_PA_dwi.nii.gz)

# Input gradient tables (file names relative to dcmroot)
#
set bveclist = (sub-BANDA001/dwi/sub-BANDA001_run-dir98_AP_dwi.bvec sub-BANDA001/dwi/sub-BANDA001_run-dir98_PA_dwi.bvec sub-BANDA002/dwi/sub-BANDA002_run-dir98_AP_dwi.bvec sub-BANDA002/dwi/sub-BANDA002_run-dir98_PA_dwi.bvec)

# Input b-value tables (file names relative to dcmroot)
#
set bvallist = (sub-BANDA001/dwi/sub-BANDA001_run-dir98_AP_dwi.bval sub-BANDA001/dwi/sub-BANDA001_run-dir98_PA_dwi.bval sub-BANDA002/dwi/sub-BANDA002_run-dir98_AP_dwi.bval sub-BANDA002/dwi/sub-BANDA002_run-dir98_PA_dwi.bval)

This is what a basic configuration file would look like, if only the absolutely necessary inputs were specified. We will now go through these inputs, as well as other, more advanced ones, one by one.

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.

Step 2: Specify the FreeSurfer subject directory

setenv SUBJECTS_DIR $TUTORIAL_DATA/tracula_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/tracula_tutorial/trc

Use this variable to specify the directory where the TRACULA outputs for all subjects will be saved. You can skip this line, in which case the TRACULA outputs will be saved under $SUBJECTS_DIR, together with the outputs of recon-all.

Step 4: Specify the list of subject IDs

set subjlist = (sub-BANDA001 sub-BANDA002)

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. If each subject has 1 diffusion scan, then each subject's ID will show up only once here. If each subject has N diffusion scans, then each subject's ID will just show up N times here (in the example config file above, N=2).

Step 5: Specify the location of the diffusion scans

set dcmroot = $TUTORIAL_DATA/tracula_tutorial/bids

Use this variable to specify the top-level directory under which the diffusion scans (DICOM or NIfTI files) for all subjects can be found.

Step 6: Specify the list of input DWIs

set dcmlist = (sub-BANDA001/dwi/sub-BANDA001_dwi.nii.gz sub-BANDA002/dwi/sub-BANDA002_dwi.nii.gz)

Use this variable to specify the input DWI volumes. There have to be as many scans here as entries in the subjlist above. 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 (e.g., NIfTI, or any format that can be read by mri_convert), you would still specify them here.

If your input DWIs are DICOM files, and 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.

If your input DWIs are in another format (e.g., NIfTI) or in a non-standard DICOM format, 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 = (3 4)

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 third and fourth scan (assuming there are at least 4 scans listed in the config file). 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 scans listed in the config file.

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 = (sub-BANDA001/dwi/sub-BANDA001_dwi.bvec sub-BANDA002/dwi/sub-BANDA002_dwi.bvec)

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. If you are using this, there have to be as many files listed here as entries in the subjlist above.

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 = (sub-BANDA001/dwi/sub-BANDA001_dwi.bval sub-BANDA002/dwi/sub-BANDA002_dwi.bval)

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. If you are using this, there have to be as many files listed here as entries in the subjlist above.

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 = (sub-BANDA001 sub-BANDA001 sub-BANDA002 sub-BANDA002)
set dcmlist = (sub-BANDA001/dwi/sub-BANDA001_run-dir98_AP_dwi.nii.gz sub-BANDA001/dwi/sub-BANDA001_run-dir98_PA_dwi.nii.gz sub-BANDA002/dwi/sub-BANDA002_run-dir98_AP_dwi.nii.gz sub-BANDA002/dwi/sub-BANDA002_run-dir98_PA_dwi.nii.gz)
set bveclist = (ssub-BANDA001/dwi/sub-BANDA001_run-dir98_AP_dwi.bvec sub-BANDA001/dwi/sub-BANDA001_run-dir98_PA_dwi.bvec sub-BANDA002/dwi/sub-BANDA002_run-dir98_AP_dwi.bvec sub-BANDA002/dwi/sub-BANDA002_run-dir98_PA_dwi.bvec)
set bvallist = (ssub-BANDA001/dwi/sub-BANDA001_run-dir98_AP_dwi.bval sub-BANDA001/dwi/sub-BANDA001_run-dir98_PA_dwi.bval sub-BANDA002/dwi/sub-BANDA002_run-dir98_AP_dwi.bval sub-BANDA002/dwi/sub-BANDA002_run-dir98_PA_dwi.bval)

set pedir = (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 (...dir98_AP_dwi.nii.gz and ...dir98_PA_dwi.nii.gz). 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

To specify if you want to compensate for eddy-current distortions, use the doeddy variable. Possible options are 0 (none), 1 (using FSL's eddy_correct), or 2 (using FSL's eddy).

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.

Summary

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

Back to list of all tutorials | Back to course page | Next