Please note that heuristic neighbourhood tractography is now deprecated. For new projects, please use the much more sophisticated and flexible probabilistic neighbourhood tractography.
This tutorial describes how to use TractoR to perform neighbourhood tractography using the heuristic method described in Ref. (1). Heuristic neighbourhood tractography (HNT) uses a reference tract as a guide to the topology of the white matter structure that needs to be segmented.
Note: The alternative probabilistic approach to neighbourhood tractography is recommended in preference to the heuristic approach described here, due to its greater flexibility and considerably improved robustness, although the heuristic method is slightly simpler to run. If you do use this method in your studies please cite Ref. (1). Details of the underlying methods can be found there.
TractoR experiment scripts that may be used in a typical HNT-based study are
hnt-eval (to evaluate a series of tracts for similarity to the reference tract),
hnt-viz (to visualise the best-matching tract from each session directory),
hnt-interpret (to display the seed point or similarity score for the best-matching tract in each subject), and
gmean (to calculate the mean anisotropy along the best-matching tracts).
The prerequisites for HNT are some fully preprocessed diffusion MR data and a reference tract representing the pathway we wish to segment in those data. The latter may be a custom reference tract, or one of the standard references provided with the software.
Segmenting in novel data
Once a suitable reference tract is chosen and available, segmenting a similar tract in another brain volume is a matter of identifying the appropriate session directory (we’ll use /data/testsubject for the sake of example) and the size of the search neighbourhood. These parameters are passed to
hnt-eval, along with the tract name:
tractor hnt-eval /data/testsubject TractName:genu SearchWidth:7 ResultsName:genu_results
Here we use a search neighbourhood of 7 x 7 x 7 voxels, as in Ref. (1). The larger the “SearchWidth”, the more likely a good match will be found, but the longer the process will take to complete. There is an anisotropy (FA) threshold of 0.2 imposed on the neighbourhood by default, so that seed points with FA lower than 0.2 will not be used to generate candidate tracts. The level of this threshold can be set with the “AnisotropyThreshold” option.
Note that the preceding example uses a standard reference tract (the genu), so TractoR knows where to find it. However, if a custom reference tract is used, it must be copied into the working directory before running
hnt-eval. An error will be produced if no reference tract of the specified name can be found.
hnt-eval script will generate a results file, which can be used to generate an Analyze/NIfTI volume and/or PNG projection images of the best matching tract from the test subject, with
tractor hnt-viz /data/testsubject TractName:genu ResultsName:genu_results
slice script can be used to convertThe location of the final seed point, or the similarity score of the associated tract, can be displayed using
tractor hnt-interpret /data/testsubject ResultsName:genu_results Mode:location
Finally, the mean FA along the selected tract can be calculated using the
mean script, as in
tractor mean /data/testsubject@FA genu.1
where “genu.1” is the tract volume created by
hnt-viz for our test session.
Using a design file
Since the various HNT scripts have a number of options in common, which are typically repeated from one to the other, it is often convenient to store these options in a file, rather than specifying them on the command line. Moreover, since any given script will simply ignore any options which it does not use, the entire experiment’s parameters can be stored in a single configuration file, or design file. For example, if we place into a file called “design.yaml” the following
TractName: genu SearchWidth: 7 ResultsName: genu_results
then our calls to the HNT scripts can be simpler and less repetitive. We can now use
tractor -c design.yaml hnt-eval /data/testsubject
to do the same job that our earlier
hnt-eval command did, but with less command-line clutter. Note that the
-c flag, which must come before the script name, tells TractoR to look in the file “design.yaml” for configuration parameters. (See the
tractor man page for more details.) Any further parameters needed by specific scripts can still be given as part of a command, as in
tractor -c design.yaml hnt-viz /data/testsubject
Another advantage of using a design file is that it allows us to easily process multiple data sets, potentially in parallel, in one command. Thus, our design can be broadened to find matching tracts in a group of subjects:
Session: [ /data/testsubject1, /data/testsubject2, /data/testsubject3 ] TractName: genu SearchWidth: 7 ResultsName: genu_results
Note that the list of test sessions is enclosed by square brackets and separated by commas (and optionally whitespace, which may include newlines as in this example). Now, we need to switch to using the
plough program from the command line, which is designed to call a TractoR script with different sets of arguments. The commands above become
plough -C design.yaml hnt-eval %Session plough -C design.yaml hnt-viz %Session plough -C design.yaml hnt-interpret %Session Mode:location plough -C design.yaml mean %Session@FA genu.%%
Note the syntax
%Session, which will be expanded by
plough to use each value of the “Session” variable specified in the design file, in turn. In the final command,
%% is also used, which is replaced by the number of the iteration being performed: 1, 2 or 3.
This tutorial has demonstrated the stages involved in using heuristic neighbourhood tractography for tract segmentation, following the process described in the reference below. We used a reference tract as a guide for candidate tract selection in a test data set of one or more subjects.
- J.D. Clayden et al., Neuroimage 33(2):482-492, 2006.