This function computes the parameters of a micro-structural model for diffusion MRI acquired in multiple shells (i.e., with multiple b-values), defined by a linear spherical convolution with an ODF as follows:
atti(u,b) = (1-f)*exp(-b*Diso) + f*Integral_{S}Phi(v)exp(-b*((lpar-lperp)(u*v)^2+lperp))dv,
where lpar and lperp parameterize the impulse response as an elemental rank-2 tensor, f stands for the partial volume fraction of water confined in the neural axons, and Diso is the free-water (extra-cellular) diffusivity. Phi(v) is the ODF, which has integral 1 in the unit sphere S.
- Parameters
-
dwifile | A string specifying the file containing the S_i/S_0 (diffusion gradients over non-weighted baseline) at each voxel within the MxNxP image frame and for each of the G acquired image gradients. |
gifile | A string specifying the file containing the gradients table, each row corresponding to a unit vector with the direction of the acquired gradient. |
bifile | A string specifying the file containing the b-values used at each gradient direction, so that a multi-shell acquisition is arranged. |
lambdaparfile | A string specifying the file to save the elemental diffusivity along the parallel direction. |
lambdaperpfile | A string specifying the file to save the elemental diffusivity along the perpendicular direction. |
ffile | A string specifying the file to save the partial volume fraction of non-free (i.e. fiber-confined) water at each imaged voxel. |
varargin | Optional arguments passed as -name value pairs (e.g. -lambda 0.006). |
- Returns
- - lambdapar: The elemental diffusivity along the parallel direction.
-
- lambdaperp: The elemental diffusivity along the perpendicular direction.
-
- f: The partial volume fraction of non-free water at each imaged voxel.
Mandatory Inputs:
- dwifile: A string specifying the file containing the diffusion gradients over non-weighted baseline.
- gifile: A string specifying the file containing the gradients table.
- bifile: A string specifying the file containing the b-values.
- lambdaparfile: A string specifying the file to save the elemental diffusivity along the parallel direction.
- lambdaperpfile: A string specifying the file to save the elemental diffusivity along the perpendicular direction.
- ffile: A string specifying the file to save the partial volume fraction.
- varargin: Optional arguments passed as -name value pairs (e.g. -lambda 0.006).
Optional Arguments - General Optional Parameters:
- lambda: The Laplace-Beltrami regularization parameter for the linear least squares problem that fits SH coeffcients to the signals to compute their orientational averages (default 0.006)
- tl, tu: The lower and upper thresholds, respectively, defining the range the dwi will lay within, so that tl should be close to 0 and tu should be close to 1 (default: 1.0e-7, 1-1.0e-7).
- usef: Wether (true) or not (false) computing the free water compartment within each voxel. The optimization is carried out by means of a multi-level greedy search algorithm: a set of values of f within the allowed range is probed and the one that best fits the model is selected. For the next resolution level, the allowed range is narrowed around such f and the process is repeated.
- Note
- this estimation dramatically increases the computational load of the method as explained below (default:false).
- ADC0: Estimated diffusivity of free water at body temperature (default: 3.0e-3).
For Estimating the Fiber-Impulse Response at Each Voxel:
- mlperp: Minimum allowed value for lambdaperp in all cases, so that it will not fall down to zero and the model will not become singular. You can pass just zero to obtain the original non-regularized model (default: 0.01e-3).
- mu: This is a regularization term imposing a penalty to close-to-singular tensor models, i.e. those voxels with lambdaperp <<< lambdapar. You can pass just zero to obtain the original non-regularized model (default: 5.0e-5).
- nu: This is a regularization parameter with the exact opposite meaning as the previous one, i.e. it penalizes close-to-spherical tensor models, i.e. those voxels with lambdaperp->lambdapar. You can pass just zero to obtain the original non-regularized model (default: 0.0).
- nmax: Maximum number of iterations in the Newton-Raphson optimization (default: 100).
- dl: Maximum allowed change in both lambda_par and lambda_perp before the Newton Raphson iterations stop (default: 1.0e-8).
- dC: Maximum allowed change in the cost function before the Newton-Raphson iterations stop (default: 1.0e-6).
- regf: Wether (true) or not (false) use the regularization parameter mu while optimizing for f (it makes sense only if the 'usef' flag is on). Otherwise, it will first fit f without regularizing the micro-structure model, then correct the spherical means with such value, then re-compute lamdapar and lambdaperp with the regularization term (default: true).
- lpar: This parameter makes sense only if:
- just 1 shell is acquired.
- 2 shells are acquired and the user asks for the estimation of the free water comparment.
- Option 'forcelar' is set true.
In all these cases, lambdapar will not be estimated, so it has to be externally fixed.
- Note
- the user is responsible of giving lpar a physically meaningful value, since this will not be internally checked. It should be less than ADC0, and an appropriate value could be around 1.7e-3. This parameter may be either a scalar (default: 1.7e-3) or an MxNxP volume.
- forcelpar: 1x1 logical, this flag may be set true so that the algorithm uses a fixed value for the parallel diffusivity (the one set with option lpar) instead of estimating its actual value (default: false).
- nolpwarn: In case the function is called in a way that lamdapar has to be fixed to a constant, it will rise a warning unless this flag is set 'true' (default: false).
For the Free-Water Compartment Isolation (only if usef=true):
- fmin, fmax: The lower and upper limits where f will be looked for at each image voxel, so that fmin should be 0 and fmax should be 1 (or close to 1) (default: 0.01, 1).
Other General Options:
- mask: An array of logicals. Only voxels where mask is true are processed (default: none).
- bth: B-values that differ from each other less than this threshold are assumed to belong to the same shell (default: 1).
- chunksz: To improve the performance of certain operations, cunksz voxels are processed together.
- Note
- that decrasing this value can dramatically slow down processing in parallel (default: 10000).
- verbose: Wether (true) or not (false) show additional information on the progress of the algorithm (default: false).
Example:
atti2micro dwifile.nii gifile.bvec bifile.bval lambdaparfile.nii lambdaperpfile.nii ffile.nii -mask mask_file.nii -usef 1
function atti2micro(in dwifile, in gifile, in bifile, in lambdaparfile, in lambdaperpfile, in ffile, in varargin)
- Note
- This is the simplest use case
- See also
- atti2micro