Convert set of DTI eigenvectors and eigenvalues to a diffusion tensor,
while also allowing for some potentially useful value-scaling and vector-
flipping.
May be helpful in converting output from different software packages.
Part of FATCAT (Taylor & Saad, 2013) in AFNI.
It is essentially the inverse of the existing AFNI command: 3dDTeig.
Minor note and caveat:
This program has been checked for consistency with 3dDWItoDT outputs (that
is using its output eigenvalues and eigenvectors to estimate a DT, which
was then compared with that of the original 3dDWItoDT fit).
This program will *mostly* return the same DTs that one would get from
using the eigenvalues and eigenvectors of 3dDWItoDT to very high agreement
The values generally match to <10**-5 or so, except in CSF where there can
be small/medium differences, apparently due to the noisiness or non-
tensor-fittability of the original DWI data in those voxels.
However, these discrepancies *shouldn't* really affect most cases of using
DTI data. This is probably generally true for reconstructing DTs of most
software program output: the results match well for most WM and GM, but
there might be trouble in partial-volumed and CSF regions, where the DT
model likely did not fit well anyways. Caveat emptor.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+ COMMAND: 3dEigsToDT -eig_vals NAME1 -eig_vecs NAME2 {-mask MASK } \
{-flip_x | -flip_y | flip_z} {-scale_eigs X} -prefix PREFIX
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+ OUTPUT:
1) AFNI-format DT file with 6 subbricks in the same format as output
by, for example, 3dDWItoDT (the lower triangular, row-wise
elements of the tensor in symmetric matrix form)
[0] Dxx
[1] Dxy
[2] Dyy
[3] Dxz
[4] Dyz
[5] Dzz
+ RUNNING:
-eig_vals NAME1 :Should be a searchable descriptor for finding all
three required eigenvalue files. Thus, on a Linux
commandline, one would expect:
$ ls NAME1
to list all three eigenvalue files in descending order
of magnitude. This program will also only take
the first three matches (not including doubling of
BRIK/HEAD files in AFNI-format).
-eig_vecs NAME2 :Should be a searchable descriptor for finding all
three required eigenvector files. Thus, on a Linux
commandline, one would expect:
$ ls NAME2
to list all three eigenvector files in order matching
the eigenvalue files. This program will also only take
the first three matches (not including doubling of
BRIK/HEAD files in AFNI-format).
-> Try to make NAME1 and NAME2 as specific as possible, so
that the search&load gets everything as right as possible.
Also, if using the wildcard character, '*', then make sure
to enclose the option value with apostrophes (see EXAMPLE,
below).
-prefix PREFIX :output file name prefix. Would suggest putting a 'DT'
label in it.
-mask MASK :can include a mask within which to calculate uncert.
Otherwise, data should be masked already.
-flip_x :change sign of first element of eigenvectors.
-flip_y :change sign of second element of eigenvectors.
-flip_z :change sign of third element of eigenvectors.
-> Only a single flip would ever be necessary; the combination
of any two flips is mathematically equivalent to the sole
application of the remaining one.
-scale_eigs X :rescale the eigenvalues, dividing by a number that is
X>0. Could be used to reintroduce the DW scale of the
original b-values, if some other program has
remorselessly scaled it away.
* * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * **
+ EXAMPLE:
3dEigsToDT \
-eig_vals 'DTI/DT_L*' \
-eig_vecs 'DTI/DT_V*' \
-prefix DTI/NEW_DT \
-scale_eigs 1000 \
-flip_y
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
If you use this program, please reference the introductory/description
paper for the FATCAT toolbox:
Taylor PA, Saad ZS (2013). FATCAT: (An Efficient) Functional And
Tractographic Connectivity Analysis Toolbox. Brain Connectivity.
