AFNI program: fat_proc_dwi_to_dt

Output of -help

-------------------------------------------------------------------------

 This program is for doing tensor and DT parameter fitting, as well as
 the uncertainty of DT parameters that are needed for tractography.

  Ver. 3.21 (PA Taylor, Sep 27, 2021)

-------------------------------------------------------------------------

  RUNNING:

  This script has two *required* arguments ('-in_dwi ...' and some
  kind of gradient/matrix file input.  

  The rest are optional, but it is highly recommended to input a
  reference data set ('-in_ref ...')  if you have used a processing
  tool that resets origin+orientation (such as TORTOISE), as well as
  using '-scale_out_1000' to make the output units of the physical DT
  measures nicer.

  fat_proc_dwi_to_dt  \
   -in_dwi       DWI                              \
   {-in_col_matA | -in_col_matT |                 \
    -in_col_vec | -in_row_vec} GRADMAT            \
   -prefix        PPP                             \
   {-in_bvals     BVAL}                           \
   {-mask         MASK}                           \
   {-mask_from_struc}                             \
   {-in_struc_res STRUC}                          \
   {-in_ref_orig  REF}                            \
   {-prefix_dti   PREFIX_D}                       \
   {-flip_x | -flip_y | -flip_z | -no_flip}       \
   {-no_scale_out_1000}                           \
   {-no_reweight}                                 \
   {-no_cumulative_wts}                           \
   {-qc_prefix    QCPREF}                         \
   {-qc_fa_thr    TTT}                            \
   {-qc_fa_max    MMM}                            \
   {-qc_fa_unc_max UM}                            \
   {-qc_v12_unc_max V}                            \
   {-no_qc_view}                                  \
   {-no_cmd_out}                                  \
   {-workdir WWW}                                 \
   {-no_clean}                                    \
   {-uncert_off}                                  \
   {-uncert_iters NN}                             \
   {-uncert_extra_cmds STR}

  where:

    -in_dwi  DWI     :4D volume of N DWIs. Required.

    -in_col_matA | 
    -in_col_matT | 
    -in_col_vec  | 
    -in_row_vec  GRADMAT
                     :input text file of N gradient vectors or 
                      bmatrices. By default, it is assumed that
                      these still have physical units in them (or that
                      there is an accompanying BVAL file input), so
                      scaling physical values by 1000 is on by default;
                      see turning this scaling off, if unnecessary, by 
                      using '-no_scale_out_1000', below.

    -prefix   PPP    :set prefix for output DWI data; required.

    -in_bvals   BVAL :optional, if bvalue information is
                      in a separate file from the b-vectors
                      or matrices; should have same number N as
                      volumes and vectors/matrices.
    -flip_x | 
    -flip_y | 
    -flip_z | 
    -no_flip         :can flip the DW grads, if needed; for example, 
                      based on the recommendation of @GradFlipTest.

  -check_abs_min VVV :briefly, this can help the program push through
                      finding tiny negative values (that miiiight be
                      due to rounding errors or small numerical
                      things) in columns that should only contain
                      numbers >=0. 'VVV' is basically a tolerance for
                      the magnitude of negative values you are willing
                      to allow: anything between [-VVV, 0) gets zeroed
                      for further calcs.  See 1dDW_Grad_o_Mat++'s help
                      for more information on this option (of the same
                      name).

   -mask    MASK     :optional whole brain mask can be input;
                      otherwise, automasking is performed for the 
                      region to be tensor and parameter fit.
   -mask_from_struc  :flag to make a mask using 3dSkullStrip+3dmask_tool
                      from the STRUC file.
        NB ---> If no "-mask*" option is given, then 3dAutomask is run on 
                the DWI set.  This often ain't great, so if TORTOISE isn't
                producing a mask, 1) email Okan and ask him about that, and
                2) try '-mask_from_struc'.
                ALSO, if you want the whole volume to be estimated
                tensorially for some reason, then make a volume fully
                filled with 1s and pass that in as the MASK, et voila
                (but then calcs will likely be slooow).

   -in_ref_orig REF  :use another data set to adjust the DWI (and
                      subsequent parameter) dsets' orientation and
                      origin; for example, TORTOISE has default 
                      orientation and origin for all output DWIs-- it
                      would be very advisable to use the anatomical
                      volume that you had input into TORTOISE as REF,
                      so that the DWIs should be viewable overlaying
                      it afterwards; if an ANAT (below) that has been 
                      merely resampled is *not* used, then you really, 
                      really want REF to have the same contrast as the
                      b=0 DWI volume. *Highly recommended to include!*
 -in_struc_res STRUC :accomplish the alignment of the output DWI to the 
                      REF data set via ANAT: a version of the anatomical 
                      that has been resampled to match the DWI set (in 
                      both orientation and origin);  for example, in
                      TORTOISE there is a 'structural.nii' file that should
                      match this description.  Both ANAT and DWI should 
                      then be well aligned to the original REF (and to  
                      each other). *Highly recommended to include!*
         
 -prefix_dti PREFIX2 :set prefix for output DTI data; optional, 
                      default is 'dt'. Do *not* include path 
                      information here-- that is only supplied using 
                      '-prefix ..'.

  -no_scale_out_1000 :by default, for tensor fitting it is assumed
                      that 1) the DW b-value information is included
                      in the gradient vectors or grads, and 2) you are
                      happy to have tiny numbers of physical
                      diffusion, which in standard units are like
                      MD~0.001 "mm^2/s", scaled by 1000 so that they
                      are returned as MD~1 "10^{-3} mm^2/s".  Isn't
                      that nicer?  I thought you'd agree-- therefore,
                      such a kind of scaling is *on* by default.  To
                      turn that *off*, use this option flag.
                      See the 3dDWItoDT help file for what this
                      entails.  Basically, you will likely have nicer
                      numeric values (from scaling physical length
                      units by 1000); otherwise, you might have small
                      numerical values leading to issues with
                      statistical modeling.

   -no_reweight      :by default, we *do* reweight+refit tensors during 
                      estimation; should improve fit.  But what do I
                      know?  This option turns that functionality *off*.
   -no_cumulative_wts :by default, show  overall weight factors for each 
                      gradient; may be useful as a quality control, but 
                      this option will turn that functionality *off*.

   -qc_fa_thr TTT    :set threshold for overlay FA volume in QC image
                      (default:  TTT=0.2, as for healthy adult human 
                      parenchyma).
   -qc_fa_max MMM    :set cbar max for overlay FA volume in QC image
                      (default:  MMM=0.9, a very large value even for 
                      healthy adult human parenchyma).
   -qc_fa_unc_max UM :set cbar max for overlay uncert (stdev) of FA 
                      in QC image (default:  UM=0.05).
   -qc_v12_unc_max V :set cbar max for overlay uncert (stdev) of V1 
                      towards the V2 direction for DTs, in QC image
                      (default:  UM=0.349 rads, which corresponds to  
                      20 deg).

   -qc_prefix QCPREF :can set the prefix of the QC image files separately
                      (default is '').

   -no_qc_view       :can turn off generating QC image files (why?)

   -no_cmd_out       :don't save the command line call of this program
                      and the location where it was run (otherwise, it is
                      saved by default in the ODIR/).

   -no_clean         :is an optional switch to NOT remove working 
                      directory: 
                        '__WORKING_dwi_to_dt' 
                      (default: remove working dir).
   -workdir WWW      :specify a working directory, which can be removed;
                      (default name = '__WORKING_dwi_to_dt').

   -uncert_off       :don't do uncertainty calc (default is to do so); 
                      perhaps if it is slow or you want *very* different
                      options.
   -uncert_iters NN  :set the number of Monte Carlo iterations for the
                      uncertainty calc (default NN=300).
-uncert_extra_cmds STR:put in extra commands for the uncertainty calcs
                      (see the 3dDWUncert helpfile for more opts).

# -----------------------------------------------------------------------

  EXAMPLE

    fat_proc_dwi_to_dt \
        -in_dwi       DWI.nii                \
        -in_col_matA  BMTXT_AFNI.txt         \
        -in_struc_res ../structural.nii      \
        -in_ref_orig  t2w.nii                \
        -mask         mask_DWI.nii.gz        \
        -prefix       OUTPUT/dwi

    or

    fat_proc_dwi_to_dt \
        -in_dwi        ap_proc_DRBUDDI_final.nii    \
        -in_col_matT   ap_proc_DRBUDDI_final.bmtxt  \
        -in_struc_res  structural.nii               \
        -in_ref_orig   t2w.nii                      \
        -mask_from_struc                            \
        -prefix        dwi_03/dwi


-------------------------------------------------------------------------
This page auto-generated on Thu Apr 18 14:46:40 EDT 2024