Given the attenuation signal atti (computed as S_i/S_0), the gradients table gi, and the b-values bi it corresponds to, computes the diffusion tensor model and the correction to S_0 that best explains it by following this procedure:
- Use ordinary least squares (OLS) to fit the logarithm of atti to a diffusion tensor model linearly.
- If asked, refine the previous solution using weighted least squares (WLS) with weight proportional to A_i^2, where A_i are iteratily estimated using the previous value of the estimated tensor.
- If asked, use the previous solution as the initial iteration of an iterative, non-linear estimation procedure in the natural (as opposed to the logarithmic) domain. Here, it is the squared root of the diffusion tensor, instead of the diffusion tensor itself, which is actually estimated, ensuring the final solution is positive semi-definite.
In either 1-) or 2-), the function allows to project the solution in the space of positive semi-definite matrixes by either clipping negative eigenvalues to 0 or computing their absolute value.
- Parameters
-
dwifile | A string specifying the file containing the diffusion-weighted images. |
gifile | A string specifying the file containing the gradient directions. |
bifile | A string specifying the file containing the b-values. |
tensorfile | A string specifying the file to save the diffusion tensor model. |
s0file | A string specifying the file to save the estimated S0 for normalization. |
varargin | Optional arguments passed as -name value pairs (e.g. -wlsit 5). |
- Returns
- - tensorfile: The diffusion tensor model.
-
- s0file: The estimated S0 for normalization.
Mandatory Inputs:
- dwifile: A string specifying the file containing the diffusion-weighted images.
- gifile: A string specifying the file containing the gradient directions.
- bifile: A string specifying the file containing the b-values.
- tensorfile: A string specifying the file to save the diffusion tensor model.
- s0file: A string specifying the file to save the estimated S0 for normalization.
- varargin: Optional arguments passed as -name value pairs.
Optional Arguments
- wls: either (true) or not (false) using weighted least squares instead of ordinary least squares (default: true).
- nonlinear: either (true) or not (false) using the nonlinear fit (default: false).
- wlsit: in case wls is switched on, the maximum number of iterations for the problem (default: 5).
- wsc: the minimum weight to be applied in the WLS problem with respect to the maximum one (default: 0.01).
- tol: Levenberg-Marquardt's tolerance for the nonlinear optimization procedure, meaning: iterations will stop if the relative change in the solution (for a seccessful iteration) is below this threshold (default: 1.0e-6).
- maxiters: maximum number of iterations in Levenberg-Marquardt's algorithm (default: 100).
- rcondth: minimum allowed reciprocal condition number for matrix inversions (default: 1.0e-6).
- fixmode: either 'n', 'z', or 'a', respectively meaning: no correction of negative eigenvalues, zero-clipping or absolute value (default: 'n').
- unroll: wether (true) or not (false) output the result as a 3x3 matrix at each voxel instead of a 6x1 vector (in the latter case duplicates of the entries of the diffusion tensor are removed so that only [D11,D12,D13,D22,D23,D33] are returned) (default: false).
- mask: a MxNxP array of logicals. Only those voxels where mask is true are processed, the others are filled with zeros.
- maxthreads: the algorithm is run with multiple threads. This is the maximum allowed number of threads, which can indeed be reduced if it exceeds the number of logical cores (default: the number of logical cores in the machine).
Example:
atti2dti dwifile.nii gifile.bvec bifile.bval tensorfile.nii s0file.nii -mask mask_file.nii
function atti2dti(in dwifile, in gifile, in bifile, in tensorfile, in s0file, in varargin)
- Note
- This is the simplest use case
- See also
- dwi2atti, atti2dti, parsevarargin, write_nifti_from_struct.