AFNI program: 3dDWItoDT

Output of -help



 Usage: 3dDWItoDT [options] gradient-file dataset

 Computes 6 principle direction tensors from multiple gradient vectors
 and corresponding DTI image volumes.
 The program takes two parameters as input :  
    a 1D file of the gradient vectors with lines of ASCII floats:
            Gxi, Gyi, Gzi.
    Only the non-zero gradient vectors are included in this file (no G0 
    line). 
    ** Now, a '1D' file of b-matrix elements can alternatively be input,
        and *all* the gradient values are included!**
    A 3D bucket dataset with Np+1 sub-briks where the first sub-brik is the
    volume acquired with no diffusion weighting.

 OUTPUTS: 
     + you can output all 6 of the independent tensor values (Dxx, Dyy, 
       etc.), as well as all three eigenvalues (L1, L2, L3) and 
       eigenvectors (V1, V2, V3), and useful DTI parameters FA, MD and
       RD.
     + 'Debugging bricks' can also be output, see below.

 Options:
   -prefix pname = Use 'pname' for the output dataset prefix name.
                   [default='DT']

   -automask = mask dataset so that the tensors are computed only for
               high-intensity (presumably brain) voxels.  The intensity 
               level is determined the same way that 3dClipLevel works.

   -mask dset = use dset as mask to include/exclude voxels

 -bmatrix_NZ FF = switch to note that the input dataset is b-matrix, 
               not gradient directions, and there is *no* row of zeros 
               at the top of the file, similar to the format for the grad
               input: N-1 rows in this file for N vols in matched data set.
               There must be 6 columns of data, representing either elements
               of G_{ij} = g_i*g_j (i.e., dyad of gradients, without b-value
               included) or of the DW scaled version, B_{ij} = b*g_i*g_j.
               The order of components is: G_xx G_yy G_zz G_xy G_xz G_yz.
 -bmatrix_Z FF = similar to '-bmatrix_NZ' above, but assumes that first
               row of the file is all zeros (or whatever the b-value for
               the reference volume was!), i.e. there are N rows to the
               text file and N volumes in the matched data set.

 -bmatrix_FULL FF = exact same as '-bmatrix_Z FF' above (i.e. there are N
               rows to the text file and N volumes in the matched data set)
               with just a lot more commonsensical name.  Definitely would
               be preferred way to go, for ease of usage!

   -scale_out_1000 = increase output parameters that have physical units
               (DT, MD, RD, L1, L2 and L3) by multiplying them by 1000. This
               might be convenient, as the input bmatrix/gradient values 
               can have their physical magnitudes of ~1000 s/mm^2, for
               which typical adult WM has diffusion values of MD~0.0007
               (in physical units of mm^2/s), and people might not like so
               many decimal points output; using this option rescales the
               input b-values and would lead to having a typical MD~0.7
               (now in units of x10^{-3} mm^2/s).  If you are not using
               bmatrix/gradient values that have their physical scalings,
               then using this switch probably wouldn't make much sense.
               FA, V1, V2 and V3 are unchanged.

 -bmax_ref THR = if the 'reference' bvalue is actually >0, you can flag
                 that here.  Otherwise, it is assumed to be zero.
                 At present, this is probably only useful/meaningful if
                 using the '-bmatrix_Z ...' or '-bmatrix_FULL ...' 
                 option, where the reference bvalue must be found and 
                 identified from the input info alone.

   -nonlinear = compute iterative solution to avoid negative eigenvalues.
                This is the default method.

   -linear = compute simple linear solution.

   -reweight = recompute weight factors at end of iterations and restart

   -max_iter n = maximum number of iterations for convergence (Default=10).
                 Values can range from -1 to any positive integer less than
                 101. A value of -1 is equivalent to the linear solution.
                 A value of 0 results in only the initial estimate of the
                 diffusion tensor solution adjusted to avoid negative
                 eigenvalues.

   -max_iter_rw n = max number of iterations after reweighting (Default=5)
                    values can range from 1 to any positive integer less
                    than 101.

   -eigs = compute eigenvalues, eigenvectors, fractional anisotropy and mean
           diffusivity in sub-briks 6-19. Computed as in 3dDTeig

   -debug_briks = add sub-briks with Ed (error functional), Ed0 (orig.
                  error), number of steps to convergence and I0 (modeled B0
                  volume).
                  [May, 2017] This also now calculates two goodness-of-fit
                  measures and outputs a new PREFIX_CHI* dset that has two
                  briks:
                     brik [0]: chi^2_p,
                     brik [1]: chi^2_c.
                  These values are essentially calculated according to
                  Papadakis et al. (2003, JMRI), Eqs. 4 and 3,
                  respectively (in chi^2_c, the sigma value is the
                  variance of measured DWIs *per voxel*). Note for both
                  chi* values, only DWI signal values are used in the
                  calculation (i.e., where b>THR; by default,
                  THR=0.01, which can be changed using '-bmax_ref ...').
                  In general, chi^2_p values seem to be <<1, consistent
                  with Papadakis et al.'s Fig. 4; the chi^2_c values are
                  are also pretty consistent with the same fig and seem to
                  be best viewed with the upper limit being roughly =Ndwi
                  or =Ndwi-7 (with the latter being the given degrees
                  of freedom value by Papadakis et al.)
   -cumulative_wts = show overall weight factors for each gradient level
                     May be useful as a quality control

   -verbose nnnnn = print convergence steps every nnnnn voxels that survive
                    to convergence loops (can be quite lengthy).

   -drive_afni nnnnn = show convergence graphs every nnnnn voxels that
                       survive to convergence loops. AFNI must have NIML
                       communications on (afni -niml)

   -sep_dsets = save tensor, eigenvalues, vectors, FA, MD in separate
                datasets

   -csf_val n.nnn = assign diffusivity value to DWI data where the mean
                    values for b=0 volumes is less than the mean of the
                    remaining volumes at each voxel. The default value is
                    '1.0 divided by the max bvalue in the grads/bmatrices'.
                    The assumption is that there are flow artifacts in CSF
                    and blood vessels that give rise to lower b=0 voxels.
                    NB: MD, RD L1, L2, L3, Dxx, Dyy, etc. values are all
                    scaled in the same way.

   -min_bad_md N  = change the min MD value used as a 'badness check' for
                    tensor fits that have veeery (-> unreasonably) large MD
                    values. Voxels where MD > N*(csf_val) will be treated
                    like CSF and turned into spheres with radius csf_val 
                    (default N=100).
   -csf_fa n.nnn  = assign a specific FA value to those voxels described
                    above The default is 0.012345678 for use in tractography
                    programs that may make special use of these voxels

   -opt mname =  if mname is 'powell', use Powell's 2004 method for 
                 optimization. If mname is 'gradient' use gradient descent
                 method. If mname is 'hybrid', use combination of methods.
                 MJD Powell, "The NEWUOA software for unconstrained 
                 optimization without derivatives", Technical report DAMTP
                 2004/NA08, Cambridge University Numerical Analysis Group:
                 See:  http://www.ii.uib.no/~lennart/drgrad/Powell2004.pdf

   -mean_b0 = use mean of all b=0 volumes for linear computation and initial
              linear for nonlinear method

 Example:
  3dDWItoDT -prefix rw01 -automask -reweight -max_iter 10 \
            -max_iter_rw 10 tensor25.1D grad02+orig.

 The output is a 6 sub-brick bucket dataset containing 
     Dxx, Dxy, Dyy, Dxz, Dyz, Dzz
 (the lower triangular, row-wise elements of the tensor in symmetric matrix
 form). Additional sub-briks may be appended with the -eigs and -debug_briks
 options.  These results are appropriate as the input to 3dDTeig.


INPUT DATASET NAMES
-------------------
This program accepts datasets that are modified on input according to the
following schemes:
  'r1+orig[3..5]'                                    {sub-brick selector}
  'r1+orig<100..200>'                                {sub-range selector}
  'r1+orig[3..5]<100..200>'                          {both selectors}
  '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )'  {calculation}
For the gruesome details, see the output of 'afni -help'.

This page auto-generated on Thu Mar 28 19:35:20 EDT 2024