3dDWUncert

OVERVIEW

Use jackknifing to estimate uncertainty of DTI parameters which are
  important for probabilistic tractography on per voxel basis.

Produces useful input for 3dTrackID, which does both mini- and full
  probabilistic tractography for GM ROIs in networks, part of
  FATCAT (Taylor & Saad, 2013) in AFNI.

This version has been reprogrammed to include parallelized running via
OpenMP (as of Oct, 2016).  So, it has the potential to run a lot more
quickly, assuming you have an OpenMPable setup for AFNI. The types/formats
 of inputs and outputs have not changed from before.

OUTPUT

1) AFNI-format file with 6 subbricks, containing uncertainty
   information. The bricks are in the following order:
       [0] bias of e1 in direction of e2
       [1] stdev of e1 in direction of e2
       [2] bias of e1 in direction of e3
       [3] stdev of e1 in direction of e3
       [4] bias of FA
       [5] stdev of FA

RUNNING

   3dDWUncert -inset FILE -input [base of FA/MD/etc.] \
           {-grads | -bmatrix_FULL} FILE -prefix NAME -iters NUMBER

   ... where:

    -inset  FILE     :file with b0 and DWI subbricks
                      (e.g., input to 3dDWtoDTI)
    -prefix PREFIX   :output file name part.
    -input  INPREF   :basename of DTI volumes output by,
                      e.g., 3dDWItoDT or TORTOISE. Assumes format of name
                      is, e.g.:  INPREF_FA+orig.HEAD or INPREF_FA.nii.gz .
                      Files needed with same prefix are:
                      *FA*, *L1*, *V1*, *V2*, *V3* .
    -input_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 '-input INPREF'.
                      See below for a 'INPUT LIST FILE EXAMPLE'.

    -grads  FF       :file with 3 columns for x-, y-, and z-comps
                      of DW-gradients (which have unit magnitude).
                      NB: this option also assumes that only 1st DWI
                      subbrick has a b=0 image (i.e., all averaging of
                      multiple b=0 images has been done already); if such
                      is not the case, then you should convert your grads to
                      the bmatrix format and use `-bmatrix_FULL'.
  OR
    -bmatrix_Z  FF   :using this means that file with gradient info
                      is in b-matrix format, with 6 columns representing:
                      b_xx b_yy b_zz b_xy b_xz b_yz.
                      NB: here, bvalue per image is the trace of the bmatr,
                      bval = b_xx+b_yy+b_zz, such as 1000 s/mm^2. This
                      option might be used, for example, if multiple
                      b-values were used to measure DWI data; this is an
                      AFNI-style bmatrix that needs to be input.
    -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!

    -iters  NUMBER   :number of jackknife resample iterations,
                      e.g. 300.
    -mask   MASK     :can include a mask within which to calculate uncert.
                      Otherwise, data should be masked already.

    -calc_thr_FA  FF :set a threshold for the minimum FA value above which
                      one calculates uncertainty; useful if one doesn't want
                      to waste time calculating uncertainty in very low-FA
                      voxels that are likely GM/CSF.  For example, in adult
                      subjects one might set FF=0.1 or 0.15, depending on
                      SNR and user's whims (default: FF=-1, i.e., do all).
    -csf_fa NUMBER   :number marking FA value of `bad' voxels, such as
                      those with S0 value <=mean(S_i), which breaks DT
                      assumptions due to, e.g., bulk/flow motion.
                      Default value of this matches 3dDWItoDT value of
                      csf_fa=0.012345678.

* * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * **

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_L1="SINGLEDT+orig[6]" />

This represents the *minimum* set of input files needed when running
3dDWUncert. (Note that MD isn't needed here.)  You can also recycle a
NIMLly formatted file from '3dTrackID -dti_list'-- the extra inputs
needed for the latter are a superset of those needed here, and won't
affect anything detrimentally (I hope).

COMMENTS (mainly about running speedily

+ This program can be slow if you have looots of voxels and/or looots of
  of grads.  *But*, it is written with OpenMP parallelization, so you
  can make use of having multiple CPUs.  The system environment variable
  to specify the number of CPUs to use is OMP_NUM_THREADS.

  You can specify OMP_NUM_THREADS in your ~/.bashrc, ~/.cshrc or other
  shell RC file.  Or, you can set it in the script you are using.
  To verify that your OMP_NUM_THREAD variable has been set as you want,
  you can use command line program 'afni_check_omp', and see what number
  is output.

+ If your input DWI dataset has not masked, you probably should input a
  mask with '-mask ..', because otherwise the program will waste a looot
  of time calculating DWI uncertainty of air and skull and other things
  of no practical consequence.

EXAMPLES

1) Basic example (probably assuming data has been masked):
  3dDWUncert                                 \
  -inset TEST_FILES/DTI/fin2_DTI_3mm_1+orig  \
  -prefix TEST_FILES/DTI/o.UNCERT            \
  -input TEST_FILES/DTI/DT                   \
  -grads TEST_FILES/Siemens_d30_GRADS.dat    \
  -iters 300


2) Same as above, with mask include as opt:
  3dDWUncert                                 \
  -inset TEST_FILES/DTI/fin2_DTI_3mm_1+orig  \
  -prefix TEST_FILES/DTI/o.UNCERT            \
  -input TEST_FILES/DTI/DT                   \
  -grads TEST_FILES/Siemens_d30_GRADS.dat    \
  -mask  TEST_FILES/dwi_mask.nii.gz          \
  -iters 300

CITING

If you use this program, please reference the jackknifing algorithm done
with nonlinear fitting described in:

      Taylor PA, Biswal BB (2011). Geometric analysis of the b-dependent
      effects of Rician signal noise on diffusion tensor imaging
      estimates and determining an optimal b value. MRI 29:777-788.

and the introductory/description paper for the FATCAT toolbox:

      Taylor PA, Saad ZS (2013).  FATCAT: (An Efficient) Functional
      And Tractographic Connectivity Analysis Toolbox. Brain
      Connectivity 3(5):523-535.