:orphan: .. _ahelp_3dDWUncert: ********** 3dDWUncert ********** .. contents:: :local: | OVERVIEW ======== .. code-block:: none 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 ====== .. code-block:: none 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 ======= .. code-block:: none 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 ===================== .. code-block:: none 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'): 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 ======================================= .. code-block:: none + 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 ======== .. code-block:: none 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 ====== .. code-block:: none 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.