AFNI program: 3dTrackID
Output of -help
FACTID-based tractography code, from Taylor, Cho, Lin and Biswal (2012),
and part of FATCAT (Taylor & Saad, 2013) in AFNI. Version 2.1 (Jan. 2014),
written by PA Taylor and ZS Saad.
Estimate locations of WM associated with target ROIs, particularly between
pairs of GM in a network; can process several networks in a given run.
Now does both single tract propagation per voxel (as per DTI) and
multi-directional tracking (as in HARDI-type models). Many extra files can
be loaded in for getting quantitative stats in WM-ROIs, mostly done via
search from entered prefixes. Many more switches and options are available
to the user to control the tracking (yay!).
Track display capabilities in SUMA have been boosted and continue to rise
quickly (all courtesy of ZS Saad).
****************************************************************************
+ NOTE that this program runs in three separate modes, each with its own
subset of commandline options and outputs:
$ 3dTrackID -mode {DET | MINIP | PROB} ...
where DET -> deterministic tracking,
MINIP -> mini-probabilistic tracking,
PROB -> (full) probabilistic tracking.
So, for example, DET and MINIP produce pretty track-image output,
while PROB only provides volumes; MINIP and PROB make use of
tensor uncertainty to produce more robust results than DET; all
produce quantitative statistical output of WM-ROIs; etc. In some cases,
using a combination of all three might even be variously useful in a
particular study.
****************************************************************************
For DTI, this program reads in tensor-related data from, e.g., 3dDWItoDT,
and also uses results from 3dDWUncert for uncertainty measures when
necessary.
For HARDI, this program reads in the direction vectors and WM-proxy map
(such as the diffusion anisotropy coefficient, GFA) created by any source-
right now, there's no HARDI modeler in AFNI. Currently known sources which
are reasonably straightforward to use include DSI-Studio (Yeh et al.,
2010) and Diffusion Toolkit (Wang et al., 2007). An example script of
outputting Qball model data as NIFTI output from the former software is
included in the FATCAT demo set.
...And on that note, it is highly recommended for users to check out the
FATCAT demo set, which can be downloaded and unwrapped simply from the
commandline:
$ @Install_FATCAT_Demo
In that demo are data, a number of scripts, and more detailed descriptions
for using 3dTrackID, as well as other programs in the FATCAT litter.
Recommended to always check that one has the most up-to-date version.
****************************************************************************
+ INPUT NOTES:
NETWORK MAPS, for any '-mode' of track, given as a single- or multi-brik
file via '-netrois':
Each target ROI is defined by the set of voxels with a given integer >0.
Target ROI labels do not have to be purely consecutive.
Note on vocabulary, dual usage of 'ROI': an (input) network is made up of
*target ROIs*, between/among which one wants to find WM connections; so,
3dTrackID outputs locations and stats on those calculated *WM-ROIs*.
****************************************************************************
+ OUTPUTS, all named using '-prefix INPREF'; somewhat dependent on tracking
mode being utilized ('-mode {DET | MINIP | PROB}').
Because multiple networks can be input simultaneously as a multi-
brik '-netrois ROIS' file, the output prefix will also have a
numerical designation of its network, matching to the brik of
the ROIS file: thus, INPREF_000* goes with ROIS[0], INPREF_001*
with ROIS[1] (if present), etc. This applies with all types of
output files, now described:
1) *INDIMAP* BRIK files (output in ALL modes).
For each network with N_ROI target ROIs, this is a N_ROI+1 brik file.
0th brick contains the number of tracts per voxel which passed through
at least one target ROI in that network (and in '-mode PROB', this
number has been thresholded-- see 'alg_Thresh_Frac' below).
If the target ROIs are consecutively labelled from 1 to N_ROI, then:
Each i-th brick (i running from 1 to N_ROI) contains the voxels
through which tracks hitting that i-th target passed; the value of
each voxel is the number of tracks passing through that location.
Else, then:
Each i-th brick contains the voxels through which the tracks
hitting the j-th target passed (where j may or may not equal i; the
value of j is recorded in the brick label: OR_roi_'j'). The target
ROI connectivity is recorded increasing order of 'j'.
For single-ROI inputs (such as a single wholebrain ROI), only the
[0] brick is output (because [1] would be redundant).
2) *PAIRMAP* BRIK files (output in ALL modes).
(-> This has altered slightly at the end of June, 2014! No longer using
2^i notation-- made simpler for reading, assuming individual connection
information for calculations was likely obtained more easily with
'-dump_rois {AFNI | BOTH | AFNI_MAP}...)
For each network with N_ROI target ROIs, this is a N_ROI+1 brik file.
0th brick contains a binary mask of voxels through which passed a
supra-threshold number of tracks (more than 0 for '-mode {DET | MINIP}'
and more than the user-defined threshold for '-mode PROB') between any
pair of target ROIs in that network (by default, these tracks have been
trimmed to only run between ROIs, cutting off parts than dangle outside
of the connection).
If the target ROIs are consecutively labelled from 1 to N_ROI, then:
Each i-th brick (i running from 1 to N_ROI) contains the voxels
through which tracks hitting that i-th target AND any other target
passed; voxels connecting i- and j-th target ROIs have value j, and
the values are summed if a given voxel is in multiple WM ROIs (i.e.,
for a voxel connecting both target ROIs 2 and 1 as well as 2 and 4,
then the value there in brick [2] would be 1 + 4 = 5).
Else, then:
Each i-th brick contains the voxels through which the tracks
hitting the j-th target AND any other target passed (where j may or
may not equal i; the value of j is recorded in the brick label:
AND_roi_'j'). The same voxel labelling and summing rules described
above also apply here.
For single-ROI inputs (such as a single wholebrain ROI), no PAIRMAP
file is output (because it would necessarily be empty).
3) *.grid ASCII-text file (output in ALL modes).
Simple text file of output stats of WM-ROIs. It outputs the means and
standard deviations of parameter quantities (such as FA, MD, L1, etc.)
as well as counts of tracks and volumes of WM-ROIs. Each matrix is
square, with dimension N_ROI by N_ROI. Like the locations in a standard
correlation matrix, each element reflects associativity with target
ROIs. A value at element (1,3) is the same as that at (3,1) and tells
about the property of a WM-ROI connecting target ROIs 1 and 3 (consider
upper left corner as (1,1)); diagonal elements provide info of tracks
through (at minimum) that single target ROI-- like OR logic connection.
Format of *.grid file is:
Line 1: number of ROIs in network (padded with #-signs)
Line 2: number of output matrices of stats info (padded with #-signs)
Line 3: list of N_ROI labels for that network
Lines following: first line, label of a property (padded with #), and
then N_ROI lines of the N_ROI-by-N_ROI matrix of that
property;
/repeat/
The first *five* matrices are currently (this may change over time):
NT = number of tracks in that WM-ROI
fNT = fractional number of tracks in that WM-ROI, defined as NT
divided by total number of tracts found (may not be relevant)
PV = physical volume of tracks, in mm^3
fNV = fractional volume of tracks compared to masked (internally or
'-mask'edly) total volume; would perhaps be useful if said
mask represents the whole brain volume well.
NV = number of voxels in that WM-ROI.
BL = average length (in mm) of a bundle of tracts.
sBL = stdev of the length (in mm) of a bundle of tracts.
Then, there can be a great variety in the remaining matrices, depending
on whether one is in DTI or HARDI mode and how many scalar parameter
files get input (max is 10). For each scalar file there are two
matrices: first a label (e.g., 'FA') and then an N_ROI-by-N_ROI matrix
of the means of that parameter in each WM-ROI; then a label (here,
would be 'sFA') and then an N_ROI-by-N_ROI matrix of the standard
deviations of that parameter in each WM-ROI.
4) *niml.tract NIML/SUMA-esque file (output in '-mode {DET | MINIP}')
File for viewing track-like output in SUMA, with, e.g.:
$ suma -tract FILE.niml.tract
5) *niml.dset NIML/SUMA-esque file (output in '-mode {DET | MINIP}')
File accompanying the *.niml.tract file-- also for use in SUMA, for
including GRID-file like information with the tract info.
$ suma -tract FILE.niml.tract -gdset FILE.niml.dset
6) *.trk TrackVis-esque file (output in '-mode {DET | MINIP}')
File for viewing track-like output in TrackVis (separate install from
AFNI/SUMA); things mainly done via GUI interface; this format of
output is off by default (see '-do_trk_out' below to enable it).
****************************************************************************
+ LABELTABLE LABELLING (Sept 2014).
The ability to use label tables in tracking result output has been
included.
Default behavior will be to *construct* a labeltable from zero-padded ints
in the '-netrois' file which define target ROIs. Thus, the ROI of '3's
will be given a label '003'. This will be used in INDIMAP and PAIRMAP
brick labels (which is useful if the targets are not consecutively
numbered from 1), PAIRMAP connections in bricks >0, and output
*.niml.tract files. The PAIRMAP labeltable will be created and output
as 'PREFIX_PAIRMAP.niml.lt', and will be useful for the user in (some-
what efficiently) resolving multiple tracts passing through voxels.
These labels are also used in the naming of '-dump_rois AFNI' output.
At the moment, in a given PAIRMAP brick of index >0, labels can only
describe up to two connections through a given voxel. In brick 1, if
voxel is intersected by tracts connection ROIs 1 and 3 as well as ROIs
1 and 6, then the label there would be '003<->006'; if another voxel
in that brick had those connections as well as one between ROIs 1 and
4, then the label might be '_M_<->003<->006', or '_M_<->003<->004', or
any two of the connections plus the leading '_M_' that stands for
'multiple others' (NB: which two are shown is not controlled, but I
figured it was better to show at least some, rather than just the
less informative '_M_' alone). In all of these things, the PAIRMAP
map is a useful, fairly efficient guide-check, but the overlaps are
difficult to represent fully and efficiently, given the possibly
complexity of patterns. For more definite, unique, and scriptable
information of where estimated WM connections are, use the
'-dump_rois AFNI' or '-dump_rois AFNI_MAP' option.
If the '-netrois' input has a labeltable, then this program will program
will read it in, use it in PAIRMAP and INDIMAP bricklabels, PAIRMAP
subbricks with index >0, *niml.tract outputs and, by default, in the
naming of '-dump_rois AFNI' output. The examples and descriptions
directly above still hold, but in cases where the ROI number has an
explicit label, then the former is replaced by the latter's string.
In cases where an input label table does not cover all ROI values,
there is no need to panic-- the explicit input labels will be used
wherever possible, and the zero-padded numbers will be used for the
remaining cases. Thus, one might see PAIRMAP labels such as:
'003<->Right-Amygdala', '_M_<->ctx-lh-insula<->006', etc.
****************************************************************************
+ RUNNING AND COMMANDLINE OPTIONS: pick a MODEL and a MODE.
There are now two types of models, DTI and HARDI, that can be tracked.
In HARDI, one may have multiple directions per voxel along which tracts
may propagate; in DTI, there can be only one. Each MODEL has some
required, and some optional, inputs.
Additionally, tracking is run in one of three modes, as described near the
top of this document, '-mode {DET | MINIP | PROB}', for deterministic
mini-probabilistic, or full probabilistic tracking, respectively.
Each MODE has some required, and some optional, inputs. Some options
find work in multiple modes.
To run '3dTrackID', one needs to have both a model and a mode in mind (and
in data...). Below is a table to show the various options available
for the user to perform tracking. The required options for a given
model or mode are marked with a single asterisk (*); the options under
the /ALL/ column are necessary in any mode. Thus, to run deterministic
tracking with DTI data, one *NEEDS* to select, at a minimum:
'-mode DET', '-netrois', '-prefix', '-logic';
and then there is a choice of loading DTI data, with either:
'-dti_in' or '-dti_list',
and then one can also use '-dti_extra', '-mask', '-alg_Nseed_Y',
et al. from the /ALL/ and DET columns; one canNOT specify '-unc_min_FA'
here -> the option is in an unmatched mode column.
Exact usages of each option, plus formats for any arguments, are listed
below. Default values for optional arguments are also described.
+-----------------------------------------------------------------+
| COMMAND OPTIONS FOR TRACKING MODES AND MODELS |
+-----------------------------------------------------------------+
| /ALL/ | DET | MINIP | PROB |
+--------+-------------------+-------------+-------------+-----------------+
|{dti_in, dti_list}*| | | |
DTI | dti_extra | | | |
| dti_search_NO | | | |
+-~or~---+-------------------+-------------+-------------+-----------------+
| hardi_gfa* | | | |
HARDI | hardi_dirs* | | | |
| hardi_pars | | | |
==~and~==+===================+=============+=============+=================+
| mode* | | | |
OPTIONS | netrois* | | | |
| prefix* | | | |
| mask | | | |
| thru_mask | | | |
| targ_surf_stop | | | |
| targ_surf_twixt | | | |
| | logic* | logic* | |
| | | mini_num* | |
| | | uncert* | uncert* |
| | | unc_min_FA | unc_min_FA |
| | | unc_min_V | unc_min_V |
| algopt | | | |
| alg_Thresh_FA | | | |
| alg_Thresh_ANG | | | |
| alg_Thresh_Len | | | |
| | alg_Nseed_X | alg_Nseed_X | |
| | alg_Nseed_Y | alg_Nseed_Y | |
| | alg_Nseed_Z | alg_Nseed_Z | |
| | | | alg_Thresh_Frac |
| | | | alg_Nseed_Vox |
| | | | alg_Nmonte |
| uncut_at_rois | | | |
| do_trk_out | | | |
| trk_opp_orient | | | |
| dump_rois | | | |
| dump_no_labtab | | | |
| dump_lab_consec | | | |
| posteriori | | | |
| rec_orig | | | |
| tract_out_mode | | | |
| write_opts | | | |
| write_rois | | | |
| pair_out_power | | | |
+--------+-------------------+-------------+-------------+-----------------+
*above, asterisked options are REQUIRED for running the given '-mode'.
With DTI data, one must use either '-dti_in' *or* '-dti_list' for input.
FOR MODEL DTI:
-dti_in INPREF :basename of DTI volumes output by, e.g., 3dDWItoDT.
NB- following volumes are *required* to be present:
INPREF_FA, INPREF_MD, INPREF_L1,
INPREF_V1, INPREF_V2, INPREF_V3,
and (now) INPREF_RD (**now output by 3dTrackID**).
Additionally, the program will search for all other
scalar (=single brik) files with name INPREF* and will
load these in as additional quantities for WM-ROI
stats; this could be useful if, for example, you have
PD or anatomical measures and want mean/stdev values
in the WM-ROIs (to turn this feature off, see below,
'dti_search_NO'); all the INPREF* files must be in same
DWI space.
Sidenote: including/omitting a '_' at the end of INPREF
makes no difference in the hunt for files.
-dti_extra SET :if you want to use a non-FA derived definition for the
WM skeleton in which tracts run, you can input one, and
then the threshold in the -algopt file (or, via the
'-alg_Thresh_FA' option) will be applied to
thresholding this SET; similarly for the minimum
uncertainty by default will be set to 0.015 times the
max value of SET, or can be set with '-unc_min_FA'.
If the SET name is formatted as INPREF*, then it will
probably be included twice in stats, but that's not the
worst thing. In grid files, name of this quantity will
be 'XF' (stands for 'extra file').
-dti_search_NO :turn off the feature to search for more scalar (=single
brik) files with INPREF*, for including stats in output
GRID file. Will only go for FA, MD, L1 and RD scalars
with INPREF.
-dti_list FILE :an alternative way to specify DTI input files, where
FILE is a NIML-formatted text file that lists the
explicit/specific files for DTI input. This option is
used in place of '-dti_in' and '-dti_extra' for loading
data sets of FA, MD, L1, etc. An 'extra' set (XF) can
be loaded in the file, as well as supplementary scalar
data sets for extra WM-ROI statistics.
See below for a 'DTI LIST FILE EXAMPLE'.
FOR MODEL HARDI:
-hardi_gfa GFA :single brik data set with generalized FA (GFA) info.
In reality, it doesn't *have* to be a literal GFA, esp.
if you are using some HARDI variety that doesn't have
a specific GFA value-- in such a case, use whatever
could be thresholded as your proxy for WM.
The default threshold is still 0.2, so you will likely
need to set a new one in the '-algopt ALG_FILE' file or
from the commandline with '-alg_Thresh_FA', which does
apply to the GFA in the HARDI case as well.
Stats in GRID file are output under name 'GFA'.
-hardi_dirs DIRS :For tracking if X>1 propagation directions per voxel
are given, for example if HARDI data is input. DIRS
would then be a file with 3*X briks of (x,y,z) ordered,
unit magnitude vector components; i.e., brik [0]
contains V1_x, [1] V1_y, [2] V1_z, [3] V2_x, etc.
(NB: even if X=1, this option works, but that would
seem to take the HAR out of HARDI...)
-hardi_pars PREF :search for scalar (=single brik) files of naming
format PREF*. These will be read in for WM-ROI stats
output in the GRID file. For example, if there are
some files PREF_PD.nii.gz, PREF_CAT.nii.gz and
PREF_DOG.nii.gz, they will be labelled in the GRID file
as 'PD', 'CAT' and 'DOG' (that '_' will be cut out).
MODEL-INDEPENDENT OPTIONS:
-mode MODUS :this necessary option is used to define whether one is
performing deterministic, mini-probabilistic or full-
probabilistic tractography, by selecting one of three
respective modes: DET, MINIP, or PROB.
-netrois ROIS :mask(s) of target ROIs- single file can have multiple
briks, one per network. The target ROIs through which
tracks will be kept should have index values >0. It is
also possible to define anti-targets (exclusionary
regions) which stop a propagating track... in its
tracks. These are defined per network (i.e., per brik)
by voxels with values <0.
-prefix PREFIX :output file name part.
-mask MASK :can include a brainmask within which to calculate
things. Otherwise, data should be masked already.
-thru_mask TM :optional extra restrictor mask, through which paths are
(strictly) required to pass in order to be included
when passing through or connecting targets. It doesn't
discriminate based on target ROI number, so it's
probably mostly useful in examining specific pairwise
connections. It is also not like one of the target
'-netrois' in that no statistics are calculated for it.
Must be same number of briks as '-netrois' set.
-targ_surf_stop :make the final tracts and tracked regions stop at the
outer surface of the target ROIs, rather than being
able to journey arbitrarily far into them (latter being
the default behavior. Might be useful when you want
meaningful distances *between* targets. Tracts stop
after going *into* the outer layer of a target.
This can be applied to DET, MINIP, or PROB modes.
NB: this only affects the connections between pairs
of targets (= AND-logic, off-diagonal elements in
output matrices), not the single-target tracts
(= OR-logic, on-diagonal elements in output
matrices); see also a related option, below.
-targ_surf_twixt :quite similar to '-targ_surf_stop', above, but the
tracts stop *before* entering the target surfaces, so
that they are only between (or betwixt) the targets.
Again, only affects tracts between pairs of targets.
-logic {OR|AND} :when in one of '-mode {DET | MINIP}', one will look for
either OR- or AND-logic connections among target ROIs
per network (multiple networks can be entered as
separate briks in '-netrois ROIS'): i.e., one keeps
either any track going through at least one network ROI
or only those tracks which join a pair of ROIs.
When using AND here, default behavior is to only keep
voxels in tracks between the ROIs they connect (i.e.,
cut off track bits which run beyond ROIs).
-mini_num NUM :will run a small number NUM of whole brain Monte Carlo
iterations perturbing relevant tensor values in accord
with their uncertainty values (hence, the need for also
using `-uncert' with this option). This might be useful
for giving a flavor of a broader range of connections
while still seeing estimated tracks themselves. NB: if
NUM is large, you might be *big* output track files;
e.g., perhaps try NUM = 5 or 9 or so to start.
Requires '-mode MINIP' in commandline.
-bundle_thr V :the number of tracts for a given connection is called
a bundle. For '-mode {DET | MINIP}', one can choose to
NOT output tracts, matrix info, etc. for any bundle
with fewer than V tracts. This might be useful to weed
out ugly/false tracts (default: V=1).
-uncert U_FILE :when in one of '-mode {MINIP | PROB}', uncertainty
values for eigenvector and WM skeleton (FA, GFA, etc.)
maps are necessary.
When using DTI ('-dti_*'), then use the 6-brik file
from 3dDWUncert; format of the file given below.
When using HARDI ('-hardi_*') with up to X directions
per voxel, one needs U_FILE to have X+1 briks, where
U_FILE[0] is the uncertainty for the GFAfile, and the
other briks are ordered for directions given with
'-hardi_dirs'.
Whatever the values in the U_FILE, this program asserts
a minimum uncertainty of stdevs, with defaults:
for FA it is 0.015, and for GFA or -dti_extra sets it
is 0.015 times the max value present (set with option
'-unc_min_FA');
for each eigenvector or dir, it is 0.06rad (~3.4deg)
(set with option '-unc_min_V')
-unc_min_FA VAL1 :when using '-uncert', one can control 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 :when using '-uncert', one can control the minimum
stdev for perturbing eigen-/direction-vectors.
In DTI, this is for tipping e_1 separately toward e2
and e3, and in HARDI, this is for defining a single
degree of freedom uncertainty cone. Default values are
0.06rad (~3.4deg) for any eigenvector/direction. User
assigns values in degrees.
-algopt A_FILE :simple ASCII file with six numbers defining tracking
parameter quantities (see list below); note the
differences whether running in '-mode {DET | MINIP}'
or in '-mode PROB': the first three parameters in each
mode are the same, but the next three differ.
The file can be in the more understandable html-type
format with labels per quantity, or just as a column
of the numbers, necessarily in the correct order.
NB: each quantity can also be changed individually
using a commandline option (see immediately following).
If A_FILE ends with '.niml.opts' (such as would be
produced using the '-write_opts' option), then it is
expected that it is in nice labelled NIML format;
otherwise, the file should just be a column of numbers
in the right order. Examples of A_FILEs are given at
the end of the option section.
-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).
-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).
+-------> NB: in summation, for example the alg_Nseed_* options
for '-mode {DET | MINIP} place 2x2x2=8 seed points,
equally spread in a 3D cube, in each voxel when
tracking.
-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). (efault = 0.001; for higher
specificity, a value of 0.01-0.05 could 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).
+-------> NB: in summation, the preceding three options for the
'-mode PROB' will mean that 'I' Monte Carlo
iterations will be run, each time using 'H' track
seeds per relevant voxel, and that a voxel will
need 'G*H*I' tracks of a given connection through
it to be included in that WM-ROI. Default example:
1000 iterations with 5 seeds/voxel, and therefore
a candidate voxel needs at least 0.001*5*1000 = 5
tracks/connection.
-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:
NTpTarVol :div. by average target volume;
NTpTarSA :div. by average target surface area;
NTpTarSAFA :div. by average target surface area
bordering suprathreshold FA (or equi-
valent WM proxy definition).
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.)
-uncut_at_rois :when looking for pairwise connections, keep entire
length of any track passing through multiple targets,
even when part ~overshoots a target (i.e., it's not
between them). When using OR tracking, this is
automatically applied. For probabilistic tracking, not
recommended to use (are untrimmed ends meaningful?).
The default behavior is to trim the tracts that AND-
wise connect targets to only include sections that are
between the targets, and not parts that run beyond one.
(Not sure why one would want to use this option, to be
honest; see '-targ_surf_stop' for really useful tract
control.)
-dump_rois TYPE :can output individual masks of ROI connections.
Options for TYPE are: {DUMP | AFNI | BOTH | AFNI_MAP}.
Using DUMP gives a set of 4-column ASCII files, each
formatted like a 3dmaskdump data set; it can be recon-
stituted using 3dUndump. Using AFNI gives a set of
BRIK/HEAD (byte) files in a directory called PREFIX;
using AFNI_MAP is like using AFNI, but it gives non-
binarized *maps* of ROI connections.
Using BOTH produces AFNI and DUMP formats of outputs.
-dump_no_labtab :if the ROIS file has a label table, the default is to
use it in naming a '-dump_rois' output (if being used);
using this switch turn that off-- output file names
will be the same as if no label table were present.
-dump_lab_consec :if using `-dump_rois', then DON'T apply the numerical
labels of the original ROIs input to the output names.
This would only matter if input ROI labels aren't
consecutive and starting with one (e.g., if instead
they were 1,2,3,5,8,..).
---> This is the opposite from previous default behavior, where
the option '-lab_orig_rois' was used to switch away
from consecutive-izing the labels in the output.
-posteriori :switch to have a bunch of individual files output, with
the value in each being the number of tracks per voxel
for that pair; works with '-dump_rois {AFNI | BOTH }',
where you get track-path maps instead of masks; makes
threshold for number of tracks between ROIs to keep to
be one automatically, regardless of setting in algopt.
-rec_orig :record dataset origin in the header of the *.trk file.
As of Sept. 2012, TrackVis doesn't use this info so it
wasn't included, but if you might want to map your
*.trk file later, then use the switch as the datasets's
Origin is necessary info for the mapping (the default
image in TrackVis might not pop up in the center of the
viewing window, though, just be aware). NB: including
the origin might become default at some point in time.
-do_trk_out :Switch ON outputting *.trk files, which are mainly to
be viewed in TrackVis (Wang et al., 2007).
(Feb, 2015): Default is to NOT output *.trk files.
-trk_opp_orient :If outputting *.trk files, you can choose to oppositize
the voxel_order parameter for the TRK file (only).
Thus, when inputting AFNI files with orient RAI, the
*.trk file would have voxel_order LPS; this is so that
files can be viewed in some other software, such as
DTK.
-nifti :output the PAIRMAP, INDIMAP, and any '-dump_rois' in
*.nii.gz format (default is BRIK/HEAD).
-no_indipair_out :Switch off outputting *INDIMAP* and *PAIRMAP* volumes.
This is probably just if you want to save file space;
also, for connectome-y studies with many (>100) target
regions, the output INDI and PAIR maps can be quite
large and/or difficult to write out. In some cases, it
might be better to just use '-dump_rois AFNI' instead.
Default is to output the INDI and PAIR map files.
-write_rois :write out a file (PREFIX.roi.labs) of all the ROI
(re-)labels, for example if the input ROIs aren't
simply consecutive and starting from 1. File has 3cols:
Input_ROI Condensed_form_ROI Power_of_2_label
-write_opts :write out all the option values into PREFIX.niml.opts.
-pair_out_power :switch to affect output of *PAIRMAP* output files.
Now, the default format is to output the >0 bricks with
tracks labelled by the target integers themselves.
This is not a unique labelling system, but it *is* far
easier to view and understand what's going on than
using a purely unique system based on using powers of
two of the ROIs (with integer summation for overlaps).
Using the switch '-pair_out_power' will change the
output of bricks [1] and higher to contain
information on connections stored as powers of two, so
that there is a unique decomposition in terms of
overlapped connections. However, it's *far* easier to
use '-dump_rois {AFNI | BOTH }' to get individual mask
files of the ROIs clearly (as well as annoying to need
to calculate powers of two simply to visualize the
connections.
-----> when considering this option, see the 'LABELTABLE'
description up above for how the labels work, with
or without an explicit table being entered.
-verb VERB :verbosity level, default is 0.
****************************************************************************
+ ALGOPT FILE EXAMPLES (note that different MODES have some different opts):
For '-mode {DET | MINIP}, the nicely readable NIML format of algopt file
would have a file name ending '.niml.opts' and contain something like the:
following seven lines:
<TRACK_opts
Thresh_FA="0.2"
Thresh_ANG="60.000000"
Thresh_Len="20.000000"
Nseed_X="2"
Nseed_Y="2"
Nseed_Z="2" />
The values above are actually all default values, and such a file would be
output using the '-write_opts' flag. For the same modes, one could get
the same result using a plain column of numbers, whose meaning is defined
by their order, contained in a file NOT ending in .niml.opts, such as
exemplified in the next six lines:
0.2
60
20
2
2
2
For '-mode PROB', the nice NIML format algopt file would contain something
like the next seven lines (again requiring the file name to end in
'.niml.opts'):
<TRACK_opts
Thresh_FA="0.2"
Thresh_ANG="60.0"
Thresh_Len="20.0"
Thresh_Frac="0.001"
Nseed_Vox="5"
Nmonte="1000" />
Again, those represent the default values, and could be given as a plain
column of numbers, in that order.
* * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * **
+ DTI LIST FILE EXAMPLE:
Consider, for example, if you hadn't used the '-sep_dsets' option when
outputting all the tensor information from 3dDWItoDT. Then one could
specify the DTI inputs for this program with a file called, e.g.,
FILE_DTI_IN.niml.opts (the name *must* end with '.niml.opts'):
<DTIFILE_opts
dti_V1="SINGLEDT+orig[9..11]"
dti_V2="SINGLEDT+orig[12..14]"
dti_V3="SINGLEDT+orig[15..17]"
dti_FA="SINGLEDT+orig[18]"
dti_MD="SINGLEDT+orig[19]"
dti_L1="SINGLEDT+orig[6]"
dti_RD="SINGLEDT+orig[20]" />
This represents the *minimum* set of input files needed when running
3dTrackID. (Oct. 2016: RD now output by 3dDWItoDT, and not calc'ed
internally by 3dTrackID.)
One could also input extra data: an 'extra file' (XF) to take the place
of an FA map for determining where tracks can propagate; and up to four
other data sets (P1, P2, P3 and P4, standing for 'plus one' etc.) for
calculating mean/stdev properties in the obtained WM-ROIs:
<DTIFILE_opts
dti_V1="SINGLEDT+orig[9..11]"
dti_V2="SINGLEDT+orig[12..14]"
dti_V3="SINGLEDT+orig[15..17]"
dti_XF="Segmented_WM.nii.gz"
dti_FA="SINGLEDT+orig[18]"
dti_MD="SINGLEDT+orig[19]"
dti_L1="SINGLEDT+orig[6]"
dti_RD="SINGLEDT+orig[20]"
dti_P1="SINGLEDT+orig[7]"
dti_P2="SINGLEDT+orig[8]"
dti_P3="T1_map.nii.gz"
dti_P4="PD_map.nii.gz" />
****************************************************************************
+ EXAMPLES:
Here are just a few scenarios-- please see the Demo data set for *maaany*
more, as well as for fuller descriptions. To obtain the Demo, type the
following into a commandline:
$ @Install_FATCAT_demo
This will also unzip the archive, which contains required data (so it's
pretty big, currently >200MB), a README.txt file, and several premade
scripts that are ~heavily commented.
A) Deterministic whole-brain tracking; set of targets is just the volume
mask. This can be useful for diagnostic purposes, sanity check for
gradients+data, for interactively selecting interesting subsets later,
etc. This uses most of the default algopts, but sets a higher minimum
length for keeping tracks:
$ 3dTrackID -mode DET \
-dti_in DTI/DT \
-netrois mask_DWI+orig \
-logic OR \
-alg_Thresh_Len 30 \
-prefix DTI/o.WB
B) Mini-probabilistic tracking through a multi-brik network file using a
DTI model and AND-logic. Instead of using the thresholded FA map to
guide tracking, an extra data set (e.g., a mapped anatomical
segmentation image) is input as the WM proxy; as such, what used to be
a threshold for adult parenchyma FA is now changed to an appropriate
value for the segmentation percentages; and this would most likely
also assume that 3dDWUncert had been used to calculate tensor value
uncertainties:
$ 3dTrackID -mode MINIP \
-dti_in DTI/DT \
-dti_extra T1_WM_in_DWI.nii.gz \
-netrois ROI_ICMAP_GMI+orig \
-logic AND \
-mini_num 7 \
-uncert DTI/o.UNCERT_UNC+orig. \
-alg_Thresh_FA 0.95 \
-prefix DTI/o.MP_AND_WM
C) Full probabilistic tracking through a multi-brik network file using
HARDI-Qball reconstruction. The designated GFA file is used to guide
the tracking, with an appropriate threshold set and a smaller minimum
uncertainty of that GFA value (from this and example B, note how
generically the '-alg_Thresh_FA' functions, always setting a value for
the WM proxy map, whether it be literally FA, GFA or the dti_extra
file). Since HARDI-value uncertainty isn't yet calculable in AFNI,
brain-wide uniform values were assigned to the GFA and directions:
$ 3dTrackID -mode PROB \
-hardi_gfa QBALL/GFA.nii.gz \
-hardi_dirs QBALL/dirs.nii.gz \
-netrois ROI_ICMAP_GMI+orig \
-uncert QBALL/UNIFORM_UNC+orig. \
-mask mask_DWI+orig \
-alg_Thresh_FA 0.04 \
-unc_min_FA 0.003 \
-prefix QBALL/o.PR_QB
****************************************************************************
If you use this program, please reference the workhorse FACTID
tractography algorithm:
Taylor PA, Cho K-H, Lin C-P, Biswal BB (2012). Improving DTI
Tractography by including Diagonal Tract Propagation. PLoS ONE
7(9): e43415.
and the introductory/description paper for FATCAT:
Taylor PA, Saad ZS (2013). FATCAT: (An Efficient) Functional And
Tractographic Connectivity Analysis Toolbox. Brain Connectivity.
This page auto-generated on
Thu Oct 31 09:42:43 PM EDT 2024