AFNI program: 3dDWUncert

Output of -help


 OVERVIEW ~1~

  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~

     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 ~1~

   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 ~1~

     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)~1~

 + 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~

    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 ~1~

  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.

____________________________________________________________________________
This page auto-generated on Thu Oct 31 09:41:33 PM EDT 2024