Differences between revisions 81 and 82
Deletions are marked like this. Additions are marked like this.
Line 60: Line 60:
A "robust max" thresholding is used within dmri_mergepaths and dmri_pathstats (i.e. the 99th percentile of the values in path.pd.nii.gz). This is to avoid cases where the absolute max is an outlier, which would cause the threshold to be too high and the isosurface in freeview to be generated from too few voxels.

TRACULA (TRActs Constrained by UnderLying Anatomy) is a tool for automatic reconstruction of a set of major white-matter pathways from diffusion-weighted MR images. It uses global probabilistic tractography with anatomical priors. Prior distributions on the neighboring anatomical structures of each pathway are derived from an atlas and combined with the FreeSurfer cortical parcellation and subcortical segmentation of the subject that is being analyzed to constrain the tractography solutions. This obviates the need for user interaction, e.g., to draw ROIs manually or to set thresholds on path angle and length, and thus automates the application of tractography to large datasets.



TRACULA in FreeSurfer 6.0:

  • Automatic path reinitialization: This feature reduces the cases where the user has to reinitialize a path dramatically.
  • Cluster job submission: Adding -jobs <filename> to the trac-all command line will process the configuration file, set up the analysis for all subjects included in it, but will not actually run the analysis. Instead, it will write the commands that need to be run into <filename>. The user is then responsible for submitting those as jobs to be run in parallel on a cluster.

  • Gradient tables and b-value tables: They can now be read directly from the DICOM header of the DWI series (using new functionality in mri_convert), without the user having to specify them.

  • In case you want to remove certain volumes from your DWIs, you can create a text file called dmri/keepframes.txt for each subject, containing the list of frames (0-based) that you want to keep. In this case, you provide the entire DWI series (and the entire gradient table and b-value table, if they are not to be read from the DICOM header) but TRACULA only uses the subset of frames specified in this file.

  • It is also possible to specify a different table of b-values for each scan, using set bvallist instead of set bvalfile in the configuration file.

TRACULA in FreeSurfer 5.3:

  • 2014/05/26 -- B) TRACULA update: CentOS 6 (64-bit) | CentOS 4 (64-bit) | CentOS 4 (32-bit) | MacOSX lion (64-bit) | MacOSX snow leopard (32-bit) This update includes all the features from the previous update, plus improvements to the longitudinal stream of TRACULA. Note that this newer version of longitudinal TRACULA uses the aparc+aseg.mgz from the *.long.* output of longitudinal FreeSurfer, rather than the cross-sectional aparc+aseg.mgz.

  • 2013/12/09
    • NEW FEATURE: Compute the four measures of head motion from Yendiki et al. 2013, which can be used to match motion between groups or regress motion in statistical analyses. This can be run as a separate step with trac-all -qa, and is also run as part of trac-all -prep.

    • NEW FEATURE: Combine anisotropy and diffusivity measures from multiple subjects at different positions along each pathway (from the pathstats.byvoxel.txt files). This can be run with trac-all -stat.

    • It is now possible to specify a different table of gradient vectors for each scan, using set bveclist instead of set bvecfile in the configuration file.

    • The tables of gradient vectors and/or b-values can now be formatted in column or row format, and blank lines at the end of each file should not cause an error.

    • A scripting bug that was causing the longitudinal stream not to run at all on certain platforms has been fixed.
  • 2013/05/15 -- No changes to TRACULA in FreeSurfer 5.3 since FreeSurfer 5.2

TRACULA in FreeSurfer 5.2:

  • 2013/03/02 -- Changes to TRACULA included in FreeSurfer 5.2:

    • Improved fitting for the initialization of the pathways in the -prior step, along with a 70% reduction in computation time for that step.
    • More efficient exploration of 3D space in the pathway reconstruction algorithm allows it to get to more of the pathway endings and those hard-to-reach spots.
    • Several default settings have changed, see $FREESURFER_HOME/bin/dmrirc.example for details:
      • The default and recommended method for intra-subject registration is now bbregister.
      • A different number of control points can be (and is, by default) chosen for each of the 18 pathways.
      • The default number of samples has increased.
    • The CVS template can now be used instead of the MNI template for inter-subject registration. This could improve the initialization of the pathways for subjects with challenging anatomical features, e.g., enlarged ventricles, at the expense of higher memory requirements for holding the CVS non-linear warp in memory.

    • The low-b images can now be interspersed throughout the DWI series and the low b-value can be greater than zero. There is no need for the user to define the number of low-b images in the configuration file any more, this will all be worked out automatically from the b-value table.
    • The user can set the number of anisotropic compartments ("sticks") in bedpostx's ball-and-stick model to something other than 2, by setting the nstick variable in the configuration file.
    • Compatibility issues with the command line options of the latest version of bedpostx have been resolved.
    • The maximum a posteriori path, which is used to produce statistics along the length of the path (pathstats.byvoxel.txt) is now selected in a more robust way that makes these paths more consistent across subjects.

    • In addition to values of FA, MD, RD, and AD at each point along the maximum a posteriori path, pathstats.byvoxel.txt now also contains the mean values of the same measures over the entire cross-section of the path distribution at each point along the trajectory of the path.

    • NEW in this version: Longitudinal tractography. Note: This is an undocumented, unpublished, and only mildly tested BETA provided for testing purposes, so proceed at your own risk. All you need to do to use it is set the baselist variable in your configuration file, see $FREESURFER_HOME/bin/dmrirc.long.example. It assumes that the longitudinal FreeSurfer stream has been run on the anatomical data to obtain the base templates.

TRACULA in FreeSurfer 5.1:

  • 2012/01/09 -- trac-all: This update for trac-all is recommended for all users of version 5.1.

  • 2011/08/17 -- dmri_5.1_snow_leopard.tar.gz: TRACULA executables compiled on snow leopard. This build resolves memory issues that snow leopard users had with the original leopard build.

  • 2011/05/24 -- First release of TRACULA in FreeSurfer 5.1.


All preprocessing of the diffusion-weighted images and reconstruction of the pathways is done by the trac-all script. Several options for this analysis stream can be set by the user in a configuration file (dmrirc file), which is passed as an argument to trac-all. For more information, see:

In summary the trac-all script can be used to:

  • Preprocess the diffusion-weighted images, applying standard methods to mitigate image distortions due to eddy currents and B0 field inhomogeneities
  • Register the individual's diffusion-weighted and anatomical images to each other and to a common (atlas) space
  • Reconstruct volumetric distributions of 18 major white-matter pathways included in the atlas
  • Extract statistics on standard diffusion measures (FA, MD, etc.) for each of the reconstructed pathways

Different command-line options allow the user to run all the above processing steps sequentially or only a single step.

The final output of TRACULA, the concatenation of the volumetric distributions of all reconstructed pathways, is a file called merged_*.mgz (the actual name depends on processing options). It can be visualized with freeview's -tv option, which displays the volumetric distributions of the pathways as isosurfaces like the ones shown in the image above.

A "robust max" thresholding is used within dmri_mergepaths and dmri_pathstats (i.e. the 99th percentile of the values in path.pd.nii.gz). This is to avoid cases where the absolute max is an outlier, which would cause the threshold to be too high and the isosurface in freeview to be generated from too few voxels.

Note that, because TRACULA relies on the underlying anatomy as derived from the FreeSurfer cortical parcellation and subcortical segmentation, these need to be generated before running trac-all. This means that before you run trac-all you will have to analyze your subjects' anatomical images with recon-all and make sure that they have a good-quality mri/aparc+aseg.mgz.


For step-by-step instructions on how to set up and run TRACULA, see the following tutorials from the FreeSurfer training workshop:

Related slide presentations from the workshop are available here:


If you use TRACULA, please cite:

If you use our measures of head motion, please cite:

If you use the longitudinal stream of TRACULA, please cite:

Tracula (last edited 2021-12-08 17:47:15 by AnastasiaYendiki)