:orphan:

.. _ahelp_3dDTtoNoisyDWI:

**************
3dDTtoNoisyDWI
**************

.. contents:: :local:


| 

.. code-block:: none

    
      Take an AFNI-style DT file as input, such as might be output by 3dDWItoDT
      (which means that the DT elements are ordered: Dxx,Dxy,Dyy,Dxz,Dyz,Dzz),
      as well as a set of gradients, and then generate a synthetic set of DWI
      measures with a given SNR. Might be useful for simulations/testing.
    
      Part of FATCAT (Taylor & Saad, 2013) in AFNI.
      It is similar in premise to 3dDTtoDWI, however this allows for the modeled
      inclusion of Rician noise (such as appears in MRI magnitude images).
    
    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
    
      + COMMAND: 3dDTtoNoisyDWI -dt_in DTFILE -grads GRADFILE -noise_frac0 FF \
               {-bval BB} {-S0 SS} {-mask MASK } -prefix PREFIX 
    
    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
    
      + OUTPUT:
         1) If N gradients are input, then the output is a file with N+1 bricks
         that mimics a set of B0+DWI data (0th brick is the B0 reference).
    
      + RUNNING:
        -dt_in DTFILE    :diffusion tensor file, which should have six bricks
                          of DT components ordered in the AFNI (i.e., 3dDWItoDT)
                          manner:
                          Dxx,Dxy,Dyy,Dxz,Dyz,Dzz.
        -grads GRADFILE  :text file of gradients arranged in three columns.
                          It is assumed that there is no row of all zeros in the
                          GRADFILE (i.e., representing the b=0 line).
                          If there are N rows in GRADFILE, then the output DWI
                          file will have N+1 bricks (0th will be the b=0
                          reference set of noise S0 measures).
        -noise_DWI  FF   :fractional value of noise in DWIs. The magnitude will
                          be set by the b=0 reference signal, S0. Rician noise
                          is used, which is characterized by a standard
                          deviation, sigma, so that FF = sigma/S0 = 1/SNR0.
                          For example, FF=0.05 roughly corresponds to an 
                          SNR0=20 'measurement'.
        -noise_B0   FF2  :optional switch to use a different fraction of Rician
                          noise in the b=0 reference image; one might consider
                          it realistic to have a much lower level of noise in
                          the reference signal, S0, mirroring the fact that
                          generally multiple averages of b=0 acquisitions are
                          averaged together. If no fraction is entered here,
                          then the simulation will run with FF2=FF.
        -prefix PREFIX   :output file name prefix. Will have N+1 bricks when
                          GRADFILE has N rows of gradients.
        -mask   MASK     :can include a mask within which to calculate uncert.
                          Otherwise, data should be masked already.
    
        -bval BB         :optional DW factor to use if one has DT values scaled
                          to something physical (NB: AFNI 3dDWItoDT works in a 
                          world of b=1, so the default setting here is BB=1; one
                          probably doesn't need to change this if using DTs made
                          by 3dDWItoDT).
        -S0  SS          :optional reference b=0 signal strength.  Default value
                          SS=1000.  This just sets scale of output.
    
    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
    
      + EXAMPLE:
        3dDTtoNoisyDWI             \
          -dt_in DTI/DT_DT+orig    \
          -grads GRADS.dat         \
          -noise_DWI 0.1           \
          -noise_B0  0             \
          -prefix NEW_DWIs_SNR10   
    
    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
    
      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 3(5):523-535.