trac-all: White-matter pathway reconstruction from diffusion-weighted images (DWIs) using TRACULA


Using a configuration file to set analysis options:

trac-all -[step] -c <configfile>

Using only mandatory inputs with all default options (no configuration file needed):

trac-all -[step] -s <subjectname> --i <dicomfile>

In the above, -[step] is one or more command-line options that specify which steps of the processing to run (see details below).

For Martinos Center users:

For non-MGH acquisitions


Required Arguments

-c <dmrirc>

configuration file that specifies analysis options


-s <subjectname>

name of the subject to be analyzed (if not specified via a configuration file)

-i <file>

path to the input DWIs (if not specified via a configuration file)

In addition to the above, one of the processing step options below must be provided to specify which parts of the analysis to run.

Processing step options

Choosing which part of the analysis to do:


Run all preprocessing (steps 1.1-1.6, see below)


Run FSL's bedpost (step 2)


Run pathway reconstruction (step 3)

Performing a part of the preprocessing or skipping a part:


Run image corrections (step 1.1)


Skip step 1.1


Run intra-subject registration (step 1.2)


Skip step 1.2


Run inter-subject registration (step 1.3)


Skip step 1.3


Run mask creation (step 1.4)


Skip step 1.4


Run tensor fit (step 1.5)


Skip step 1.5


Run estimation of pathway priors (step 1.6)


Skip step 1.6

Optional arguments

Status and log files

-log <file>

Log file (default: $SUBJECTS_DIR/<your_subjectid>/scripts/trac-all.log)

-cmd <file>

Command file (default: $SUBJECTS_DIR/<your_subjectid>/scripts/trac-all.cmd)


Start new log files instead of appending to existing files

Other arguments


Do not check whether subjects are currently being processed

-sd <dir>

Specify subjects dir (default: $SUBJECTS_DIR)

-umask <umask>

Set unix file permission mask (default: 002)

-grp <groupid>

Check that current group is alpha groupid


Set coredump limit to unlimited


Generate much more output


Do everything except executing commands


Print version of each binary and exit


Print version of this script and exit


Print full contents of help

Processing steps

  1. Preprocessing

    • 1.1 Image corrections

      • This step does the following:
        • Convert the input DWI files to NIfTI.
        • Correct for B0 inhomogeneities (optional). This is done using epidewarp.fsl. This step can be turned on or off in the configuration file. To run this step, B0 field map files for each subject must be specified in the configuration file.

        • Correct for eddy currents and simple head motion (optional). This is done using FSL's eddy_correct. This step can be turned on or off in the configuration file.

        • Create a brain mask from the low-b diffusion images. This done using FSL's bet. The threshold can be specified in the configuration file. The configuration file can also be used to specify if this brain mask will actually be used in the following processing steps or if the anatomical brain mask from recon-all will be used instead.

      1.2 Intra-subject registration

      • This step performs an affine registration between the individual's low-b diffusion and T1 images. This can be done with bbregister and/or with FSL's flirt, as specified in the configuration file.

      1.3 Inter-subject registration

      • This step does the following:
        • Register the individual's T1 image to an atlas template. Currently the only available option is to use the MNI template and compute an affine registration between the individual T1 and the template using FSL's flirt.

        • Compose the diffusion-to-T1 transformation (from step 1.2) and the T1-to-template transformation to get the diffusion-to-template transformation.

      1.4 Mask creation

      • This step does the following:
        • Create a white-matter (WM) mask. This is done by extracting the cerebral WM, cerebellar WM, ventral DC, and brainstem from the individual's FreeSurfer cortical parcellation and subcortical segmentation (mri/aparc+aseg.mgz).

        • Create a mask of the cortex. This is done by mapping the cortical parcellation labels to the volume, growing them into the WM by 2mm and combining all the grown cortical labels into a mask.
        • Create an anatomical brain mask. This is done by binarizing and dilating the entire cortical parcellation and subcortical segmentation.
        • Transform all the above masks from individual T1 space to individual diffusion space and to the template space. This is done using the registrations that were computed in steps 1.2 and 1.3.
        • Transform the diffusion brain mask created in step 1.1 from the individual diffusion space to individual T1 space and to the template space.

      1.5 Tensor fit

      • This step does the following:
        • Perform least-squares tensor estimation using FSL's dtifit.

        • Map all scalar output volumes of the tensor fit (FA, MD, etc.) from diffusion space to the template space. This is done using the registrations that were computed in steps 1.2 and 1.3. (One could use these transformed volumes to do voxel-based statistical analyses in the template space, if one is so inclined.)

      1.6 Estimation of pathway priors

      • This step does the following:
        • Compute pathway priors. This is done in template space by combining the atlas data (training subjects' manually labeled pathways and anatomical segmentations) with the individual's own masks from step 1.4. The training data is used to estimate a priori probabilities that each pathway intersects/neighbors each of the labels in the cortical parcellation and subcortical segmentation, at each point along the pathway's trajectory. The training set is also used to obtain ROIs for the two endings of each pathway, as well as an initial guess of the location of the control points of each pathway, to be used in the tractography of step 3.

        • Map the selected initial control points from the template space to individual diffusion space, using the registrations that were computed in steps 1.2 and 1.3.
  2. Ball-and-stick model fitting

    • This step runs FSL's bedpostx to fit the ball-and-stick model of diffusion to the DWIs. One isotropic and two anisotropic compartments are assumed by default to model the diffusion signal in each voxel. Parallel processing on a computer cluster is highly recommended for this step.

  3. Pathway reconstruction

    • This step does the following:
      • Estimate the a posteriori probability distribution of the location of each pathway in the individual. This distribution consists of a likelihood term (the fit of the pathway orientation to the anisotropic compartments of the ball-and-stick model at each voxel) and a prior term (computed in step 1.6 from the atlas). The estimation is done by an MCMC algorithm and several parameters of that algorithm can be set in the configuration file.

      • Use the estimated pathway distributions to extract statistics on standard diffusion measures (FA, MD, etc.) for each of the pathways

Output directories and files

When trac-all runs, it generates output files for each subject under a directory that is denoted by <subjid> in the following. This subject name is provided either on the command line via the -s option, where only one subject can be specified, or in the configuration file, where multiple subjects can be specified.

By default the <subjid> directory is the same as the one under $SUBJECTS_DIR, where the subject's FreeSurfer recon is saved. An alternative location for trac-all subject directories can be specified either in the configuration file or with the -sd command-line option.

The most basic output of trac-all is the concatenation of the volumetric distributions of all the pathways that were specified in the configuration file (by default all 18 pathways included in the atlas). This output is called merged_*.mgz (the actual name depends on processing options). It can be visualized with freeview's -tv option. More information on this can be found in the TRACULA tutorial.

A detailed list of output files from each step of trac-all is given below.

Outputs from trac-all -corr

Outputs from trac-all -intra

In the following, <regtype> is used to denote the intra-subject registration method. Depending on what configuration options were used, it can be flt (flirt) or bbr (bbregister).

Outputs from trac-all -inter

Outputs from trac-all -masks

In the following, <space> is used to denote the space that the volume is in. It can be anatorig (original anatomical space), anat (converted anatomical space in the orientation preferred by FSL), diff (diffusion space) or mni (MNI template space).

Outputs from trac-all -tensor

Outputs from trac-all -prior

In the following, <tract> is used to denote the name of the pathway, <nsubj> the number of training subjects used to calculate the priors (by default all 33 subjects in the atlas), and <regtype> the intra-subject registration method (flt for flirt or bbr for bbregister).

Pathway initialization:

Pathway end ROIs:

Pathway histograms:

Priors on the underlying anatomy of the pathways

Before computing these, each pathway is split into segments along its arc length. The number of segments depends on the average length of the pathway. Prior information on the underlying anatomy is extracted from the training subjects for each segment along the length of each pathway. In the following text files, each row corresponds to a different segment along the pathway, i.e., the number of rows equals the number of segments. The information in the text files relates to the frequency with which each label in the aparc+aseg is found in the immediate neighborhood of each segment of the pathway, in the left, right, anterior, posterior, superior, and inferior direction. There is a different text file for each of these directions, denoted by the <x>, <y>, and <z> suffixes for the L-R, A-P, and I-S direction respectively. Specifically, x=1: Left; x=-1: Right; y=1: Anterior; y=-1: Posterior; z=1: Superior; z=-1: Inferior.

Outputs from trac-all -bedp

See bedpostX documentation for a detailed explanation of the bedpostX algorithm and its outputs. Every voxel in the diffusion volume is modeled as a combination of two anisotropic compartments and one isotropic compartment. In the following <i> denotes the anisotropic compartment (1 or 2).

Outputs from trac-all -path

In the following, <tract> is used to denote the name of the pathway, <nsubj> the number of training subjects used to calculate the priors (by default all 33 subjects in the atlas), and <regtype> the intra-subject registration method (flt for flirt or bbr for bbregister). Note: The directory structure given below assumes that the user set only a single option for each of the configuration parameters such as type of intra-subject registration, number of pathway controls points, etc. If multiple options are specified for one of these parameters in the configuration file, then there will be a seperate subdirectory for each case. For example, if you select to do intra-subject registration using both flirt and bbregister, the results from each case will be in a subdirectory named like this: <subjid>/dpath/<ncpts>/priormni/seg14/initmni/reg<regtype> (<regtype> is either flt or bbr for BBREGISTER; <ncpts> is the number of pathway control points).

All volumes and coordinate files below are in the native diffusion space of subject <subjid>. Tractography is run in diffusion space, even though the anatomical priors were estimated in MNI space.

For more information on the stats files, see Tract statistics in the TRACULA tutorial.

For more information on how to visualize the merged 4D volume, see Visualizing the posterior distribution of all reconstructed tracts in the TRACULA tutorial.

See Also





Automated probabilistic reconstruction of white-matter pathways in health and disease using an atlas of the underlying anatomy. Yendiki A, Panneck P, Srinivasan P, Stevens A, Zöllei L, Augustinack J, Wang R, Salat D, Ehrlich S, Behrens T, Jbabdi S, Gollub R and Fischl B (2011). Front. Neuroinform. 5:23. doi: 10.3389/fninf.2011.00023

Reporting Bugs

Report bugs to < >


Anastasia Yendiki