def test_positive_evals():
# Tested evals
L1 = np.array([[1e-3, 1e-3, 2e-3], [0, 1e-3, 0]])
L2 = np.array([[3e-3, 0, 2e-3], [1e-3, 1e-3, 0]])
L3 = np.array([[4e-3, 1e-4, 0], [0, 1e-3, 0]])
# only the first voxels have all eigenvalues larger than zero, thus:
expected_ind = np.array([[True, False, False], [False, True, False]], dtype=bool)
# test function _positive_evals
ind = _positive_evals(L1, L2, L3)
assert_array_equal(ind, expected_ind)
def test_positive_evals():
# Tested evals
L1 = np.array([[1e-3, 1e-3, 2e-3], [0, 1e-3, 0]])
L2 = np.array([[3e-3, 0, 2e-3], [1e-3, 1e-3, 0]])
L3 = np.array([[4e-3, 1e-4, 0], [0, 1e-3, 0]])
# only the first voxels have all eigenvalues larger than zero, thus:
expected_ind = np.array([[True, False, False], [False, True, False]],
dtype=bool)
# test function _positive_evals
ind = _positive_evals(L1, L2, L3)
assert_array_equal(ind, expected_ind)
def fwdti_prediction(params, gtab, S0=1, Diso=3.0e-3):
r""" Signal prediction given the free water DTI model parameters.
Parameters
----------
params : (..., 13) ndarray
Model parameters. The last dimension should have the 12 tensor
parameters (3 eigenvalues, followed by the 3 corresponding
eigenvectors) and the volume fraction of the free water compartment.
gtab : a GradientTable class instance
The gradient table for this prediction
S0 : float or ndarray
The non diffusion-weighted signal in every voxel, or across all
voxels. Default: 1
Diso : float, optional
Value of the free water isotropic diffusion. Default is set to 3e-3
$mm^{2}.s^{-1}$. Please adjust this value if you are assuming different
units of diffusion.
Returns
--------
S : (..., N) ndarray
Simulated signal based on the free water DTI model
Notes
-----
The predicted signal is given by:
$S(\theta, b) = S_0 * [(1-f) * e^{-b ADC} + f * e^{-b D_{iso}]$, where
$ADC = \theta Q \theta^T$, $\theta$ is a unit vector pointing at any
direction on the sphere for which a signal is to be predicted, $b$ is the b
value provided in the GradientTable input for that direction, $Q$ is the
quadratic form of the tensor determined by the input parameters, $f$ is the
free water diffusion compartment, $D_{iso}$ is the free water diffusivity
which is equal to $3 * 10^{-3} mm^{2}s^{-1} [1]_.
References
----------
.. [1] Hoy, A.R., Koay, C.G., Kecskemeti, S.R., Alexander, A.L., 2014.
Optimization of a free water elimination two-compartmental model
for diffusion tensor imaging. NeuroImage 103, 323-333.
doi: 10.1016/j.neuroimage.2014.09.053
"""
evals = params[..., :3]
evecs = params[..., 3:-1].reshape(params.shape[:-1] + (3, 3))
f = params[..., 12]
qform = vec_val_vect(evecs, evals)
lower_dt = lower_triangular(qform, S0)
lower_diso = lower_dt.copy()
lower_diso[..., 0] = lower_diso[..., 2] = lower_diso[..., 5] = Diso
lower_diso[..., 1] = lower_diso[..., 3] = lower_diso[..., 4] = 0
D = design_matrix(gtab)
pred_sig = np.zeros(f.shape + (gtab.bvals.shape[0], ))
mask = _positive_evals(evals[..., 0], evals[..., 1], evals[..., 2])
index = ndindex(f.shape)
for v in index:
if mask[v]:
pred_sig[v] = (1 - f[v]) * np.exp(np.dot(lower_dt[v], D.T)) + \
f[v] * np.exp(np.dot(lower_diso[v], D.T))
return pred_sig
def dkimicro_prediction(params, gtab, S0=1):
r""" Signal prediction given the DKI microstructure model parameters.
Parameters
----------
params : ndarray (x, y, z, 40) or (n, 40)
All parameters estimated from the diffusion kurtosis microstructure model.
Parameters are ordered as follows:
1) Three diffusion tensor's eigenvalues
2) Three lines of the eigenvector matrix each containing the
first, second and third coordinates of the eigenvector
3) Fifteen elements of the kurtosis tensor
4) Six elements of the hindered diffusion tensor
5) Six elements of the restricted diffusion tensor
6) Axonal water fraction
gtab : a GradientTable class instance
The gradient table for this prediction
S0 : float or ndarray
The non diffusion-weighted signal in every voxel, or across all
voxels. Default: 1
Returns
-------
S : (..., N) ndarray
Simulated signal based on the DKI microstructure model
Notes
-----
1) The predicted signal is given by:
$S(\theta, b) = S_0 * [f * e^{-b ADC_{r}} + (1-f) * e^{-b ADC_{h}]$, where
$ ADC_{r} and ADC_{h} are the apparent diffusion coefficients of the
diffusion hindered and restricted compartment for a given direction
$\theta$, $b$ is the b value provided in the GradientTable input for that
direction, $f$ is the volume fraction of the restricted diffusion
compartment (also known as the axonal water fraction).
2) In the original article of DKI microstructural model [1]_, the hindered
and restricted tensors were definde as the intra-cellular and
extra-cellular diffusion compartments respectively.
"""
# Initialize pred_sig
pred_sig = np.zeros(params.shape[:-1] + (gtab.bvals.shape[0], ))
# Define dti design matrix and region to process
D = dti_design_matrix(gtab)
evals = params[..., :3]
mask = _positive_evals(evals[..., 0], evals[..., 1], evals[..., 2])
# Prepare parameters
f = params[..., 27]
adce = params[..., 28:34]
adci = params[..., 34:40]
if isinstance(S0, np.ndarray):
S0_vol = S0 * np.ones(params.shape[:-1])
else:
S0_vol = S0
# Process pred_sig for all data voxels
index = ndindex(evals.shape[:-1])
for v in index:
if mask[v]:
pred_sig[v] = (1. - f[v]) * np.exp(np.dot(D[:, :6], adce[v])) + \
f[v] * np.exp(np.dot(D[:, :6], adci[v]))
return pred_sig * S0_vol
def fwdti_prediction(params, gtab, S0=1, Diso=3.0e-3):
r""" Signal prediction given the free water DTI model parameters.
Parameters
----------
params : (..., 13) ndarray
Model parameters. The last dimension should have the 12 tensor
parameters (3 eigenvalues, followed by the 3 corresponding
eigenvectors) and the volume fraction of the free water compartment.
gtab : a GradientTable class instance
The gradient table for this prediction
S0 : float or ndarray
The non diffusion-weighted signal in every voxel, or across all
voxels. Default: 1
Diso : float, optional
Value of the free water isotropic diffusion. Default is set to 3e-3
$mm^{2}.s^{-1}$. Please adjust this value if you are assuming different
units of diffusion.
Returns
--------
S : (..., N) ndarray
Simulated signal based on the free water DTI model
Notes
-----
The predicted signal is given by:
$S(\theta, b) = S_0 * [(1-f) * e^{-b ADC} + f * e^{-b D_{iso}]$, where
$ADC = \theta Q \theta^T$, $\theta$ is a unit vector pointing at any
direction on the sphere for which a signal is to be predicted, $b$ is the b
value provided in the GradientTable input for that direction, $Q$ is the
quadratic form of the tensor determined by the input parameters, $f$ is the
free water diffusion compartment, $D_{iso}$ is the free water diffusivity
which is equal to $3 * 10^{-3} mm^{2}s^{-1} [1]_.
References
----------
.. [1] Hoy, A.R., Koay, C.G., Kecskemeti, S.R., Alexander, A.L., 2014.
Optimization of a free water elimination two-compartmental model
for diffusion tensor imaging. NeuroImage 103, 323-333.
doi: 10.1016/j.neuroimage.2014.09.053
"""
evals = params[..., :3]
evecs = params[..., 3:-1].reshape(params.shape[:-1] + (3, 3))
f = params[..., 12]
qform = vec_val_vect(evecs, evals)
lower_dt = lower_triangular(qform, S0)
lower_diso = lower_dt.copy()
lower_diso[..., 0] = lower_diso[..., 2] = lower_diso[..., 5] = Diso
lower_diso[..., 1] = lower_diso[..., 3] = lower_diso[..., 4] = 0
D = design_matrix(gtab)
pred_sig = np.zeros(f.shape + (gtab.bvals.shape[0],))
mask = _positive_evals(evals[..., 0], evals[..., 1], evals[..., 2])
index = ndindex(f.shape)
for v in index:
if mask[v]:
pred_sig[v] = (1 - f[v]) * np.exp(np.dot(lower_dt[v], D.T)) + \
f[v] * np.exp(np.dot(lower_diso[v], D.T))
return pred_sig
def dkimicro_prediction(params, gtab, S0=1):
r""" Signal prediction given the DKI microstructure model parameters.
Parameters
----------
params : ndarray (x, y, z, 40) or (n, 40)
All parameters estimated from the diffusion kurtosis microstructure model.
Parameters are ordered as follows:
1) Three diffusion tensor's eigenvalues
2) Three lines of the eigenvector matrix each containing the
first, second and third coordinates of the eigenvector
3) Fifteen elements of the kurtosis tensor
4) Six elements of the hindered diffusion tensor
5) Six elements of the restricted diffusion tensor
6) Axonal water fraction
gtab : a GradientTable class instance
The gradient table for this prediction
S0 : float or ndarray
The non diffusion-weighted signal in every voxel, or across all
voxels. Default: 1
Returns
--------
S : (..., N) ndarray
Simulated signal based on the DKI microstructure model
Notes
-----
1) The predicted signal is given by:
$S(\theta, b) = S_0 * [f * e^{-b ADC_{r}} + (1-f) * e^{-b ADC_{h}]$, where
$ ADC_{r} and ADC_{h} are the apparent diffusion coefficients of the
diffusion hindered and restricted compartment for a given direction
$\theta$, $b$ is the b value provided in the GradientTable input for that
direction, $f$ is the volume fraction of the restricted diffusion
compartment (also known as the axonal water fraction).
2) In the original article of DKI microstructural model [1]_, the hindered
and restricted tensors were definde as the intra-cellular and
extra-cellular diffusion compartments respectively.
"""
# Initialize pred_sig
pred_sig = np.zeros(params.shape[:-1] + (gtab.bvals.shape[0],))
# Define dti design matrix and region to process
D = dti_design_matrix(gtab)
evals = params[..., :3]
mask = _positive_evals(evals[..., 0], evals[..., 1], evals[..., 2])
# Prepare parameters
f = params[..., 27]
adce = params[..., 28:34]
adci = params[..., 34:40]
if isinstance(S0, np.ndarray):
S0_vol = S0 * np.ones(params.shape[:-1])
else:
S0_vol = S0
# Process pred_sig for all data voxels
index = ndindex(evals.shape[:-1])
for v in index:
if mask[v]:
pred_sig[v] = (1. - f[v]) * np.exp(np.dot(D[:, :6], adce[v])) + \
f[v] * np.exp(np.dot(D[:, :6], adci[v]))
return pred_sig * S0_vol
