Classes and functions for fitting tensors
Diffusion Tensor
Methods
fit(data[, mask]) | Fit method of the DTI model class |
Fit method of the DTI model class
Parameters : | data : array
mask : array
|
---|
Calculate the apparent diffusion coefficient (ADC) in each direction of a sphere.
Parameters : | q_form : ndarray
sphere : a Sphere class instance
|
---|
Notes
The calculation of ADC, relies on the following relationship:
ADC = \vec{b} Q \vec{b}^T
Where Q is the quadratic form of the tensor.
Axial Diffusivity (AD) of a diffusion tensor. Also called parallel diffusivity.
Parameters : | evals : array-like
axis : int
|
---|---|
Returns : | ad : array
|
Notes
AD is calculated with the following equation:
AD = \lambda_1
Color fractional anisotropy of diffusion tensor
Parameters : | fa : array-like
evecs : array-like
|
---|---|
Returns : | rgb : Array with 3 channels for each color as the last dimension.
|
Returns eigenvalues and eigenvectors given a diffusion tensor
Computes tensor eigen decomposition to calculate eigenvalues and eigenvectors (Basser et al., 1994a).
Parameters : | tensor : array (3, 3)
min_diffusivity : float
|
---|---|
Returns : | eigvals : array (3,)
eigvecs : array (3, 3)
|
Constructs design matrix for DTI weighted least squares or least squares fitting. (Basser et al., 1994a)
Parameters : | gtab : A GradientTable class instance dtype : string
|
---|---|
Returns : | design_matrix : array (g,7)
|
The determinant of a tensor, given in quadratic form
Parameters : | q_form : ndarray
|
---|---|
Returns : | det : array
|
Calculate the deviatoric (anisotropic) part of the tensor [R7].
Parameters : | q_form : ndarray
|
---|---|
Returns : | A_squiggle : ndarray
|
Notes
The deviatoric part of the tensor is defined as (equations 3-5 in [R7]):
\widetilde{A} = A - \bar{A}
Where A is the tensor quadratic form and \bar{A} is the anisotropic part of the tensor.
[R7] | (1, 2) Daniel B. Ennis and G. Kindlmann, “Orthogonal Tensor Invariants and the Analysis of Diffusion Tensor Magnetic Resonance Images”, Magnetic Resonance in Medicine, vol. 55, no. 1, pp. 136-146, 2006. |
Calculates parameters for creating a Tensor instance
Calculates tensor parameters from the six unique tensor elements. This function can be passed to the Tensor class as a fit_method for creating a Tensor instance from tensors stored in a nifti file.
Parameters : | data : array_like (..., 6)
|
---|---|
Returns : | dti_params :
|
Fractional anisotropy (FA) of a diffusion tensor.
Parameters : | evals : array-like
axis : int
|
---|---|
Returns : | fa : array
|
Notes
FA is calculated using the following equation:
FA = \sqrt{\frac{1}{2}\frac{(\lambda_1-\lambda_2)^2+(\lambda_1- \lambda_3)^2+(\lambda_2-\lambda_3)^2}{\lambda_1^2+ \lambda_2^2+\lambda_3^2}}
Returns a tensor given the six unique tensor elements
Given the six unique tensor elments (in the order: Dxx, Dxy, Dyy, Dxz, Dyz, Dzz) returns a 3 by 3 tensor. All elements after the sixth are ignored.
Parameters : | D : array_like, (..., >6)
|
---|---|
Returns : | tensor : ndarray (..., 3, 3)
|
Calculate the isotropic part of the tensor [R8].
Parameters : | q_form : ndarray
|
---|---|
Returns : | A_hat: ndarray :
|
Notes
The isotropic part of a tensor is defined as (equations 3-5 of [R8]):
\bar{A} = \frac{1}{2} tr(A) I
[R8] | (1, 2) Daniel B. Ennis and G. Kindlmann, “Orthogonal Tensor Invariants and the Analysis of Diffusion Tensor Magnetic Resonance Images”, Magnetic Resonance in Medicine, vol. 55, no. 1, pp. 136-146, 2006. |
The linearity of the tensor [1]
Parameters : | evals : array-like
axis : int
|
---|---|
Returns : | linearity : array
|
Notes
Returns the six lower triangular values of the tensor and a dummy variable if b0 is not None
Parameters : | tensor : array_like (..., 3, 3)
b0 : float
|
---|---|
Returns : | D : ndarray
|
Mean Diffusivity (MD) of a diffusion tensor.
Parameters : | evals : array-like
axis : int
|
---|---|
Returns : | md : array
|
Notes
MD is calculated with the following equation:
MD = \frac{\lambda_1 + \lambda_2 + \lambda_3}{3}
Mode (MO) of a diffusion tensor [R9].
Parameters : | q_form : ndarray
|
---|---|
Returns : | mode : array
|
Notes
Mode ranges between -1 (linear anisotropy) and +1 (planar anisotropy) with 0 representing orthotropy. Mode is calculated with the following equation (equation 9 in [R9]):
Mode = 3*\sqrt{6}*det(\widetilde{A}/norm(\widetilde{A}))
Where \widetilde{A} is the deviatoric part of the tensor quadratic form.
References
[R9] | (1, 2, 3) Daniel B. Ennis and G. Kindlmann, “Orthogonal Tensor Invariants and the Analysis of Diffusion Tensor Magnetic Resonance Images”, Magnetic Resonance in Medicine, vol. 55, no. 1, pp. 136-146, 2006. |
Fit the tensor params using non-linear least-squares.
Parameters : | design_matrix : array (g, 7)
data : array ([X, Y, Z, ...], g)
min_signal : float, optional
weighting: str :
sigma: float :
jac : bool
|
---|---|
Returns : | nlls_params: the eigen-values and eigen-vectors of the tensor in each voxel. : |
Calculate the Frobenius norm of a tensor quadratic form
Parameters : | q_form: ndarray :
|
---|---|
Returns : | norm : ndarray
|
See also
np.linalg.norm
Notes
The Frobenius norm is defined as:
Math : | ||A||_F = [sum_{i,j} abs(a_{i,j})^2]^{1/2} |
---|
Computes ordinary least squares (OLS) fit to calculate self-diffusion tensor using a linear regression model [1].
Parameters : | design_matrix : array (g, 7)
data : array ([X, Y, Z, ...], g)
min_signal : default = 1
|
---|---|
Returns : | eigvals : array (..., 3)
eigvecs : array (..., 3, 3)
|
See also
WLS_fit_tensor, decompose_tensor, design_matrix
Notes
y = \mathrm{data} \\ X = \mathrm{design matrix} \\ \hat{\beta}_\mathrm{OLS} = (X^T X)^{-1} X^T y
References
[1] | (1, 2, 3, 4) Chung, SW., Lu, Y., Henry, R.G., 2006. Comparison of bootstrap approaches for estimation of uncertainties of DTI parameters. NeuroImage 33, 531-541. |
The planarity of the tensor [1]
Parameters : | evals : array-like
axis : int
|
---|---|
Returns : | linearity : array
|
Notes
Find the closest orientation of an evenly distributed sphere
Parameters : | evecs : ndarray odf_vertices : None or ndarray
|
---|---|
Returns : | IN : ndarray |
Radial Diffusivity (RD) of a diffusion tensor. Also called perpendicular diffusivity.
Parameters : | evals : array-like
axis : int
|
---|---|
Returns : | rd : array
|
Notes
RD is calculated with the following equation:
RD = \frac{\lambda_2 + \lambda_3}{2}
Use the RESTORE algorithm [Chang2005] to calculate a robust tensor fit
Parameters : | design_matrix : array of shape (g, 7)
data : array of shape ([X, Y, Z, n_directions], g)
min_signal : float, optional
sigma : float
jac : bool, optional
|
---|---|
Returns : | restore_params : an estimate of the tensor parameters in each voxel. |
The sphericity of the tensor [1]
Parameters : | evals : array-like
axis : int
|
---|---|
Returns : | sphericity : array
|
Notes
Trace of a diffusion tensor.
Parameters : | evals : array-like
axis : int
|
---|---|
Returns : | trace : array
|
Notes
Trace is calculated with the following equation:
Trace = \lambda_1 + \lambda_2 + \lambda_3
Computes weighted least squares (WLS) fit to calculate self-diffusion tensor using a linear regression model [R10].
Parameters : | design_matrix : array (g, 7)
data : array ([X, Y, Z, ...], g)
min_signal : default = 1
|
---|---|
Returns : | eigvals : array (..., 3)
eigvecs : array (..., 3, 3)
|
See also
Notes
In Chung, et al. 2006, the regression of the WLS fit needed an unbiased preliminary estimate of the weights and therefore the ordinary least squares (OLS) estimates were used. A “two pass” method was implemented:
- calculate OLS estimates of the data
- apply the OLS estimates as weights to the WLS fit of the data
This ensured heteroscadasticity could be properly modeled for various types of bootstrap resampling (namely residual bootstrap).
y = \mathrm{data} \\ X = \mathrm{design matrix} \\ \hat{\beta}_\mathrm{WLS} = \mathrm{desired regression coefficients (e.g. tensor)}\\ \\ \hat{\beta}_\mathrm{WLS} = (X^T W X)^{-1} X^T W y \\ \\ W = \mathrm{diag}((X \hat{\beta}_\mathrm{OLS})^2), \mathrm{where} \hat{\beta}_\mathrm{OLS} = (X^T X)^{-1} X^T y
References
[R10] | (1, 2) Chung, SW., Lu, Y., Henry, R.G., 2006. Comparison of bootstrap approaches for estimation of uncertainties of DTI parameters. NeuroImage 33, 531-541. |