Computes the SH coefficients of the ODF that best fits the multi-shell attenuation signal atti (with gradients table gi and b-values bi) according to the convolutional model:
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 we aim at estimating.
- 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. |
lambdaparfile | A string specifying the file containing the elemental diffusivity along the parallel direction. |
lambdaperpfile | A string specifying the file contanining the elemental diffusivity along the perpendicular direction. |
ffile | A string specifying the file containing the partial volume fraction. |
varargin | Optional arguments passed as -name value pairs (e.g. -flperp 0.001). |
- Returns
- - shfile: The SH coefficients of the ODF at each imaged voxel.
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.
- lambdaparfile: A string specifying the file containing the parallel diffusvity modeling the impulse response (should fulfill 0<lpar<=Diso).
- lambdaperpfile: A string specifying the file containing the perpendicular diffusvity modeling the impulse response (should fulfill 0<lerp<lpar).
- ffile: A string specifying the file contanining the partial volume fraction of intra-cellular water (should fulfill 0<=f<=1). If an empty array is passed, then f=1 for all voxels is assumed, so that ones(M,N,P) has the same effect as [].
- varargin: Optional arguments passed as - name value pairs (e.g. -flperp 0.001).
Optional Arguments - General Optional Parameters:
- L: An even integer with the maximum order of the SH to be used (default: 8).
- lambda: The Laplace-Beltrami regularization parameter for the linear least squares problem (default 0.001).
- 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).
- ADC0: The estimated diffusivity of free water at body temperature (Diso). Should use the same as in atti2micro (default: 3.0e-3).
- mask: A MxNxP array of logicals. Only those voxels where mask is true are processed, the others are filled with isotropic ODFs (default: all trues).
Sanity Checks On The Micro-Structure Model:
- chkmod: Whether (true) or not (false) perform sanity checks over lpar and lperp as provided by atti2micro. If true, three corrections are performed:
- lpar is ensured to be in the range (ADC0/20,ADC0);
- lperp is ensured to be greater than lpar*flperp (see below);
- lperp is ensured to be less than lpar*Flperp (see below). (default: true)
- flperp: If chkmod == true, this parameter provides a lower threshold for lperp as a function of lpar (default: 0.001).
- Flperp: If chkmod == true, this parameter provides an upper threshold for lperp as a function of lpar (default: 0.999).
Advanced parameters:
- optimal: wether (true) or not (false) use a globally optimal
- (slower) LLS fitting of the ODF for all shells or a subotimal
- (faster) LLS fitting shell-by-shell (default: true).
- chunksz: if optimal == false, the LLS problem reduces to the product of the atti signal with a precomputed matrix. To improve the performance, cunksz voxels are processed together Note that decrasing this value can dramatically slow down processing in parallel (default: 1000).
- recrop: wether (true) or not (false) cropping again the signal to the interval [tl,tu] after the free-water compartment has been substracted (default: false).
- bth: 1x1, b-values that differ from each other less than this threshold are assumed to belong to the same shell (default: 1).
Examples:
micro2shodf dwifile.nii gifile.bvec bifile.bval lambdaparfile.nii lambdaperpfile.nii ffile.nii shfile.nii -mask mask_file.nii
function micro2shodf(in dwifile, in gifile, in bifile, in lambdaparfile, in lambdaperpfile, in ffile, in shfile, in varargin)
- Note
- This is the simplest use case
- See also
- micro2shodf