Contents
There are a few modes/varieties/flavors of fiber tracking which can be performed with 3dTrackID. Selecting which one to use depends a bit on the available inputs (though, these are mostly the same for each mode) and on the desired outcome (“with great power comes great responsibility”).
A general theme of all of them is to be able to deal with the following scenario: I have a network of target ROIs; where is the most likely location of the white matter connecting any of them, and what quantitative properties do those white matter ROIs have?
Excited? Me, too. Before continuing, though, let’s agree on some terminology with which these help pages will hopefully show consistency:
Note
“All targets are equal,” meaning that tracking is performed amongst and within the network of targets, with no special preference. Other programs may have an approach of tracking ‘to’ a target ‘from’ a seed, but this directional approach (where “some targets are more equal than others”) is not the philosphical choice here. Why should a tract result connecting targets 1 and 9 be different than that connecting 9 and 1?
Preface. Once upon a time, there were two separate FATCAT programs for performing deterministic and probabilistic tractography (3dTrackID and 3dProbTrackID, respectively), as described in the initial paper (Taylor and Saad, 2013). Soon after this introduction, it became apparent that there could be only one. After a brief quickening, 3dTrackID picked up the probabilistic attributes and now that program is run in separate modes. Which brings us to the present.
tractography, and each is denoted with a short string after the required switch -mode *. These are:
Thus, all FATCAT tracking commands will start with a selection of one of these modes:
3dTrackID -mode {DET|MINIP|PROB} ...
There is a lot of overlap in what kind of data are input and output for these modes. First, we describe the default and optional outputs of all; then, special outputs of some; finally, the differences in inputs (and why they exist as such).
The outputs can be viewed variously and interactively in AFNI and SUMA (such as for volume, tract, and dset files). Additionally, matrices of properties can be viewed and saved from the command line with some fat_*.py functions. Finally, outputs can be used for quantitative comparison and statistical modeling– one method for doing the latter exists using G. Chen’s 3dMVM (see below for some description, and the FATMVM demo introduced Demo data sets and scripts).
By default, each of the 3dTrackID modes will output the following:
Example 1. For example, running 3dTrackID with -prefix o.NETS (and -nifti) will produce the output files:
o.NETS_000.grid
o.NETS_000.niml.dset
o.NETS_000_INDIMAP.nii.gz
o.NETS_000_PAIRMAP.nii.gz
Comments on these outputs:
- A PAIRMAP is not output if the input network has only one target ROI, such as if one is doing a simple whole brain tracking.
- One can turn off INDIMAP and PAIRMAP output altogether, using the switch -no_indipair_out. This might be useful if you are tracking through a large network of targets (for example, something connectome-y) and don’t want to risk having a single reaaally big output file wasting space or causing trouble.
- By default, all volumetric outputs (PAIRMAP, INDIMAP, -dump_rois * files, etc.) are in BRIK/HEAD file format. If you prefer NIFTI, you can use the switch -nifti to get all “*.nii.gz” files.
Additionally, each mode can also output:
a set of maps/masks of each individual WM ROI. This is done using the option -dump_rois {AFNI|DUMP|BOTH|AFNI_MAP}. The keyword options each produces a set of individual files of the following:
Example 1 (continued). Additionally, if one also included the command -dump_rois AFNI, then the output would include a directory o.NETS/ with the following files, such as:
NET_000_ROI_001_001.nii.gz
NET_000_ROI_001_004.nii.gz
NET_000_ROI_002_002.nii.gz
NET_000_ROI_002_003.nii.gz
NET_000_ROI_002_004.nii.gz
NET_000_ROI_002_006.nii.gz
NET_000_ROI_002_007.nii.gz
...
With the specific dump option used here, each file would contain a binary mask of the given WM connection. The file naming convention is: NET_X_ROI_Y_Z.nii.gz, where:
- ‘X’ is the number of the network (because multiple ones can be tracked simultaneously
- ‘Y’ is the number or label of a target ROI
- ‘Z’ is the number or label of another target ROI
The files where ‘Y’==’Z’ contain INDIMAP information of a target, and the others where not(‘Y’==’Z’) contain PAIRMAPs. It’s important to note that tracts will not be found between every possible pair of targets, and so not every possible pairwise combination will have a file output. |
Note
Probably using one of the options -dump_rois {AFNI|AFNI_MAP} would be the most useful. Some unnamed user(s) would even go so far as to recommend using it all the time, because either would provide the only unambiguous maps of individual WM ROIs output by 3dTrackID.
A labeltable file (*.niml.lt) will also be output if one has been attached to the input network file. While one might not view this on its own, having a labeltable set up can be very useful, for example in helping to discuss specific bundles by the anatomical locations they connect.
The outputs in the previous section are output for all modes of 3dTrackID. However, careful readers will note that none of those tractographic outputs actually contained the tracts themselves! These are only output in {DET|MINIP} modes, as the following:
a tract file (ending with *.tract), which contains all the individual tract sequences. Additionally, it internally has the tracts organized into sets of bundles between targets, so that each bundle could be displayed as a separate color. These files are viewable in SUMA, loading with:
suma -tract PREFIX.niml.tract ...
One can also load in the dset simultaneously and view the connectivity matrix elements as coloration of tract bundles, such as after:
suma -tract PREFIX.niml.tract -gdset PREFIX.niml.dset ...
(In fact, the dset loaded in could be either one output by 3dTrackID or by 3dNetCorr.)
a TRK-format file, *.trk, legacy of when tractographic output had to be viewed with non-AFNI/SUMA options, which in this case were with TrackVis. These are not output by default. To have these be output, use the the -do_trk_out switch.
When outputting tract files, one has to choose whether to use AND-logic or OR-logic within the network. That is, whether to keep tracts that have a minimal requirement of going through one target (OR), or whether to require at tract to connect at least two targets (AND). The choice is made using the (required) option -logic {AND|OR}.
And, just to state explicitly, the full probabilistic tracking in -mode PROB does not (currently) produce tract file output. Such is life and also an impetus behind the mini-probabilistic methodology (described further below).
Many different types of output files can be viewed simultaneously in SUMA (volume, tractfile, dset/matrices, etc.). SUMA and AFNI can also be run at the same time to talk together and share informative gossip on data sets. All the individual SUMA examples below can be combined in a single command line call. After opening a controller, you can hit the new useful ‘All Objs.’ button near the top, in order to immediately be able to toggle among each input file. For more information on SUMA viewing in general, check out SUMA Viewer.
Volume files outputs. PAIRMAP, INDIMAP and dumped volumes can all be viewed in either AFNI or in SUMA. To load them into the latter for 3D visualization, use:
suma -vol FILENAME ...
By default, they are displayed as slices and not as surfaces, but you can select that capability (see description in Volume Viewing).
To view the volume files in the 2D afni slice viewer, one uses the standard, general call to open AFNI (assuming you’re in a directory where those files are located; otherwise, include the path to them):
afni
Matrix file outputs. SUMA is used to view the matrix information in the *.dset file. While one can view this information as a ‘classic’ connectivity matrix (for both 3dTrackID and 3dNetCorr outputs), it is also possible to view the data as coloration of graph edges and/or tract bundles in the brain volume. For more features, please see the help examples in SUMA: Graph Viewing. To load the data into SUMA, use:
suma -gdset FILE.niml.dset ...
Additionally, one can select, view and save the matrices from the command line with a Python-based tool, fat_mat_sel.py. This program can output several matrices from several subjects simultaneously, and the user can control several features of the plotting (font size, colorbar properties, ranges, DPI, etc.). It can be useful, for example, when making outputs for presentations and publications. See the helpfile:
fat_mat_sel.py -h
for more information and list of the options.
Tract files. These are viewable in SUMA with many, many interactive features. To load in the tracts:
suma -tract FILE.niml.tract ...
Default coloration is by local tract orientation, but one can also color, for example, by bundle (useful for connectomes) or by the connectivity matrix information (importing the -gdset FILE.niml.dset information, above).
Selection masks (either sphere or box) can be made for specifying subsets of tracts. One can have multiple selection masks, and use AND- and/or OR-logic with them. Importantly, these volumes are dragged along the tracts and bundles themselves, so that one can follow arbitrary trajectories through 3D (i.e., one is not constrained to manipulating them just in 2D slices).
For more information, please see the voluminous set of features, hints and examples in the SUMA help: Tract Viewing.
TRK files. These NAME.trk files are generated using the TrackVis format, and as such can be viewed in the eponymous program. (They are not output by default.)
This section will be an attempt to cluster 3dTrackID input options meaningfully.
Each option is briefly explained the first time it is mentioned; one can assume that, unless explicitly noted, the initial definition still holds. A selection of -mode {DET|MINIP|PROB} is always required, as well.
The examples are shown for DTI tracking, and the simple option change in each case for performing HARDI tracking is provided immediately after.
Deterministic (DET) DTI:
3dTrackID -mode DET \
-dti_in DT_PREF \
-netrois TARGET_ROI_FILE \
-logic {AND|OR} \
-prefix OUT_PREF
where:
-dti_in DT_PREF: point to the set of DTI parameter files by their prefix. The program will read in all scalar files with this prefix and output WM ROI statistics on them. The minimum set of files needed for tracking is:
The function will glob for all scalar files with the entered prefix (-dti_in DT_PREF leads to searching for file names like ‘DT_PREF*’), so other scalars can be easily included for automatic connectivity matrix calculation by giving them the same prefix. (See below for other ways of including extra files.)
-netrois TARGET_ROI_FILE: input the file of targets among which to find connections. This can be a file with multiple volumes/bricks, and each brick is treated like a separate network. Each target in a network is defined as a set of voxels with a given integer, and a labletable can be attached for further target naming with strings (with the labels also being attached to tracked outputs).
-logic {AND|OR}: select whether the tracts output in the *.tract file connect targets using AND- or OR-logic. NB: in *either case, both INDI and PAIR map (volume) files are output.
-prefix OUT_PREF: prefix for all output files, as described above. Additionally, a network number will be appended before the file extensions, starting with 000, 001, 002, etc. (in order to match the brick number of the -netrois file).
Note
Instead of -dti_in DT_PREF, one can input an explicit file of list of DTI parameter files to input in a niml-formatted text file with -dti_list FILE.niml.opts. An example is provided in the 3dTrackID help file under “DTI LIST FILE EXAMPLE”. Up to 4 ‘extra’ scalar-valued files can be input for statistical purposes.
Mini-probabilistic (MINIP) DTI:
3dTrackID -mode MINIP \
-dti_in DT_PREF \
-netrois TARGET_ROI_FILE \
-logic {AND|OR} \
-uncert U_FILE \
-mini_num NREP \
-prefix OUT_PREF
where:
-uncert UNCERT_FILE: the file of uncertainty values output by 3dDWUncert.
-mini_num NREP: the number of perturbed Monte Carlo repetitions to perform. Often 5-7 seems to be a good number.
Fully probabilistic (PROB) DTI:
3dTrackID -mode PROB \
-dti_in DT_PREF \
-netrois TARGET_ROI_FILE \
-uncert U_FILE \
-prefix OUT_PREF
where: all the options have been described in the previous two examples! (This method produces no tract results, however, just volumes. But those can be quite useful, too.)
Performing HARDI tracking in each of the above cases is done with a change of one option:
One might want to load extra volumes of information into 3dTrackID for making extra connectivity matrices in the output *.grid files. For example, one might want statistics performed on non-diffusion data such as T1 or PD values.
Alternatively, in DTI analysis one might want to use a non-FA map to restrict tract propagation, for example using a T1-weighted segmentation. For this purpose, one would load it in using -dti_extra SET. In grid files, name of this quantity will be ‘XF’ (stands for ‘extra file’).
NB: if the file SET happens to have a name like ‘DT_PREF*’, it will still be globbed for using -dti_in DT_PREF, and therefore included twice. But that shouldn’t harm any results.
Note
To turn off the globbing capability (beyond finding just the bare minimum DTI files), one can use the -dti_search_NO switch.
The following major tracking parameters can all be changed individually from the command line (default values are given):
for all modes:
-alg_Thresh_FA A : set threshold for DTI FA map, ‘-dti_extra’ FILE, or HARDI GFA map (default = 0.2).
-alg_Thresh_ANG B : set max angle (in deg) for turning when going to a new voxel during propagation (default = 60).
-alg_Thresh_Len C : min physical length (in mm) of tracts to keep (default = 20).
for {DET|MINIP} modes:
-alg_Nseed_X D : Number of seeds per vox in x-direc (default = 2).
-alg_Nseed_Y E : Number of seeds per vox in y-direc (default = 2).
-alg_Nseed_Z F : Number of seeds per vox in z-direc (default = 2).
for PROB mode:
-alg_Thresh_Frac G : value for thresholding how many tracks must pass through a voxel for a given connection before it is included in the final WM-ROI of that connection. It is a decimal value <=1, which will multiply the number of ‘starting seeds’ per voxel, Nseed_Vox*Nmonte (see just below for those; default = 0.001; for higher specificity, a value of 0.01-0.05 would be used).
-alg_Nseed_Vox H : number of seeds per voxel per Monte Carlo iteration; seeds will be placed randomly (default = 5).
-alg_Nmonte I : number of Monte Carlo iterations (default = 1000).
The above alg_* tracking parameters can also be set at once in a single text file. The text file can either have only plain text and no labels, or it can be in NIML-format with nice labels so that there’s no confusion about which value is being set. See the 3dTrackID help file’s “ALGOPT FILE EXAMPLES” for more information. The option file is loaded in using -algopt A_FILE.
When in MINIP and PROB modes, which use the uncertainty of parameter values, one can choose an explicit minimum uncertainty; in general, the uncertainty files will have been generated using 3dDWUncert, but for whatever reason you might want to enforce a minimal angular uncertainty or something. The values are set with:
-unc_min_FA VAL1 : the minimum stdev for perturbing FA (in -dti_in), or the EXTRA- file also in DTI (-dti_extra), or GFA (in -hardi_*). Default value is: 0.015 for FA, and 0.015 times the max value in the EXTRA-file or in the GFA file.
-unc_min_V VAL2 : the minimum stdev for perturbing eigen-/direction-vectors. In DTI, this is for tipping V1 separately toward V2 and V3, and in HARDI, this is for defining a single degree of freedom uncertainty cone. Default values are 0.06 rad (~3.4 deg) for any eigenvector/direction. User assigns values in degrees.
The PROB method requires a certain number of tracts to go through a voxel before it is included in a WM ROI connection.
Recently, the ability to trim some kinds of ‘obvious’ noisy tracts from DET and MINIP modes has been added. The option -bundle_thr V allows the user to enter a minimum threshold number of tracts for any bundle to have without being filtered out (AKA removed).
It is based on the fact that occasionally, one will see an odd tract winding as a connection between two targets, in what would appear visually to be an outlier. Even when using more DET seeds or MINIP iterations, the tract might remain isolated– further justifying its interpretation as noise-driven. The bundle threshold criterion can be useful in removing it easily.
Note, however, that the fully probabilistic mode’s criterion is stricter, and it still provides the most robust results when tracking.
See the -dump_rois * option above in Outputs common to all modes. I think it’s pretty valuable to use one of -dump_rois {AFNI|AFNI_MAP}, in order to be able to have individual WM ROI files output. The PAIR and INDI maps are mostly for quick reference, in my opinion, while the dumped files can be more useful in viewing or further quantitative analyses.
-nifti : output all volume files as *.nii.gz files.
-extra_tr_par : run three extra track parameter scalings for each target pair, output in the *.grid file. The NT value of each connection is scaled in the following manners for each subsequent matrix label:
NB: the volume and surface area numbers are given in terms of voxel counts and not using physical units (consistent: NT values themselves are just numbers.)
Sundry other options described in the 3dTrackID helpfile (which most likely aren’t interesting enough to describe further): ‘-dump_lab_consec’, ‘-posteriori’, ‘-rec_orig’ and ‘-pair_out_power’.