def test_from_lower_triangular():
result = np.array([[0, 1, 3], [1, 2, 4], [3, 4, 5]])
D = np.arange(7)
tensor = from_lower_triangular(D)
assert_array_equal(tensor, result)
result = result * np.ones((5, 4, 1, 1))
D = D * np.ones((5, 4, 1))
tensor = from_lower_triangular(D)
assert_array_equal(tensor, result)
def test_from_lower_triangular():
result = np.array([[0, 1, 3],
[1, 2, 4],
[3, 4, 5]])
D = np.arange(7)
tensor = from_lower_triangular(D)
assert_array_equal(tensor, result)
result = result * np.ones((5, 4, 1, 1))
D = D * np.ones((5, 4, 1))
tensor = from_lower_triangular(D)
assert_array_equal(tensor, result)
def test_Wrotate_crossing_fibers():
# Test 2 - simulate crossing fibers intersecting at 70 degrees.
# In this case, diffusion tensor principal eigenvector will be aligned in
# the middle of the crossing fibers. Thus, after rotating the kurtosis
# tensor, this will be equal to a kurtosis tensor simulate of crossing
# fibers both deviating 35 degrees from the x-axis. Moreover, we know that
# crossing fibers will be aligned to the x-y plane, because the smaller
# diffusion eigenvalue, perpendicular to both crossings fibers, will be
# aligned to the z-axis.
# Simulate the crossing fiber
angles = [(90, 30), (90, 30), (20, 30), (20, 30)]
fie = 0.49
frac = [fie*50, (1-fie) * 50, fie*50, (1-fie) * 50]
mevals = np.array([[0.00099, 0, 0], [0.00226, 0.00087, 0.00087],
[0.00099, 0, 0], [0.00226, 0.00087, 0.00087]])
signal, dt, kt = multi_tensor_dki(gtab_2s, mevals, angles=angles,
fractions=frac, snr=None)
evals, evecs = decompose_tensor(from_lower_triangular(dt))
kt_rotated = dki.Wrotate(kt, evecs)
# Now coordinate system has diffusion tensor diagonal aligned to the x-axis
# Simulate the reference kurtosis tensor
angles = [(90, 35), (90, 35), (90, -35), (90, -35)]
signal, dt, kt_ref = multi_tensor_dki(gtab_2s, mevals, angles=angles,
fractions=frac, snr=None)
# Compare rotated with the reference
assert_array_almost_equal(kt_rotated, kt_ref)
def test_Wrotate_single_fiber():
# Rotate the kurtosis tensor of single fiber simulate to the diffusion
# tensor diagonal and check that is equal to the kurtosis tensor of the
# same single fiber simulated directly to the x-axis
# Define single fiber simulate
mevals = np.array([[0.00099, 0, 0], [0.00226, 0.00087, 0.00087]])
fie = 0.49
frac = [fie*100, (1 - fie)*100]
# simulate single fiber not aligned to the x-axis
theta = random.uniform(0, 180)
phi = random.uniform(0, 320)
angles = [(theta, phi), (theta, phi)]
signal, dt, kt = multi_tensor_dki(gtab_2s, mevals, angles=angles,
fractions=frac, snr=None)
evals, evecs = decompose_tensor(from_lower_triangular(dt))
kt_rotated = dki.Wrotate(kt, evecs)
# Now coordinate system has the DT diagonal aligned to the x-axis
# Reference simulation in which DT diagonal is directly aligned to the
# x-axis
angles = (90, 0), (90, 0)
signal, dt_ref, kt_ref = multi_tensor_dki(gtab_2s, mevals, angles=angles,
fractions=frac, snr=None)
assert_array_almost_equal(kt_rotated, kt_ref)
def test_Wrotate_single_fiber():
# Rotate the kurtosis tensor of single fiber simulate to the diffusion
# tensor diagonal and check that is equal to the kurtosis tensor of the
# same single fiber simulated directly to the x-axis
# Define single fiber simulate
mevals = np.array([[0.00099, 0, 0], [0.00226, 0.00087, 0.00087]])
fie = 0.49
frac = [fie*100, (1 - fie)*100]
# simulate single fiber not aligned to the x-axis
theta = random.uniform(0, 180)
phi = random.uniform(0, 320)
angles = [(theta, phi), (theta, phi)]
signal, dt, kt = multi_tensor_dki(gtab_2s, mevals, angles=angles,
fractions=frac, snr=None)
evals, evecs = decompose_tensor(from_lower_triangular(dt))
kt_rotated = dki.Wrotate(kt, evecs)
# Now coordinate system has the DT diagonal aligned to the x-axis
# Reference simulation in which DT diagonal is directly aligned to the
# x-axis
angles = (90, 0), (90, 0)
signal, dt_ref, kt_ref = multi_tensor_dki(gtab_2s, mevals, angles=angles,
fractions=frac, snr=None)
assert_array_almost_equal(kt_rotated, kt_ref)
def test_restore():
"""
Test the implementation of the RESTORE algorithm
"""
b0 = 1000.
bvecs, bval = read_bvec_file(get_data('55dir_grad.bvec'))
gtab = grad.gradient_table(bval, bvecs)
B = bval[1]
#Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
md = evals.mean()
tensor = from_lower_triangular(D)
#Design Matrix
X = dti.design_matrix(gtab)
#Signals
Y = np.exp(np.dot(X,D))
Y.shape = (-1,) + Y.shape
for drop_this in range(1, Y.shape[-1]):
# RESTORE estimates should be robust to dropping
this_y = Y.copy()
this_y[:, drop_this] = 1.0
tensor_model = dti.TensorModel(gtab, fit_method='restore',
sigma=67.0)
tensor_est = tensor_model.fit(this_y)
assert_array_almost_equal(tensor_est.evals[0], evals, decimal=3)
assert_array_almost_equal(tensor_est.quadratic_form[0], tensor,
decimal=3)
def test_Wrotate_crossing_fibers():
# Test 2 - simulate crossing fibers intersecting at 70 degrees.
# In this case, diffusion tensor principal eigenvector will be aligned in
# the middle of the crossing fibers. Thus, after rotating the kurtosis
# tensor, this will be equal to a kurtosis tensor simulate of crossing
# fibers both deviating 35 degrees from the x-axis. Moreover, we know that
# crossing fibers will be aligned to the x-y plane, because the smaller
# diffusion eigenvalue, perpendicular to both crossings fibers, will be
# aligned to the z-axis.
# Simulate the crossing fiber
angles = [(90, 30), (90, 30), (20, 30), (20, 30)]
fie = 0.49
frac = [fie*50, (1-fie) * 50, fie*50, (1-fie) * 50]
mevals = np.array([[0.00099, 0, 0], [0.00226, 0.00087, 0.00087],
[0.00099, 0, 0], [0.00226, 0.00087, 0.00087]])
signal, dt, kt = multi_tensor_dki(gtab_2s, mevals, angles=angles,
fractions=frac, snr=None)
evals, evecs = decompose_tensor(from_lower_triangular(dt))
kt_rotated = dki.Wrotate(kt, evecs)
# Now coordinate system has diffusion tensor diagonal aligned to the x-axis
# Simulate the reference kurtosis tensor
angles = [(90, 35), (90, 35), (90, -35), (90, -35)]
signal, dt, kt_ref = multi_tensor_dki(gtab_2s, mevals, angles=angles,
fractions=frac, snr=None)
# Compare rotated with the reference
assert_array_almost_equal(kt_rotated, kt_ref)
def test_TensorModel():
data, gtab = dsi_voxels()
dm = dti.TensorModel(gtab, 'LS')
dtifit = dm.fit(data[0, 0, 0])
assert_equal(dtifit.fa < 0.5, True)
dm = dti.TensorModel(gtab, 'WLS')
dtifit = dm.fit(data[0, 0, 0])
assert_equal(dtifit.fa < 0.5, True)
sphere = create_unit_sphere(4)
assert_equal(len(dtifit.odf(sphere)), len(sphere.vertices))
assert_almost_equal(dtifit.fa, gfa(dtifit.odf(sphere)), 1)
# Check that the multivoxel case works:
dtifit = dm.fit(data)
assert_equal(dtifit.fa.shape, data.shape[:3])
# Make some synthetic data
b0 = 1000.
bvecs, bvals = read_bvec_file(get_data('55dir_grad.bvec'))
gtab = grad.gradient_table_from_bvals_bvecs(bvals, bvecs.T)
# The first b value is 0., so we take the second one:
B = bvals[1]
#Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
md = evals.mean()
tensor = from_lower_triangular(D)
evecs = np.linalg.eigh(tensor)[1]
#Design Matrix
X = dti.design_matrix(bvecs, bvals)
#Signals
Y = np.exp(np.dot(X,D))
assert_almost_equal(Y[0], b0)
Y.shape = (-1,) + Y.shape
# Test fitting with different methods: #XXX Add NNLS methods!
for fit_method in ['OLS', 'WLS']:
tensor_model = dti.TensorModel(gtab,
fit_method=fit_method)
tensor_fit = tensor_model.fit(Y)
assert_true(tensor_fit.model is tensor_model)
assert_equal(tensor_fit.shape, Y.shape[:-1])
assert_array_almost_equal(tensor_fit.evals[0], evals)
assert_array_almost_equal(tensor_fit.quadratic_form[0], tensor,
err_msg =\
"Calculation of tensor from Y does not compare to analytical solution")
assert_almost_equal(tensor_fit.md[0], md)
assert_equal(tensor_fit.directions.shape[-2], 1)
assert_equal(tensor_fit.directions.shape[-1], 3)
# Test error-handling:
assert_raises(ValueError,
dti.TensorModel,
gtab,
fit_method='crazy_method')
def test_WLS_and_LS_fit():
"""
Tests the WLS and LS fitting functions to see if they returns the correct
eigenvalues and eigenvectors.
Uses data/55dir_grad.bvec as the gradient table and 3by3by56.nii
as the data.
"""
### Defining Test Voxel (avoid nibabel dependency) ###
#Recall: D = [Dxx,Dyy,Dzz,Dxy,Dxz,Dyz,log(S_0)] and D ~ 10^-4 mm^2 /s
b0 = 1000.
bvec, bval = read_bvec_file(get_data('55dir_grad.bvec'))
B = bval[1]
#Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
md = evals.mean()
tensor = from_lower_triangular(D)
#Design Matrix
X = dti.design_matrix(bvec, bval)
#Signals
Y = np.exp(np.dot(X, D))
assert_almost_equal(Y[0], b0)
Y.shape = (-1,) + Y.shape
gtab = grad.gradient_table(bval, bvec)
### Testing WLS Fit on Single Voxel ###
#Estimate tensor from test signals
model = TensorModel(gtab, min_signal=1e-8, fit_method='WLS')
tensor_est = model.fit(Y)
assert_equal(tensor_est.shape, Y.shape[:-1])
assert_array_almost_equal(tensor_est.evals[0], evals)
assert_array_almost_equal(tensor_est.quadratic_form[0], tensor,
err_msg="Calculation of tensor from Y does not "
"compare to analytical solution")
assert_almost_equal(tensor_est.md[0], md)
# Test that we can fit a single voxel's worth of data (a 1d array)
y = Y[0]
tensor_est = model.fit(y)
assert_equal(tensor_est.shape, tuple())
assert_array_almost_equal(tensor_est.evals, evals)
assert_array_almost_equal(tensor_est.quadratic_form, tensor)
assert_almost_equal(tensor_est.md, md)
assert_array_almost_equal(tensor_est.lower_triangular(b0), D)
# Test using fit_method='LS'
model = TensorModel(gtab, min_signal=1e-8, fit_method='LS')
tensor_est = model.fit(y)
assert_equal(tensor_est.shape, tuple())
assert_array_almost_equal(tensor_est.evals, evals)
assert_array_almost_equal(tensor_est.quadratic_form, tensor)
assert_almost_equal(tensor_est.md, md)
assert_array_almost_equal(tensor_est.lower_triangular(b0), D)
def _wls_iter(design_matrix, inv_design, sig, min_diffusivity):
""" Helper function used by wls_fit_dki - Applies WLS fit of the diffusion
kurtosis model to single voxel signals.
Parameters
----------
design_matrix : array (g, 22)
Design matrix holding the covariants used to solve for the regression
coefficients
inv_design : array (g, 22)
Inverse of the design matrix.
sig : array (g, )
Diffusion-weighted signal for a single voxel data.
min_diffusivity : float
Because negative eigenvalues are not physical and small eigenvalues,
much smaller than the diffusion weighting, cause quite a lot of noise
in metrics such as fa, diffusivity values smaller than
`min_diffusivity` are replaced with `min_diffusivity`.
Returns
-------
dki_params : array (27, )
All parameters estimated from the diffusion kurtosis model.
Parameters are ordered as follow:
1) Three diffusion tensor's eingenvalues
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
"""
A = design_matrix
# DKI ordinary linear least square solution
log_s = np.log(sig)
ols_result = np.dot(inv_design, log_s)
# Define weights as diag(yn**2)
W = np.diag(np.exp(2 * np.dot(A, ols_result)))
# DKI weighted linear least square solution
inv_AT_W_A = np.linalg.pinv(np.dot(np.dot(A.T, W), A))
AT_W_LS = np.dot(np.dot(A.T, W), log_s)
wls_result = np.dot(inv_AT_W_A, AT_W_LS)
# Extracting the diffusion tensor parameters from solution
DT_elements = wls_result[:6]
evals, evecs = decompose_tensor(from_lower_triangular(DT_elements),
min_diffusivity=min_diffusivity)
# Extracting kurtosis tensor parameters from solution
MD_square = (evals.mean(0))**2
KT_elements = wls_result[6:21] / MD_square
# Write output
dki_params = np.concatenate((evals, evecs[0], evecs[1], evecs[2],
KT_elements), axis=0)
return dki_params
def _wls_iter(design_matrix, inv_design, sig, min_diffusivity):
""" Helper function used by wls_fit_dki - Applies WLS fit of the diffusion
kurtosis model to single voxel signals.
Parameters
----------
design_matrix : array (g, 22)
Design matrix holding the covariants used to solve for the regression
coefficients
inv_design : array (g, 22)
Inverse of the design matrix.
sig : array (g, )
Diffusion-weighted signal for a single voxel data.
min_diffusivity : float
Because negative eigenvalues are not physical and small eigenvalues,
much smaller than the diffusion weighting, cause quite a lot of noise
in metrics such as fa, diffusivity values smaller than
`min_diffusivity` are replaced with `min_diffusivity`.
Returns
-------
dki_params : array (27, )
All parameters estimated from the diffusion kurtosis model.
Parameters are ordered as follow:
1) Three diffusion tensor's eingenvalues
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
"""
A = design_matrix
# DKI ordinary linear least square solution
log_s = np.log(sig)
ols_result = np.dot(inv_design, log_s)
# Define weights as diag(yn**2)
W = np.diag(np.exp(2 * np.dot(A, ols_result)))
# DKI weighted linear least square solution
inv_AT_W_A = np.linalg.pinv(np.dot(np.dot(A.T, W), A))
AT_W_LS = np.dot(np.dot(A.T, W), log_s)
wls_result = np.dot(inv_AT_W_A, AT_W_LS)
# Extracting the diffusion tensor parameters from solution
DT_elements = wls_result[:6]
evals, evecs = decompose_tensor(from_lower_triangular(DT_elements),
min_diffusivity=min_diffusivity)
# Extracting kurtosis tensor parameters from solution
MD_square = (evals.mean(0))**2
KT_elements = wls_result[6:21] / MD_square
# Write output
dki_params = np.concatenate(
(evals, evecs[0], evecs[1], evecs[2], KT_elements), axis=0)
return dki_params
def setup_module():
"""Module-level setup"""
global gtab, gtab_2s, mevals, model_params_mv
global DWI, FAref, GTF, MDref, FAdti, MDdti
_, fbvals, fbvecs = get_fnames('small_64D')
bvals, bvecs = read_bvals_bvecs(fbvals, fbvecs)
gtab = gradient_table(bvals, bvecs)
# FW model requires multishell data
bvals_2s = np.concatenate((bvals, bvals * 1.5), axis=0)
bvecs_2s = np.concatenate((bvecs, bvecs), axis=0)
gtab_2s = gradient_table(bvals_2s, bvecs_2s)
# Simulation a typical DT and DW signal for no water contamination
S0 = np.array(100)
dt = np.array([0.0017, 0, 0.0003, 0, 0, 0.0003])
evals, evecs = decompose_tensor(from_lower_triangular(dt))
S_tissue = single_tensor(gtab_2s,
S0=100,
evals=evals,
evecs=evecs,
snr=None)
dm = dti.TensorModel(gtab_2s, 'WLS')
dtifit = dm.fit(S_tissue)
FAdti = dtifit.fa
MDdti = dtifit.md
dtiparams = dtifit.model_params
# Simulation of 8 voxels tested
DWI = np.zeros((2, 2, 2, len(gtab_2s.bvals)))
FAref = np.zeros((2, 2, 2))
MDref = np.zeros((2, 2, 2))
# Diffusion of tissue and water compartments are constant for all voxel
mevals = np.array([[0.0017, 0.0003, 0.0003], [0.003, 0.003, 0.003]])
# volume fractions
GTF = np.array([[[0.06, 0.71], [0.33, 0.91]], [[0., 0.], [0., 0.]]])
# S0 multivoxel
S0m = 100 * np.ones((2, 2, 2))
# model_params ground truth (to be fill)
model_params_mv = np.zeros((2, 2, 2, 13))
for i in range(2):
for j in range(2):
gtf = GTF[0, i, j]
S, p = multi_tensor(gtab_2s,
mevals,
S0=100,
angles=[(90, 0), (90, 0)],
fractions=[(1 - gtf) * 100, gtf * 100],
snr=None)
DWI[0, i, j] = S
FAref[0, i, j] = FAdti
MDref[0, i, j] = MDdti
R = all_tensor_evecs(p[0])
R = R.reshape((9))
model_params_mv[0, i, j] = \
np.concatenate(([0.0017, 0.0003, 0.0003], R, [gtf]), axis=0)
def test_WLS_and_LS_fit():
"""
Tests the WLS and LS fitting functions to see if they returns the correct
eigenvalues and eigenvectors.
Uses data/55dir_grad.bvec as the gradient table and 3by3by56.nii
as the data.
"""
### Defining Test Voxel (avoid nibabel dependency) ###
#Recall: D = [Dxx,Dyy,Dzz,Dxy,Dxz,Dyz,log(S_0)] and D ~ 10^-4 mm^2 /s
b0 = 1000.
gtab, bval = read_bvec_file(get_data('55dir_grad.bvec'))
B = bval[1]
#Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
md = evals.mean()
tensor = from_lower_triangular(D)
#Design Matrix
X = dti.design_matrix(gtab, bval)
#Signals
Y = np.exp(np.dot(X, D))
assert_almost_equal(Y[0], b0)
Y.shape = (-1, ) + Y.shape
### Testing WLS Fit on Single Voxel ###
#Estimate tensor from test signals
tensor_est = dti.Tensor(Y, bval, gtab.T, min_signal=1e-8)
assert_equal(tensor_est.shape, Y.shape[:-1])
assert_array_almost_equal(tensor_est.evals[0], evals)
assert_array_almost_equal(
tensor_est.D[0],
tensor,
err_msg=
"Calculation of tensor from Y does not compare to analytical solution")
assert_almost_equal(tensor_est.md()[0], md)
#test 0d tensor
y = Y[0]
tensor_est = dti.Tensor(y, bval, gtab.T, min_signal=1e-8)
assert_equal(tensor_est.shape, tuple())
assert_array_almost_equal(tensor_est.evals, evals)
assert_array_almost_equal(tensor_est.D, tensor)
assert_almost_equal(tensor_est.md(), md)
assert_array_almost_equal(tensor_est.lower_triangular(b0), D)
tensor_est = dti.Tensor(y, bval, gtab.T, min_signal=1e-8, fit_method='LS')
assert_equal(tensor_est.shape, tuple())
assert_array_almost_equal(tensor_est.evals, evals)
assert_array_almost_equal(tensor_est.D, tensor)
assert_almost_equal(tensor_est.md(), md)
assert_array_almost_equal(tensor_est.lower_triangular(b0), D)
def setup_module():
"""Module-level setup"""
global gtab, gtab_2s, mevals, model_params_mv
global DWI, FAref, GTF, MDref, FAdti, MDdti
_, fbvals, fbvecs = get_fnames('small_64D')
bvals, bvecs = read_bvals_bvecs(fbvals, fbvecs)
gtab = gradient_table(bvals, bvecs)
# FW model requires multishell data
bvals_2s = np.concatenate((bvals, bvals * 1.5), axis=0)
bvecs_2s = np.concatenate((bvecs, bvecs), axis=0)
gtab_2s = gradient_table(bvals_2s, bvecs_2s)
# Simulation a typical DT and DW signal for no water contamination
S0 = np.array(100)
dt = np.array([0.0017, 0, 0.0003, 0, 0, 0.0003])
evals, evecs = decompose_tensor(from_lower_triangular(dt))
S_tissue = single_tensor(gtab_2s, S0=100, evals=evals, evecs=evecs,
snr=None)
dm = dti.TensorModel(gtab_2s, 'WLS')
dtifit = dm.fit(S_tissue)
FAdti = dtifit.fa
MDdti = dtifit.md
dtiparams = dtifit.model_params
# Simulation of 8 voxels tested
DWI = np.zeros((2, 2, 2, len(gtab_2s.bvals)))
FAref = np.zeros((2, 2, 2))
MDref = np.zeros((2, 2, 2))
# Diffusion of tissue and water compartments are constant for all voxel
mevals = np.array([[0.0017, 0.0003, 0.0003], [0.003, 0.003, 0.003]])
# volume fractions
GTF = np.array([[[0.06, 0.71], [0.33, 0.91]],
[[0., 0.], [0., 0.]]])
# S0 multivoxel
S0m = 100 * np.ones((2, 2, 2))
# model_params ground truth (to be fill)
model_params_mv = np.zeros((2, 2, 2, 13))
for i in range(2):
for j in range(2):
gtf = GTF[0, i, j]
S, p = multi_tensor(gtab_2s, mevals, S0=100,
angles=[(90, 0), (90, 0)],
fractions=[(1-gtf) * 100, gtf*100], snr=None)
DWI[0, i, j] = S
FAref[0, i, j] = FAdti
MDref[0, i, j] = MDdti
R = all_tensor_evecs(p[0])
R = R.reshape((9))
model_params_mv[0, i, j] = \
np.concatenate(([0.0017, 0.0003, 0.0003], R, [gtf]), axis=0)
def test_restore():
"""
Test the implementation of the RESTORE algorithm
"""
b0 = 1000.
bvecs, bval = read_bvec_file(get_data('55dir_grad.bvec'))
gtab = grad.gradient_table(bval, bvecs)
B = bval[1]
# Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
tensor = from_lower_triangular(D)
# Design Matrix
X = dti.design_matrix(gtab)
# Signals
Y = np.exp(np.dot(X, D))
Y.shape = (-1, ) + Y.shape
for drop_this in range(1, Y.shape[-1]):
for jac in [True, False]:
# RESTORE estimates should be robust to dropping
this_y = Y.copy()
this_y[:, drop_this] = 1.0
for sigma in [67.0, np.ones(this_y.shape[-1]) * 67.0]:
tensor_model = dti.TensorModel(gtab,
fit_method='restore',
jac=jac,
sigma=67.0)
tensor_est = tensor_model.fit(this_y)
assert_array_almost_equal(tensor_est.evals[0],
evals,
decimal=3)
assert_array_almost_equal(tensor_est.quadratic_form[0],
tensor,
decimal=3)
# If sigma is very small, it still needs to work:
tensor_model = dti.TensorModel(gtab, fit_method='restore', sigma=0.0001)
tensor_model.fit(Y.copy())
# Test return_S0_hat
tensor_model = dti.TensorModel(gtab,
fit_method='restore',
sigma=0.0001,
return_S0_hat=True)
tmf = tensor_model.fit(Y.copy())
assert_almost_equal(tmf[0].S0_hat, b0)
def test_single_voxel_DKI_stats():
# tests if AK and RK are equal to expected values for a single fiber
# simulate randomly oriented
ADi = 0.00099
ADe = 0.00226
RDi = 0
RDe = 0.00087
# Reference values
AD = fie * ADi + (1 - fie) * ADe
AK = 3 * fie * (1 - fie) * ((ADi - ADe) / AD)**2
RD = fie * RDi + (1 - fie) * RDe
RK = 3 * fie * (1 - fie) * ((RDi - RDe) / RD)**2
ref_vals = np.array([AD, AK, RD, RK])
# simulate fiber randomly oriented
theta = random.uniform(0, 180)
phi = random.uniform(0, 320)
angles = [(theta, phi), (theta, phi)]
mevals = np.array([[ADi, RDi, RDi], [ADe, RDe, RDe]])
frac = [fie * 100, (1 - fie) * 100]
signal, dt, kt = multi_tensor_dki(gtab_2s,
mevals,
S0=100,
angles=angles,
fractions=frac,
snr=None)
evals, evecs = decompose_tensor(from_lower_triangular(dt))
dki_par = np.concatenate((evals, evecs[0], evecs[1], evecs[2], kt), axis=0)
# Estimates using dki functions
ADe1 = dti.axial_diffusivity(evals)
RDe1 = dti.radial_diffusivity(evals)
AKe1 = axial_kurtosis(dki_par)
RKe1 = radial_kurtosis(dki_par)
e1_vals = np.array([ADe1, AKe1, RDe1, RKe1])
assert_array_almost_equal(e1_vals, ref_vals)
# Estimates using the kurtosis class object
dkiM = dki.DiffusionKurtosisModel(gtab_2s)
dkiF = dkiM.fit(signal)
e2_vals = np.array([dkiF.ad, dkiF.ak(), dkiF.rd, dkiF.rk()])
assert_array_almost_equal(e2_vals, ref_vals)
# test MK (note this test correspond to the MK singularity L2==L3)
MK_as = dkiF.mk()
sph = Sphere(xyz=gtab.bvecs[gtab.bvals > 0])
MK_nm = np.mean(dkiF.akc(sph))
assert_array_almost_equal(MK_as, MK_nm, decimal=1)
def test_nlls_fit_tensor():
"""
Test the implementation of NLLS and RESTORE
"""
b0 = 1000.
bvecs, bval = read_bvec_file(get_data('55dir_grad.bvec'))
gtab = grad.gradient_table(bval, bvecs)
B = bval[1]
#Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
md = evals.mean()
tensor = from_lower_triangular(D)
#Design Matrix
X = dti.design_matrix(bvecs, bval)
#Signals
Y = np.exp(np.dot(X,D))
Y.shape = (-1,) + Y.shape
#Estimate tensor from test signals and compare against expected result
#using non-linear least squares:
tensor_model = dti.TensorModel(gtab, fit_method='NLLS')
tensor_est = tensor_model.fit(Y)
assert_equal(tensor_est.shape, Y.shape[:-1])
assert_array_almost_equal(tensor_est.evals[0], evals)
assert_array_almost_equal(tensor_est.quadratic_form[0], tensor)
assert_almost_equal(tensor_est.md[0], md)
# Using the gmm weighting scheme:
tensor_model = dti.TensorModel(gtab, fit_method='NLLS', weighting='gmm')
assert_equal(tensor_est.shape, Y.shape[:-1])
assert_array_almost_equal(tensor_est.evals[0], evals)
assert_array_almost_equal(tensor_est.quadratic_form[0], tensor)
assert_almost_equal(tensor_est.md[0], md)
# Use NLLS with some actual 4D data:
data, bvals, bvecs = get_data('small_25')
gtab = grad.gradient_table(bvals, bvecs)
tm1 = dti.TensorModel(gtab, fit_method='NLLS')
dd = nib.load(data).get_data()
tf1 = tm1.fit(dd)
tm2 = dti.TensorModel(gtab)
tf2 = tm2.fit(dd)
assert_array_almost_equal(tf1.fa, tf2.fa, decimal=1)
def test_nlls_fit_tensor():
"""
Test the implementation of NLLS and RESTORE
"""
b0 = 1000.
bvecs, bval = read_bvec_file(get_data('55dir_grad.bvec'))
gtab = grad.gradient_table(bval, bvecs)
B = bval[1]
#Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
md = evals.mean()
tensor = from_lower_triangular(D)
#Design Matrix
X = dti.design_matrix(bvecs, bval)
#Signals
Y = np.exp(np.dot(X,D))
Y.shape = (-1,) + Y.shape
#Estimate tensor from test signals and compare against expected result
#using non-linear least squares:
tensor_model = dti.TensorModel(gtab, fit_method='NLLS')
tensor_est = tensor_model.fit(Y)
assert_equal(tensor_est.shape, Y.shape[:-1])
assert_array_almost_equal(tensor_est.evals[0], evals)
assert_array_almost_equal(tensor_est.quadratic_form[0], tensor)
assert_almost_equal(tensor_est.md[0], md)
# Using the gmm weighting scheme:
tensor_model = dti.TensorModel(gtab, fit_method='NLLS', weighting='gmm')
assert_equal(tensor_est.shape, Y.shape[:-1])
assert_array_almost_equal(tensor_est.evals[0], evals)
assert_array_almost_equal(tensor_est.quadratic_form[0], tensor)
assert_almost_equal(tensor_est.md[0], md)
# Use NLLS with some actual 4D data:
data, bvals, bvecs = get_data('small_25')
gtab = grad.gradient_table(bvals, bvecs)
tm1 = dti.TensorModel(gtab, fit_method='NLLS')
dd = nib.load(data).get_data()
tf1 = tm1.fit(dd)
tm2 = dti.TensorModel(gtab)
tf2 = tm2.fit(dd)
assert_array_almost_equal(tf1.fa, tf2.fa, decimal=1)
def test_WLS_and_LS_fit():
"""
Tests the WLS and LS fitting functions to see if they returns the correct
eigenvalues and eigenvectors.
Uses data/55dir_grad.bvec as the gradient table and 3by3by56.nii
as the data.
"""
### Defining Test Voxel (avoid nibabel dependency) ###
#Recall: D = [Dxx,Dyy,Dzz,Dxy,Dxz,Dyz,log(S_0)] and D ~ 10^-4 mm^2 /s
D = np.array([1., 1., 1., 0., 0., 1., np.log(1000) * 10.**4]) * 10.**-4
evals = np.array([2., 1., 0.]) * 10.**-4
md = evals.mean()
tensor = from_lower_triangular(D)
#Design Matrix
gtab, bval = read_bvec_file(get_data('55dir_grad.bvec'))
X = dti.design_matrix(gtab, bval)
#Signals
Y = np.exp(np.dot(X,D))
Y.shape = (-1,) + Y.shape
### Testing WLS Fit on Single Voxel ###
#Estimate tensor from test signals
tensor_est = dti.Tensor(Y,bval,gtab.T,min_signal=1e-8)
assert_equal(tensor_est.shape, Y.shape[:-1])
assert_array_almost_equal(tensor_est.evals[0], evals)
assert_array_almost_equal(tensor_est.D[0], tensor,err_msg= "Calculation of tensor from Y does not compare to analytical solution")
assert_almost_equal(tensor_est.md()[0], md)
#test 0d tensor
y = Y[0]
tensor_est = dti.Tensor(y, bval, gtab.T, min_signal=1e-8)
assert_equal(tensor_est.shape, tuple())
assert_array_almost_equal(tensor_est.evals, evals)
assert_array_almost_equal(tensor_est.D, tensor)
assert_almost_equal(tensor_est.md(), md)
assert_array_almost_equal(tensor_est.lower_triangular(1000), D)
tensor_est = dti.Tensor(y, bval, gtab.T, min_signal=1e-8, fit_method='LS')
assert_equal(tensor_est.shape, tuple())
assert_array_almost_equal(tensor_est.evals, evals)
assert_array_almost_equal(tensor_est.D, tensor)
assert_almost_equal(tensor_est.md(), md)
assert_array_almost_equal(tensor_est.lower_triangular(1000), D)
def _compartments_eigenvalues(cdt):
""" Helper function that computes the eigenvalues of a tissue sub
compartment given its individual diffusion tensor
Parameters
----------
cdt : ndarray (..., 6)
Diffusion tensors elements of the tissue compartment stored in lower
triangular order.
Returns
-------
eval : ndarry (..., 3)
Eigenvalues of the tissue compartment
"""
evals, evecs = decompose_tensor(from_lower_triangular(cdt))
return evals
def _compartments_eigenvalues(cdt):
""" Helper function that computes the eigenvalues of a tissue sub
compartment given its individual diffusion tensor
Parameters
----------
cdt : ndarray (..., 6)
Diffusion tensors elements of the tissue compartment stored in lower
triangular order.
Returns
-------
eval : ndarry (..., 3)
Eigenvalues of the tissue compartment
"""
evals, evecs = decompose_tensor(from_lower_triangular(cdt))
return evals
def test_restore():
"""
Test the implementation of the RESTORE algorithm
"""
b0 = 1000.
bvecs, bval = read_bvec_file(get_data('55dir_grad.bvec'))
gtab = grad.gradient_table(bval, bvecs)
B = bval[1]
# Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
tensor = from_lower_triangular(D)
# Design Matrix
X = dti.design_matrix(gtab)
# Signals
Y = np.exp(np.dot(X, D))
Y.shape = (-1,) + Y.shape
for drop_this in range(1, Y.shape[-1]):
for jac in [True, False]:
# RESTORE estimates should be robust to dropping
this_y = Y.copy()
this_y[:, drop_this] = 1.0
for _ in [67.0, np.ones(this_y.shape[-1]) * 67.0]:
tensor_model = dti.TensorModel(gtab, fit_method='restore',
jac=jac,
sigma=67.0)
tensor_est = tensor_model.fit(this_y)
assert_array_almost_equal(tensor_est.evals[0], evals,
decimal=3)
assert_array_almost_equal(tensor_est.quadratic_form[0], tensor,
decimal=3)
# If sigma is very small, it still needs to work:
tensor_model = dti.TensorModel(gtab, fit_method='restore', sigma=0.0001)
tensor_model.fit(Y.copy())
# Test return_S0_hat
tensor_model = dti.TensorModel(gtab, fit_method='restore', sigma=0.0001,
return_S0_hat=True)
tmf = tensor_model.fit(Y.copy())
assert_almost_equal(tmf[0].S0_hat, b0)
def test_single_voxel_DKI_stats():
# tests if AK and RK are equal to expected values for a single fiber
# simulate randomly oriented
ADi = 0.00099
ADe = 0.00226
RDi = 0
RDe = 0.00087
# Reference values
AD = fie * ADi + (1 - fie) * ADe
AK = 3 * fie * (1 - fie) * ((ADi-ADe) / AD) ** 2
RD = fie * RDi + (1 - fie) * RDe
RK = 3 * fie * (1 - fie) * ((RDi-RDe) / RD) ** 2
ref_vals = np.array([AD, AK, RD, RK])
# simulate fiber randomly oriented
theta = random.uniform(0, 180)
phi = random.uniform(0, 320)
angles = [(theta, phi), (theta, phi)]
mevals = np.array([[ADi, RDi, RDi], [ADe, RDe, RDe]])
frac = [fie * 100, (1 - fie) * 100]
signal, dt, kt = multi_tensor_dki(gtab_2s, mevals, S0=100, angles=angles,
fractions=frac, snr=None)
evals, evecs = decompose_tensor(from_lower_triangular(dt))
dki_par = np.concatenate((evals, evecs[0], evecs[1], evecs[2], kt), axis=0)
# Estimates using dki functions
ADe1 = dti.axial_diffusivity(evals)
RDe1 = dti.radial_diffusivity(evals)
AKe1 = axial_kurtosis(dki_par)
RKe1 = radial_kurtosis(dki_par)
e1_vals = np.array([ADe1, AKe1, RDe1, RKe1])
assert_array_almost_equal(e1_vals, ref_vals)
# Estimates using the kurtosis class object
dkiM = dki.DiffusionKurtosisModel(gtab_2s)
dkiF = dkiM.fit(signal)
e2_vals = np.array([dkiF.ad, dkiF.ak(), dkiF.rd, dkiF.rk()])
assert_array_almost_equal(e2_vals, ref_vals)
# test MK (note this test correspond to the MK singularity L2==L3)
MK_as = dkiF.mk()
sph = Sphere(xyz=gtab.bvecs[gtab.bvals > 0])
MK_nm = np.mean(dkiF.akc(sph))
assert_array_almost_equal(MK_as, MK_nm, decimal=1)
def test_restore():
"""
Test the implementation of the RESTORE algorithm
"""
b0 = 1000.
bvecs, bval = read_bvec_file(get_data('55dir_grad.bvec'))
gtab = grad.gradient_table(bval, bvecs)
B = bval[1]
#Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
md = evals.mean()
tensor = from_lower_triangular(D)
#Design Matrix
X = dti.design_matrix(bvecs, bval)
#Signals
Y = np.exp(np.dot(X,D))
Y.shape = (-1,) + Y.shape
for sigma in [0.1, 1, 10, 100]:
for drop_this in range(1, Y.shape[-1]):
# RESTORE estimates should be robust to dropping
this_y = Y.copy()
this_y[:, drop_this] = 1.0
tensor_model = dti.TensorModel(gtab, fit_method='restore',
sigma=sigma)
tensor_est = tensor_model.fit(Y)
assert_array_almost_equal(tensor_est.evals[0], evals)
assert_array_almost_equal(tensor_est.quadratic_form[0], tensor)
data, bvals, bvecs = get_data('small_25')
dd = nib.load(data).get_data()
gtab = grad.gradient_table(bvals, bvecs)
fit_method = 'restore' # 'NLLS'
jac = True # False
dd[..., 5] = 1.0
tm = dti.TensorModel(gtab, fit_method=fit_method, jac=True, sigma=10)
tm.fit(dd)
def test_restore():
"""
Test the implementation of the RESTORE algorithm
"""
b0 = 1000.
bvecs, bval = read_bvec_file(get_data('55dir_grad.bvec'))
gtab = grad.gradient_table(bval, bvecs)
B = bval[1]
#Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
md = evals.mean()
tensor = from_lower_triangular(D)
#Design Matrix
X = dti.design_matrix(bvecs, bval)
#Signals
Y = np.exp(np.dot(X,D))
Y.shape = (-1,) + Y.shape
for sigma in [0.1, 1, 10, 100]:
for drop_this in range(1, Y.shape[-1]):
# RESTORE estimates should be robust to dropping
this_y = Y.copy()
this_y[:, drop_this] = 1.0
tensor_model = dti.TensorModel(gtab, fit_method='restore',
sigma=sigma)
tensor_est = tensor_model.fit(Y)
assert_array_almost_equal(tensor_est.evals[0], evals)
assert_array_almost_equal(tensor_est.quadratic_form[0], tensor)
data, bvals, bvecs = get_data('small_25')
dd = nib.load(data).get_data()
gtab = grad.gradient_table(bvals, bvecs)
fit_method = 'restore' # 'NLLS'
jac = True # False
dd[..., 5] = 1.0
tm = dti.TensorModel(gtab, fit_method=fit_method, jac=True, sigma=10)
tm.fit(dd)
def test_decompose_tensor_nan():
D_fine = np.array([1.7e-3, 0.0, 0.3e-3, 0.0, 0.0, 0.2e-3])
D_alter = np.array([1.6e-3, 0.0, 0.4e-3, 0.0, 0.0, 0.3e-3])
D_nan = np.nan * np.ones(6)
lref, vref = decompose_tensor(from_lower_triangular(D_fine))
lfine, vfine = _decompose_tensor_nan(from_lower_triangular(D_fine),
from_lower_triangular(D_alter))
assert_array_almost_equal(lfine, np.array([1.7e-3, 0.3e-3, 0.2e-3]))
assert_array_almost_equal(vfine, vref)
lref, vref = decompose_tensor(from_lower_triangular(D_alter))
lalter, valter = _decompose_tensor_nan(from_lower_triangular(D_nan),
from_lower_triangular(D_alter))
assert_array_almost_equal(lalter, np.array([1.6e-3, 0.4e-3, 0.3e-3]))
assert_array_almost_equal(valter, vref)
def test_decompose_tensor_nan():
D_fine = np.array([1.7e-3, 0.0, 0.3e-3, 0.0, 0.0, 0.2e-3])
D_alter = np.array([1.6e-3, 0.0, 0.4e-3, 0.0, 0.0, 0.3e-3])
D_nan = np.nan * np.ones(6)
lref, vref = decompose_tensor(from_lower_triangular(D_fine))
lfine, vfine = _decompose_tensor_nan(from_lower_triangular(D_fine),
from_lower_triangular(D_alter))
assert_array_almost_equal(lfine, np.array([1.7e-3, 0.3e-3, 0.2e-3]))
assert_array_almost_equal(vfine, vref)
lref, vref = decompose_tensor(from_lower_triangular(D_alter))
lalter, valter = _decompose_tensor_nan(from_lower_triangular(D_nan),
from_lower_triangular(D_alter))
assert_array_almost_equal(lalter, np.array([1.6e-3, 0.4e-3, 0.3e-3]))
assert_array_almost_equal(valter, vref)
def calculate_scalars(tensor_data, mask):
'''
Calculate the scalar images from the tensor
returns: FA, MD, TR, AX, RAD
'''
mask = np.asarray(mask, dtype=np.bool)
shape = mask.shape
data = dti.from_lower_triangular(tensor_data[mask])
w, v = dti.decompose_tensor(data)
w = np.squeeze(w)
v = np.squeeze(v)
md = np.zeros(shape)
md[mask] = dti.mean_diffusivity(w, axis=-1)
fa = np.zeros(shape)
fa[mask] = dti.fractional_anisotropy(w, axis=-1)
tr = np.zeros(shape)
tr[mask] = dti.trace(w, axis=-1)
ax = np.zeros(shape)
ax[mask] = dti.axial_diffusivity(w, axis=-1)
rad = np.zeros(shape)
rad[mask] = dti.radial_diffusivity(w, axis=-1)
return fa, md, tr, ax, rad
bvecs_2s = np.concatenate((bvecs, bvecs), axis=0)
gtab_2s = gradient_table(bvals_2s, bvecs_2s)
# Simulation 1. signals of two crossing fibers are simulated
mevals_cross = np.array([[0.00099, 0, 0], [0.00226, 0.00087, 0.00087],
[0.00099, 0, 0], [0.00226, 0.00087, 0.00087]])
angles_cross = [(80, 10), (80, 10), (20, 30), (20, 30)]
fie = 0.49
frac_cross = [fie*50, (1-fie) * 50, fie*50, (1-fie) * 50]
# Noise free simulates
signal_cross, dt_cross, kt_cross = multi_tensor_dki(gtab_2s, mevals_cross,
S0=100,
angles=angles_cross,
fractions=frac_cross,
snr=None)
evals_cross, evecs_cross = decompose_tensor(from_lower_triangular(dt_cross))
crossing_ref = np.concatenate((evals_cross, evecs_cross[0], evecs_cross[1],
evecs_cross[2], kt_cross), axis=0)
# Simulation 2. Spherical kurtosis tensor.- for white matter, this can be a
# biological implaussible scenario, however this simulation is usefull for
# testing the estimation of directional apparent kurtosis and the mean
# kurtosis, since its directional and mean kurtosis ground truth are a constant
# which can be easly mathematicaly calculated.
Di = 0.00099
De = 0.00226
mevals_sph = np.array([[Di, Di, Di], [De, De, De]])
frac_sph = [50, 50]
signal_sph, dt_sph, kt_sph = multi_tensor_dki(gtab_2s, mevals_sph, S0=100,
fractions=frac_sph,
snr=None)
def test_wls_and_ls_fit():
"""
Tests the WLS and LS fitting functions to see if they returns the correct
eigenvalues and eigenvectors.
Uses data/55dir_grad.bvec as the gradient table and 3by3by56.nii
as the data.
"""
# Defining Test Voxel (avoid nibabel dependency) ###
# Recall: D = [Dxx,Dyy,Dzz,Dxy,Dxz,Dyz,log(S_0)] and D ~ 10^-4 mm^2 /s
b0 = 1000.
bvec, bval = read_bvec_file(get_data('55dir_grad.bvec'))
B = bval[1]
# Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
md = evals.mean()
tensor = from_lower_triangular(D)
# Design Matrix
gtab = grad.gradient_table(bval, bvec)
X = dti.design_matrix(gtab)
# Signals
Y = np.exp(np.dot(X, D))
assert_almost_equal(Y[0], b0)
Y.shape = (-1,) + Y.shape
# Testing WLS Fit on Single Voxel
# If you do something wonky (passing min_signal<0), you should get an
# error:
npt.assert_raises(ValueError, TensorModel, gtab, fit_method='WLS',
min_signal=-1)
# Estimate tensor from test signals
model = TensorModel(gtab, fit_method='WLS', return_S0_hat=True)
tensor_est = model.fit(Y)
assert_equal(tensor_est.shape, Y.shape[:-1])
assert_array_almost_equal(tensor_est.evals[0], evals)
assert_array_almost_equal(tensor_est.quadratic_form[0], tensor,
err_msg="Calculation of tensor from Y does not "
"compare to analytical solution")
assert_almost_equal(tensor_est.md[0], md)
assert_array_almost_equal(tensor_est.S0_hat[0], b0, decimal=3)
# Test that we can fit a single voxel's worth of data (a 1d array)
y = Y[0]
tensor_est = model.fit(y)
assert_equal(tensor_est.shape, tuple())
assert_array_almost_equal(tensor_est.evals, evals)
assert_array_almost_equal(tensor_est.quadratic_form, tensor)
assert_almost_equal(tensor_est.md, md)
assert_array_almost_equal(tensor_est.lower_triangular(b0), D)
# Test using fit_method='LS'
model = TensorModel(gtab, fit_method='LS')
tensor_est = model.fit(y)
assert_equal(tensor_est.shape, tuple())
assert_array_almost_equal(tensor_est.evals, evals)
assert_array_almost_equal(tensor_est.quadratic_form, tensor)
assert_almost_equal(tensor_est.md, md)
assert_array_almost_equal(tensor_est.lower_triangular(b0), D)
assert_array_almost_equal(tensor_est.linearity, linearity(evals))
assert_array_almost_equal(tensor_est.planarity, planarity(evals))
assert_array_almost_equal(tensor_est.sphericity, sphericity(evals))
def test_tensor_model():
fdata, fbval, fbvec = get_data('small_25')
data1 = nib.load(fdata).get_data()
gtab1 = grad.gradient_table(fbval, fbvec)
data2, gtab2 = dsi_voxels()
for data, gtab in zip([data1, data2], [gtab1, gtab2]):
dm = dti.TensorModel(gtab, 'LS')
dtifit = dm.fit(data[0, 0, 0])
assert_equal(dtifit.fa < 0.9, True)
dm = dti.TensorModel(gtab, 'WLS')
dtifit = dm.fit(data[0, 0, 0])
assert_equal(dtifit.fa < 0.9, True)
assert_equal(dtifit.fa > 0, True)
sphere = create_unit_sphere(4)
assert_equal(len(dtifit.odf(sphere)), len(sphere.vertices))
# Check that the multivoxel case works:
dtifit = dm.fit(data)
# Check that it works on signal that has already been normalized to S0:
dm_to_relative = dti.TensorModel(gtab)
if np.any(gtab.b0s_mask):
relative_data = (data[0, 0, 0]/np.mean(data[0, 0, 0,
gtab.b0s_mask]))
dtifit_to_relative = dm_to_relative.fit(relative_data)
npt.assert_almost_equal(dtifit.fa[0, 0, 0], dtifit_to_relative.fa,
decimal=3)
# And smoke-test that all these operations return sensibly-shaped arrays:
assert_equal(dtifit.fa.shape, data.shape[:3])
assert_equal(dtifit.ad.shape, data.shape[:3])
assert_equal(dtifit.md.shape, data.shape[:3])
assert_equal(dtifit.rd.shape, data.shape[:3])
assert_equal(dtifit.trace.shape, data.shape[:3])
assert_equal(dtifit.mode.shape, data.shape[:3])
assert_equal(dtifit.linearity.shape, data.shape[:3])
assert_equal(dtifit.planarity.shape, data.shape[:3])
assert_equal(dtifit.sphericity.shape, data.shape[:3])
# Test for the shape of the mask
assert_raises(ValueError, dm.fit, np.ones((10, 10, 3)), np.ones((3, 3)))
# Make some synthetic data
b0 = 1000.
bvecs, bvals = read_bvec_file(get_data('55dir_grad.bvec'))
gtab = grad.gradient_table_from_bvals_bvecs(bvals, bvecs.T)
# The first b value is 0., so we take the second one:
B = bvals[1]
# Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
md = evals.mean()
tensor = from_lower_triangular(D)
A_squiggle = tensor - (1 / 3.0) * np.trace(tensor) * np.eye(3)
mode = (3 * np.sqrt(6) * np.linalg.det(A_squiggle /
np.linalg.norm(A_squiggle)))
evals_eigh, evecs_eigh = np.linalg.eigh(tensor)
# Sort according to eigen-value from large to small:
evecs = evecs_eigh[:, np.argsort(evals_eigh)[::-1]]
# Check that eigenvalues and eigenvectors are properly sorted through
# that previous operation:
for i in range(3):
assert_array_almost_equal(np.dot(tensor, evecs[:, i]),
evals[i] * evecs[:, i])
# Design Matrix
X = dti.design_matrix(gtab)
# Signals
Y = np.exp(np.dot(X, D))
assert_almost_equal(Y[0], b0)
Y.shape = (-1,) + Y.shape
# Test fitting with different methods:
for fit_method in ['OLS', 'WLS', 'NLLS']:
tensor_model = dti.TensorModel(gtab,
fit_method=fit_method,
return_S0_hat=True)
tensor_fit = tensor_model.fit(Y)
assert_true(tensor_fit.model is tensor_model)
assert_equal(tensor_fit.shape, Y.shape[:-1])
assert_array_almost_equal(tensor_fit.evals[0], evals)
assert_array_almost_equal(tensor_fit.S0_hat, b0, decimal=3)
# Test that the eigenvectors are correct, one-by-one:
for i in range(3):
# Eigenvectors have intrinsic sign ambiguity
# (see
# http://prod.sandia.gov/techlib/access-control.cgi/2007/076422.pdf)
# so we need to allow for sign flips. One of the following should
# always be true:
assert_(
np.all(np.abs(tensor_fit.evecs[0][:, i] -
evecs[:, i]) < 10e-6) or
np.all(np.abs(-tensor_fit.evecs[0][:, i] -
evecs[:, i]) < 10e-6))
# We set a fixed tolerance of 10e-6, similar to array_almost_equal
err_msg = "Calculation of tensor from Y does not compare to "
err_msg += "analytical solution"
assert_array_almost_equal(tensor_fit.quadratic_form[0], tensor,
err_msg=err_msg)
assert_almost_equal(tensor_fit.md[0], md)
assert_array_almost_equal(tensor_fit.mode, mode, decimal=5)
assert_equal(tensor_fit.directions.shape[-2], 1)
assert_equal(tensor_fit.directions.shape[-1], 3)
# Test error-handling:
assert_raises(ValueError,
dti.TensorModel,
gtab,
fit_method='crazy_method')
# Test custom fit tensor method
try:
model = dti.TensorModel(gtab, fit_method=lambda *args, **kwargs: 42)
fit = model.fit_method()
except Exception as exc:
assert False, "TensorModel should accept custom fit methods: %s" % exc
assert fit == 42, "Custom fit method for TensorModel returned %s." % fit
# Test multi-voxel data
data = np.zeros((3, Y.shape[1]))
# Normal voxel
data[0] = Y
# High diffusion voxel, all diffusing weighted signal equal to zero
data[1, gtab.b0s_mask] = b0
data[1, ~gtab.b0s_mask] = 0
# Masked voxel, all data set to zero
data[2] = 0.
tensor_model = dti.TensorModel(gtab)
fit = tensor_model.fit(data)
assert_array_almost_equal(fit[0].evals, evals)
# Return S0_test
tensor_model = dti.TensorModel(gtab, return_S0_hat=True)
fit = tensor_model.fit(data)
assert_array_almost_equal(fit[0].evals, evals)
assert_array_almost_equal(fit[0].S0_hat, b0)
# Evals should be high for high diffusion voxel
assert_(all(fit[1].evals > evals[0] * .9))
# Evals should be zero where data is masked
assert_array_almost_equal(fit[2].evals, 0.)
def exp_transform_from_qform(qform):
"""Takes a q form and returns evals and evecs"""
return (dti.decompose_tensor(dti.from_lower_triangular(qform),
min_diffusivity=MIN_POSITIVE_EIGENVALUE))
from dipy.core.gradients import gradient_table
from dipy.data import get_data
fimg, fbvals, fbvecs = get_data('small_64D')
bvals, bvecs = read_bvals_bvecs(fbvals, fbvecs)
gtab = gradient_table(bvals, bvecs)
# FW model requires multishell data
bvals_2s = np.concatenate((bvals, bvals * 1.5), axis=0)
bvecs_2s = np.concatenate((bvecs, bvecs), axis=0)
gtab_2s = gradient_table(bvals_2s, bvecs_2s)
# Simulation a typical DT and DW signal for no water contamination
S0 = np.array(100)
dt = np.array([0.0017, 0, 0.0003, 0, 0, 0.0003])
evals, evecs = decompose_tensor(from_lower_triangular(dt))
S_tissue = single_tensor(gtab_2s, S0=100, evals=evals, evecs=evecs, snr=None)
dm = dti.TensorModel(gtab_2s, 'WLS')
dtifit = dm.fit(S_tissue)
FAdti = dtifit.fa
MDdti = dtifit.md
dtiparams = dtifit.model_params
# Simulation of 8 voxels tested
DWI = np.zeros((2, 2, 2, len(gtab_2s.bvals)))
FAref = np.zeros((2, 2, 2))
MDref = np.zeros((2, 2, 2))
# Diffusion of tissue and water compartments are constant for all voxel
mevals = np.array([[0.0017, 0.0003, 0.0003], [0.003, 0.003, 0.003]])
# volume fractions
GTF = np.array([[[0.06, 0.71], [0.33, 0.91]], [[0., 0.], [0., 0.]]])
def nls_iter(design_matrix, sig, S0, Diso=3e-3, mdreg=2.7e-3,
min_signal=1.0e-6, cholesky=False, f_transform=True,
jac=True):
""" Applies non linear least squares fit of the water free elimination
model to single voxel signals.
Parameters
----------
design_matrix : array (g, 7)
Design matrix holding the covariants used to solve for the regression
coefficients.
sig : array (g, )
Diffusion-weighted signal for a single voxel data.
S0 : float
Non diffusion weighted signal (i.e. signal for b-value=0).
Diso : float, optional
Value of the free water isotropic diffusion. Default is set to 3e-3
$mm^{2}.s^{-1}$. Please ajust this value if you are assuming different
units of diffusion.
min_signal : float
The minimum signal value. Needs to be a strictly positive
number.
cholesky : bool, optional
If true it uses cholesky decomposition to insure that diffusion tensor
is positive define.
Default: False
f_transform : bool, optional
If true, the water volume fractions is converted during the convergence
procedure to ft = arcsin(2*f - 1) + pi/2, insuring f estimates between
0 and 1.
Default: True
jac : bool
Use the Jacobian? Default: False
Returns
-------
All parameters estimated from the free water tensor 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) The volume fraction of the free water compartment.
"""
# Initial guess
params = wls_iter(design_matrix, sig, S0, min_signal=min_signal, Diso=Diso)
# Process voxel if it has significant signal from tissue
if np.mean(sig) > min_signal and S0 > min_signal:
# converting evals and evecs to diffusion tensor elements
evals = params[:3]
evecs = params[3:12].reshape((3, 3))
dt = lower_triangular(vec_val_vect(evecs, evals))
# Cholesky decomposition if requested
if cholesky:
dt = lower_triangular_to_cholesky(dt)
# f transformation if requested
if f_transform:
f = np.arcsin(2*params[12] - 1) + np.pi/2
else:
f = params[12]
# Use the Levenberg-Marquardt algorithm wrapped in opt.leastsq
start_params = np.concatenate((dt, [-np.log(S0), f]), axis=0)
if jac:
this_tensor, status = opt.leastsq(_nls_err_func, start_params[:8],
args=(design_matrix, sig, Diso,
cholesky, f_transform),
Dfun=_nls_jacobian_func)
else:
this_tensor, status = opt.leastsq(_nls_err_func, start_params[:8],
args=(design_matrix, sig, Diso,
cholesky, f_transform))
# Invert the cholesky decomposition if this was requested
if cholesky:
this_tensor[:6] = cholesky_to_lower_triangular(this_tensor[:6])
# Invert f transformation if this was requested
if f_transform:
this_tensor[7] = 0.5 * (1 + np.sin(this_tensor[7] - np.pi/2))
# The parameters are the evals and the evecs:
evals, evecs = decompose_tensor(from_lower_triangular(this_tensor[:6]))
params = np.concatenate((evals, evecs[0], evecs[1], evecs[2],
np.array([this_tensor[7]])), axis=0)
return params
def test_tensor_model():
fdata, fbval, fbvec = get_data('small_25')
data1 = nib.load(fdata).get_data()
gtab1 = grad.gradient_table(fbval, fbvec)
data2, gtab2 = dsi_voxels()
for data, gtab in zip([data1, data2], [gtab1, gtab2]):
dm = dti.TensorModel(gtab, 'LS')
dtifit = dm.fit(data[0, 0, 0])
assert_equal(dtifit.fa < 0.9, True)
dm = dti.TensorModel(gtab, 'WLS')
dtifit = dm.fit(data[0, 0, 0])
assert_equal(dtifit.fa < 0.9, True)
assert_equal(dtifit.fa > 0, True)
sphere = create_unit_sphere(4)
assert_equal(len(dtifit.odf(sphere)), len(sphere.vertices))
# Check that the multivoxel case works:
dtifit = dm.fit(data)
# Check that it works on signal that has already been normalized to S0:
dm_to_relative = dti.TensorModel(gtab)
if np.any(gtab.b0s_mask):
relative_data = (data[0, 0, 0]/np.mean(data[0, 0, 0,
gtab.b0s_mask]))
dtifit_to_relative = dm_to_relative.fit(relative_data)
npt.assert_almost_equal(dtifit.fa[0, 0, 0], dtifit_to_relative.fa,
decimal=3)
# And smoke-test that all these operations return sensibly-shaped arrays:
assert_equal(dtifit.fa.shape, data.shape[:3])
assert_equal(dtifit.ad.shape, data.shape[:3])
assert_equal(dtifit.md.shape, data.shape[:3])
assert_equal(dtifit.rd.shape, data.shape[:3])
assert_equal(dtifit.trace.shape, data.shape[:3])
assert_equal(dtifit.mode.shape, data.shape[:3])
assert_equal(dtifit.linearity.shape, data.shape[:3])
assert_equal(dtifit.planarity.shape, data.shape[:3])
assert_equal(dtifit.sphericity.shape, data.shape[:3])
# Test for the shape of the mask
assert_raises(ValueError, dm.fit, np.ones((10, 10, 3)), np.ones((3, 3)))
# Make some synthetic data
b0 = 1000.
bvecs, bvals = read_bvec_file(get_data('55dir_grad.bvec'))
gtab = grad.gradient_table_from_bvals_bvecs(bvals, bvecs.T)
# The first b value is 0., so we take the second one:
B = bvals[1]
# Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
md = evals.mean()
tensor = from_lower_triangular(D)
A_squiggle = tensor - (1 / 3.0) * np.trace(tensor) * np.eye(3)
mode = (3 * np.sqrt(6) * np.linalg.det(A_squiggle /
np.linalg.norm(A_squiggle)))
evals_eigh, evecs_eigh = np.linalg.eigh(tensor)
# Sort according to eigen-value from large to small:
evecs = evecs_eigh[:, np.argsort(evals_eigh)[::-1]]
# Check that eigenvalues and eigenvectors are properly sorted through
# that previous operation:
for i in range(3):
assert_array_almost_equal(np.dot(tensor, evecs[:, i]),
evals[i] * evecs[:, i])
# Design Matrix
X = dti.design_matrix(gtab)
# Signals
Y = np.exp(np.dot(X, D))
assert_almost_equal(Y[0], b0)
Y.shape = (-1,) + Y.shape
# Test fitting with different methods:
for fit_method in ['OLS', 'WLS', 'NLLS']:
tensor_model = dti.TensorModel(gtab,
fit_method=fit_method,
return_S0_hat=True)
tensor_fit = tensor_model.fit(Y)
assert_true(tensor_fit.model is tensor_model)
assert_equal(tensor_fit.shape, Y.shape[:-1])
assert_array_almost_equal(tensor_fit.evals[0], evals)
assert_array_almost_equal(tensor_fit.S0_hat, b0, decimal=3)
# Test that the eigenvectors are correct, one-by-one:
for i in range(3):
# Eigenvectors have intrinsic sign ambiguity
# (see
# http://prod.sandia.gov/techlib/access-control.cgi/2007/076422.pdf)
# so we need to allow for sign flips. One of the following should
# always be true:
assert_(
np.all(np.abs(tensor_fit.evecs[0][:, i] -
evecs[:, i]) < 10e-6) or
np.all(np.abs(-tensor_fit.evecs[0][:, i] -
evecs[:, i]) < 10e-6))
# We set a fixed tolerance of 10e-6, similar to array_almost_equal
err_msg = "Calculation of tensor from Y does not compare to "
err_msg += "analytical solution"
assert_array_almost_equal(tensor_fit.quadratic_form[0], tensor,
err_msg=err_msg)
assert_almost_equal(tensor_fit.md[0], md)
assert_array_almost_equal(tensor_fit.mode, mode, decimal=5)
assert_equal(tensor_fit.directions.shape[-2], 1)
assert_equal(tensor_fit.directions.shape[-1], 3)
# Test error-handling:
assert_raises(ValueError,
dti.TensorModel,
gtab,
fit_method='crazy_method')
# Test custom fit tensor method
try:
model = dti.TensorModel(gtab, fit_method=lambda *args, **kwargs: 42)
fit = model.fit_method()
except Exception as exc:
assert False, "TensorModel should accept custom fit methods: %s" % exc
assert fit == 42, "Custom fit method for TensorModel returned %s." % fit
# Test multi-voxel data
data = np.zeros((3, Y.shape[1]))
# Normal voxel
data[0] = Y
# High diffusion voxel, all diffusing weighted signal equal to zero
data[1, gtab.b0s_mask] = b0
data[1, ~gtab.b0s_mask] = 0
# Masked voxel, all data set to zero
data[2] = 0.
tensor_model = dti.TensorModel(gtab)
fit = tensor_model.fit(data)
assert_array_almost_equal(fit[0].evals, evals)
# Return S0_test
tensor_model = dti.TensorModel(gtab, return_S0_hat=True)
fit = tensor_model.fit(data)
assert_array_almost_equal(fit[0].evals, evals)
assert_array_almost_equal(fit[0].S0_hat, b0)
# Evals should be high for high diffusion voxel
assert_(all(fit[1].evals > evals[0] * .9))
# Evals should be zero where data is masked
assert_array_almost_equal(fit[2].evals, 0.)
from dipy.core.gradients import gradient_table
from dipy.data import get_data
fimg, fbvals, fbvecs = get_data('small_64D')
bvals, bvecs = read_bvals_bvecs(fbvals, fbvecs)
gtab = gradient_table(bvals, bvecs)
# FW model requires multishell data
bvals_2s = np.concatenate((bvals, bvals * 1.5), axis=0)
bvecs_2s = np.concatenate((bvecs, bvecs), axis=0)
gtab_2s = gradient_table(bvals_2s, bvecs_2s)
# Simulation a typical DT and DW signal for no water contamination
S0 = np.array(100)
dt = np.array([0.0017, 0, 0.0003, 0, 0, 0.0003])
evals, evecs = decompose_tensor(from_lower_triangular(dt))
S_tissue = single_tensor(gtab_2s, S0=100, evals=evals, evecs=evecs,
snr=None)
dm = dti.TensorModel(gtab_2s, 'WLS')
dtifit = dm.fit(S_tissue)
FAdti = dtifit.fa
MDdti = dtifit.md
dtiparams = dtifit.model_params
# Simulation of 8 voxels tested
DWI = np.zeros((2, 2, 2, len(gtab_2s.bvals)))
FAref = np.zeros((2, 2, 2))
MDref = np.zeros((2, 2, 2))
# Diffusion of tissue and water compartments are constant for all voxel
mevals = np.array([[0.0017, 0.0003, 0.0003], [0.003, 0.003, 0.003]])
# volume fractions
def nls_iter(design_matrix, sig, S0, Diso=3e-3, mdreg=2.7e-3,
min_signal=1.0e-6, cholesky=False, f_transform=True,
jac=True):
""" Applies non linear least squares fit of the water free elimination
model to single voxel signals.
Parameters
----------
design_matrix : array (g, 7)
Design matrix holding the covariants used to solve for the regression
coefficients.
sig : array (g, )
Diffusion-weighted signal for a single voxel data.
S0 : float
Non diffusion weighted signal (i.e. signal for b-value=0).
Diso : float, optional
Value of the free water isotropic diffusion. Default is set to 3e-3
$mm^{2}.s^{-1}$. Please ajust this value if you are assuming different
units of diffusion.
mdreg : float, optimal
DTI's mean diffusivity regularization threshold. If standard DTI
diffusion tensor's mean diffusivity is almost near the free water
diffusion value, the diffusion signal is assumed to be only free water
diffusion (i.e. volume fraction will be set to 1 and tissue's diffusion
parameters are set to zero). Default md_reg is 2.7e-3 $mm^{2}.s^{-1}$
(corresponding to 90% of the free water diffusion value).
min_signal : float
The minimum signal value. Needs to be a strictly positive
number.
cholesky : bool, optional
If true it uses cholesky decomposition to insure that diffusion tensor
is positive define.
Default: False
f_transform : bool, optional
If true, the water volume fractions is converted during the convergence
procedure to ft = arcsin(2*f - 1) + pi/2, insuring f estimates between
0 and 1.
Default: True
jac : bool
Use the Jacobian? Default: False
Returns
-------
All parameters estimated from the free water tensor 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) The volume fraction of the free water compartment.
"""
# Initial guess
params = wls_iter(design_matrix, sig, S0,
min_signal=min_signal, Diso=Diso, mdreg=mdreg)
# Process voxel if it has significant signal from tissue
if params[12] < 0.99 and np.mean(sig) > min_signal and S0 > min_signal:
# converting evals and evecs to diffusion tensor elements
evals = params[:3]
evecs = params[3:12].reshape((3, 3))
dt = lower_triangular(vec_val_vect(evecs, evals))
# Cholesky decomposition if requested
if cholesky:
dt = lower_triangular_to_cholesky(dt)
# f transformation if requested
if f_transform:
f = np.arcsin(2*params[12] - 1) + np.pi/2
else:
f = params[12]
# Use the Levenberg-Marquardt algorithm wrapped in opt.leastsq
start_params = np.concatenate((dt, [-np.log(S0), f]), axis=0)
if jac:
this_tensor, status = opt.leastsq(_nls_err_func, start_params[:8],
args=(design_matrix, sig, Diso,
cholesky, f_transform),
Dfun=_nls_jacobian_func)
else:
this_tensor, status = opt.leastsq(_nls_err_func, start_params[:8],
args=(design_matrix, sig, Diso,
cholesky, f_transform))
# Invert the cholesky decomposition if this was requested
if cholesky:
this_tensor[:6] = cholesky_to_lower_triangular(this_tensor[:6])
# Invert f transformation if this was requested
if f_transform:
this_tensor[7] = 0.5 * (1 + np.sin(this_tensor[7] - np.pi/2))
# The parameters are the evals and the evecs:
evals, evecs = decompose_tensor(from_lower_triangular(this_tensor[:6]))
params = np.concatenate((evals, evecs[0], evecs[1], evecs[2],
np.array([this_tensor[7]])), axis=0)
return params
def nls_iter(design_matrix, sig, S0, Diso=3e-3, mdreg=2.7e-3,
min_signal=1.0e-6, cholesky=False, f_transform=True, jac=False,
weighting=None, sigma=None):
""" Applies non linear least squares fit of the water free elimination
model to single voxel signals.
Parameters
----------
design_matrix : array (g, 7)
Design matrix holding the covariants used to solve for the regression
coefficients.
sig : array (g, )
Diffusion-weighted signal for a single voxel data.
S0 : float
Non diffusion weighted signal (i.e. signal for b-value=0).
Diso : float, optional
Value of the free water isotropic diffusion. Default is set to 3e-3
$mm^{2}.s^{-1}$. Please ajust this value if you are assuming different
units of diffusion.
mdreg : float, optimal
DTI's mean diffusivity regularization threshold. If standard DTI
diffusion tensor's mean diffusivity is almost near the free water
diffusion value, the diffusion signal is assumed to be only free water
diffusion (i.e. volume fraction will be set to 1 and tissue's diffusion
parameters are set to zero). Default md_reg is 2.7e-3 $mm^{2}.s^{-1}$
(corresponding to 90% of the free water diffusion value).
min_signal : float
The minimum signal value. Needs to be a strictly positive
number.
cholesky : bool, optional
If true it uses cholesky decomposition to insure that diffusion tensor
is positive define.
Default: False
f_transform : bool, optional
If true, the water volume fractions is converted during the convergence
procedure to ft = arcsin(2*f - 1) + pi/2, insuring f estimates between
0 and 1.
Default: True
jac : bool
Use the Jacobian? Default: False
weighting: str, optional
the weighting scheme to use in considering the
squared-error. Default behavior is to use uniform weighting. Other
options: 'sigma' 'gmm'
sigma: float, optional
If the 'sigma' weighting scheme is used, a value of sigma needs to be
provided here. According to [Chang2005]_, a good value to use is
1.5267 * std(background_noise), where background_noise is estimated
from some part of the image known to contain no signal (only noise).
Returns
-------
All parameters estimated from the free water tensor 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) The volume fraction of the free water compartment.
"""
# Initial guess
params = wls_iter(design_matrix, sig, S0,
min_signal=min_signal, Diso=Diso, mdreg=mdreg)
# Process voxel if it has significant signal from tissue
if params[12] < 0.99 and np.mean(sig) > min_signal and S0 > min_signal:
# converting evals and evecs to diffusion tensor elements
evals = params[:3]
evecs = params[3:12].reshape((3, 3))
dt = lower_triangular(vec_val_vect(evecs, evals))
# Cholesky decomposition if requested
if cholesky:
dt = lower_triangular_to_cholesky(dt)
# f transformation if requested
if f_transform:
f = np.arcsin(2*params[12] - 1) + np.pi/2
else:
f = params[12]
# Use the Levenberg-Marquardt algorithm wrapped in opt.leastsq
start_params = np.concatenate((dt, [-np.log(S0), f]), axis=0)
if jac:
this_tensor, status = opt.leastsq(_nls_err_func, start_params[:8],
args=(design_matrix, sig, Diso,
weighting, sigma, cholesky,
f_transform),
Dfun=_nls_jacobian_func)
else:
this_tensor, status = opt.leastsq(_nls_err_func, start_params[:8],
args=(design_matrix, sig, Diso,
weighting, sigma, cholesky,
f_transform))
# Process tissue diffusion tensor
if cholesky:
this_tensor[:6] = cholesky_to_lower_triangular(this_tensor[:6])
evals, evecs = _decompose_tensor_nan(
from_lower_triangular(this_tensor[:6]),
from_lower_triangular(start_params[:6]))
# Process water volume fraction f
f = this_tensor[7]
if f_transform:
f = 0.5 * (1 + np.sin(f - np.pi/2))
params = np.concatenate((evals, evecs[0], evecs[1], evecs[2],
np.array([f])), axis=0)
return params
def test_nlls_fit_tensor():
"""
Test the implementation of NLLS and RESTORE
"""
b0 = 1000.
bval, bvecs = read_bvals_bvecs(*get_fnames('55dir_grad'))
gtab = grad.gradient_table(bval, bvecs)
B = bval[1]
# Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
md = evals.mean()
tensor = from_lower_triangular(D)
# Design Matrix
X = dti.design_matrix(gtab)
# Signals
Y = np.exp(np.dot(X, D))
Y.shape = (-1, ) + Y.shape
# Estimate tensor from test signals and compare against expected result
# using non-linear least squares:
tensor_model = dti.TensorModel(gtab, fit_method='NLLS')
tensor_est = tensor_model.fit(Y)
npt.assert_equal(tensor_est.shape, Y.shape[:-1])
npt.assert_array_almost_equal(tensor_est.evals[0], evals)
npt.assert_array_almost_equal(tensor_est.quadratic_form[0], tensor)
npt.assert_almost_equal(tensor_est.md[0], md)
# You can also do this without the Jacobian (though it's slower):
tensor_model = dti.TensorModel(gtab, fit_method='NLLS', jac=False)
tensor_est = tensor_model.fit(Y)
npt.assert_equal(tensor_est.shape, Y.shape[:-1])
npt.assert_array_almost_equal(tensor_est.evals[0], evals)
npt.assert_array_almost_equal(tensor_est.quadratic_form[0], tensor)
npt.assert_almost_equal(tensor_est.md[0], md)
# Using the gmm weighting scheme:
tensor_model = dti.TensorModel(gtab, fit_method='NLLS', weighting='gmm')
tensor_est = tensor_model.fit(Y)
npt.assert_equal(tensor_est.shape, Y.shape[:-1])
npt.assert_array_almost_equal(tensor_est.evals[0], evals)
npt.assert_array_almost_equal(tensor_est.quadratic_form[0], tensor)
npt.assert_almost_equal(tensor_est.md[0], md)
# If you use sigma weighting, you'd better provide a sigma:
tensor_model = dti.TensorModel(gtab, fit_method='NLLS', weighting='sigma')
npt.assert_raises(ValueError, tensor_model.fit, Y)
# Use NLLS with some actual 4D data:
data, bvals, bvecs = get_fnames('small_25')
gtab = grad.gradient_table(bvals, bvecs)
tm1 = dti.TensorModel(gtab, fit_method='NLLS')
dd = load_nifti_data(data)
tf1 = tm1.fit(dd)
tm2 = dti.TensorModel(gtab)
tf2 = tm2.fit(dd)
npt.assert_array_almost_equal(tf1.fa, tf2.fa, decimal=1)
def wls_iter(design_matrix, sig, S0, Diso=3e-3, mdreg=2.7e-3,
min_signal=1.0e-6, piterations=3):
""" Applies weighted linear least squares fit of the water free elimination
model to single voxel signals.
Parameters
----------
design_matrix : array (g, 7)
Design matrix holding the covariants used to solve for the regression
coefficients.
sig : array (g, )
Diffusion-weighted signal for a single voxel data.
S0 : float
Non diffusion weighted signal (i.e. signal for b-value=0).
Diso : float, optional
Value of the free water isotropic diffusion. Default is set to 3e-3
$mm^{2}.s^{-1}$. Please ajust this value if you are assuming different
units of diffusion.
mdreg : float, optimal
DTI's mean diffusivity regularization threshold. If standard DTI
diffusion tensor's mean diffusivity is almost near the free water
diffusion value, the diffusion signal is assumed to be only free water
diffusion (i.e. volume fraction will be set to 1 and tissue's diffusion
parameters are set to zero). Default md_reg is 2.7e-3 $mm^{2}.s^{-1}$
(corresponding to 90% of the free water diffusion value).
min_signal : float
The minimum signal value. Needs to be a strictly positive
number. Default: minimal signal in the data provided to `fit`.
piterations : inter, optional
Number of iterations used to refine the precision of f. Default is set
to 3 corresponding to a precision of 0.01.
Returns
-------
All parameters estimated from the free water tensor 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) The volume fraction of the free water compartment
"""
W = design_matrix
# DTI ordinary linear least square solution
log_s = np.log(np.maximum(sig, min_signal))
# Define weights
S2 = np.diag(sig**2)
# DTI weighted linear least square solution
WTS2 = np.dot(W.T, S2)
inv_WT_S2_W = np.linalg.pinv(np.dot(WTS2, W))
invWTS2W_WTS2 = np.dot(inv_WT_S2_W, WTS2)
params = np.dot(invWTS2W_WTS2, log_s)
md = (params[0] + params[2] + params[5]) / 3
# Process voxel if it has significant signal from tissue
if md < mdreg and np.mean(sig) > min_signal and S0 > min_signal:
# General free-water signal contribution
fwsig = np.exp(np.dot(design_matrix,
np.array([Diso, 0, Diso, 0, 0, Diso, 0])))
df = 1 # initialize precision
flow = 0 # lower f evaluated
fhig = 1 # higher f evaluated
ns = 9 # initial number of samples per iteration
for p in range(piterations):
df = df * 0.1
fs = np.linspace(flow+df, fhig-df, num=ns) # sampling f
SFW = np.array([fwsig, ]*ns) # repeat contributions for all values
FS, SI = np.meshgrid(fs, sig)
SA = SI - FS*S0*SFW.T
# SA < 0 means that the signal components from the free water
# component is larger than the total fiber. This cases are present
# for inapropriate large volume fractions (given the current S0
# value estimated). To overcome this issue negative SA are replaced
# by data's min positive signal.
SA[SA <= 0] = min_signal
y = np.log(SA / (1-FS))
all_new_params = np.dot(invWTS2W_WTS2, y)
# Select params for lower F2
SIpred = (1-FS)*np.exp(np.dot(W, all_new_params)) + FS*S0*SFW.T
F2 = np.sum(np.square(SI - SIpred), axis=0)
Mind = np.argmin(F2)
params = all_new_params[:, Mind]
f = fs[Mind] # Updated f
flow = f - df # refining precision
fhig = f + df
ns = 19
evals, evecs = decompose_tensor(from_lower_triangular(params))
fw_params = np.concatenate((evals, evecs[0], evecs[1], evecs[2],
np.array([f])), axis=0)
else:
fw_params = np.zeros(13)
if md > mdreg:
fw_params[12] = 1.0
return fw_params
def test_tensor_model():
fdata, fbval, fbvec = get_data('small_25')
data1 = nib.load(fdata).get_data()
gtab1 = grad.gradient_table(fbval, fbvec)
data2, gtab2 = dsi_voxels()
for data, gtab in zip([data1, data2], [gtab1, gtab2]):
dm = dti.TensorModel(gtab, 'LS')
dtifit = dm.fit(data[0, 0, 0])
assert_equal(dtifit.fa < 0.9, True)
dm = dti.TensorModel(gtab, 'WLS')
dtifit = dm.fit(data[0, 0, 0])
assert_equal(dtifit.fa < 0.9, True)
assert_equal(dtifit.fa > 0, True)
sphere = create_unit_sphere(4)
assert_equal(len(dtifit.odf(sphere)), len(sphere.vertices))
# Check that the multivoxel case works:
dtifit = dm.fit(data)
# Check that it works on signal that has already been normalized to S0:
dm_to_relative = dti.TensorModel(gtab)
if np.any(gtab.b0s_mask):
relative_data = (data[0, 0, 0] /
np.mean(data[0, 0, 0, gtab.b0s_mask]))
dtifit_to_relative = dm_to_relative.fit(relative_data)
npt.assert_almost_equal(dtifit.fa[0, 0, 0],
dtifit_to_relative.fa,
decimal=3)
# And smoke-test that all these operations return sensibly-shaped arrays:
assert_equal(dtifit.fa.shape, data.shape[:3])
assert_equal(dtifit.ad.shape, data.shape[:3])
assert_equal(dtifit.md.shape, data.shape[:3])
assert_equal(dtifit.rd.shape, data.shape[:3])
assert_equal(dtifit.trace.shape, data.shape[:3])
assert_equal(dtifit.mode.shape, data.shape[:3])
assert_equal(dtifit.linearity.shape, data.shape[:3])
assert_equal(dtifit.planarity.shape, data.shape[:3])
assert_equal(dtifit.sphericity.shape, data.shape[:3])
# Test for the shape of the mask
assert_raises(ValueError, dm.fit, np.ones((10, 10, 3)), np.ones((3, 3)))
# Make some synthetic data
b0 = 1000.
bvecs, bvals = read_bvec_file(get_data('55dir_grad.bvec'))
gtab = grad.gradient_table_from_bvals_bvecs(bvals, bvecs.T)
# The first b value is 0., so we take the second one:
B = bvals[1]
# Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
md = evals.mean()
tensor = from_lower_triangular(D)
A_squiggle = tensor - (1 / 3.0) * np.trace(tensor) * np.eye(3)
mode = 3 * np.sqrt(6) * np.linalg.det(
A_squiggle / np.linalg.norm(A_squiggle))
evecs = np.linalg.eigh(tensor)[1]
# Design Matrix
X = dti.design_matrix(gtab)
# Signals
Y = np.exp(np.dot(X, D))
assert_almost_equal(Y[0], b0)
Y.shape = (-1, ) + Y.shape
# Test fitting with different methods:
for fit_method in ['OLS', 'WLS', 'NLLS']:
tensor_model = dti.TensorModel(gtab, fit_method=fit_method)
tensor_fit = tensor_model.fit(Y)
assert_true(tensor_fit.model is tensor_model)
assert_equal(tensor_fit.shape, Y.shape[:-1])
assert_array_almost_equal(tensor_fit.evals[0], evals)
assert_array_almost_equal(tensor_fit.quadratic_form[0], tensor,
err_msg=\
"Calculation of tensor from Y does not compare to analytical solution")
assert_almost_equal(tensor_fit.md[0], md)
assert_array_almost_equal(tensor_fit.mode, mode, decimal=5)
assert_equal(tensor_fit.directions.shape[-2], 1)
assert_equal(tensor_fit.directions.shape[-1], 3)
# Test error-handling:
assert_raises(ValueError, dti.TensorModel, gtab, fit_method='crazy_method')
# Test multi-voxel data
data = np.zeros((3, Y.shape[1]))
# Normal voxel
data[0] = Y
# High diffusion voxel, all diffusing weighted signal equal to zero
data[1, gtab.b0s_mask] = b0
data[1, ~gtab.b0s_mask] = 0
# Masked voxel, all data set to zero
data[2] = 0.
tensor_model = dti.TensorModel(gtab)
fit = tensor_model.fit(data)
assert_array_almost_equal(fit[0].evals, evals)
# Evals should be high for high diffusion voxel
assert_(all(fit[1].evals > evals[0] * .9))
# Evals should be zero where data is masked
assert_array_almost_equal(fit[2].evals, 0.)
def test_TensorModel():
data, gtab = dsi_voxels()
dm = dti.TensorModel(gtab, 'LS')
dtifit = dm.fit(data[0, 0, 0])
assert_equal(dtifit.fa < 0.5, True)
dm = dti.TensorModel(gtab, 'WLS')
dtifit = dm.fit(data[0, 0, 0])
assert_equal(dtifit.fa < 0.5, True)
sphere = create_unit_sphere(4)
assert_equal(len(dtifit.odf(sphere)), len(sphere.vertices))
assert_almost_equal(dtifit.fa, gfa(dtifit.odf(sphere)), 1)
# Check that the multivoxel case works:
dtifit = dm.fit(data)
# And smoke-test that all these operations return sensibly-shaped arrays:
assert_equal(dtifit.fa.shape, data.shape[:3])
assert_equal(dtifit.ad.shape, data.shape[:3])
assert_equal(dtifit.md.shape, data.shape[:3])
assert_equal(dtifit.rd.shape, data.shape[:3])
assert_equal(dtifit.trace.shape, data.shape[:3])
assert_equal(dtifit.mode.shape, data.shape[:3])
assert_equal(dtifit.linearity.shape, data.shape[:3])
assert_equal(dtifit.planarity.shape, data.shape[:3])
assert_equal(dtifit.sphericity.shape, data.shape[:3])
# Test for the shape of the mask
assert_raises(ValueError, dm.fit, np.ones((10, 10, 3)), np.ones((3, 3)))
# Make some synthetic data
b0 = 1000.
bvecs, bvals = read_bvec_file(get_data('55dir_grad.bvec'))
gtab = grad.gradient_table_from_bvals_bvecs(bvals, bvecs.T)
# The first b value is 0., so we take the second one:
B = bvals[1]
# Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
md = evals.mean()
tensor = from_lower_triangular(D)
A_squiggle = tensor - (1 / 3.0) * np.trace(tensor) * np.eye(3)
mode = 3 * np.sqrt(6) * np.linalg.det(
A_squiggle / np.linalg.norm(A_squiggle))
evecs = np.linalg.eigh(tensor)[1]
# Design Matrix
X = dti.design_matrix(gtab)
# Signals
Y = np.exp(np.dot(X, D))
assert_almost_equal(Y[0], b0)
Y.shape = (-1, ) + Y.shape
# Test fitting with different methods:
for fit_method in ['OLS', 'WLS', 'NLLS']:
tensor_model = dti.TensorModel(gtab, fit_method=fit_method)
tensor_fit = tensor_model.fit(Y)
assert_true(tensor_fit.model is tensor_model)
assert_equal(tensor_fit.shape, Y.shape[:-1])
assert_array_almost_equal(tensor_fit.evals[0], evals)
assert_array_almost_equal(tensor_fit.quadratic_form[0], tensor,
err_msg=\
"Calculation of tensor from Y does not compare to analytical solution")
assert_almost_equal(tensor_fit.md[0], md)
assert_array_almost_equal(tensor_fit.mode, mode, decimal=5)
assert_equal(tensor_fit.directions.shape[-2], 1)
assert_equal(tensor_fit.directions.shape[-1], 3)
# Test error-handling:
assert_raises(ValueError, dti.TensorModel, gtab, fit_method='crazy_method')
def test_wls_and_ls_fit():
"""
Tests the WLS and LS fitting functions to see if they returns the correct
eigenvalues and eigenvectors.
Uses data/55dir_grad.bvec as the gradient table and 3by3by56.nii
as the data.
"""
# Defining Test Voxel (avoid nibabel dependency) ###
# Recall: D = [Dxx,Dyy,Dzz,Dxy,Dxz,Dyz,log(S_0)] and D ~ 10^-4 mm^2 /s
b0 = 1000.
bvec, bval = read_bvec_file(get_fnames('55dir_grad.bvec'))
B = bval[1]
# Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
md = evals.mean()
tensor = from_lower_triangular(D)
# Design Matrix
gtab = grad.gradient_table(bval, bvec)
X = dti.design_matrix(gtab)
# Signals
Y = np.exp(np.dot(X, D))
npt.assert_almost_equal(Y[0], b0)
Y.shape = (-1,) + Y.shape
# Testing WLS Fit on Single Voxel
# If you do something wonky (passing min_signal<0), you should get an
# error:
npt.assert_raises(ValueError, TensorModel, gtab, fit_method='WLS',
min_signal=-1)
# Estimate tensor from test signals
model = TensorModel(gtab, fit_method='WLS', return_S0_hat=True)
tensor_est = model.fit(Y)
npt.assert_equal(tensor_est.shape, Y.shape[:-1])
npt.assert_array_almost_equal(tensor_est.evals[0], evals)
npt.assert_array_almost_equal(tensor_est.quadratic_form[0], tensor,
err_msg="Calculation of tensor from Y does "
"not compare to analytical solution")
npt.assert_almost_equal(tensor_est.md[0], md)
npt.assert_array_almost_equal(tensor_est.S0_hat[0], b0, decimal=3)
# Test that we can fit a single voxel's worth of data (a 1d array)
y = Y[0]
tensor_est = model.fit(y)
npt.assert_equal(tensor_est.shape, tuple())
npt.assert_array_almost_equal(tensor_est.evals, evals)
npt.assert_array_almost_equal(tensor_est.quadratic_form, tensor)
npt.assert_almost_equal(tensor_est.md, md)
npt.assert_array_almost_equal(tensor_est.lower_triangular(b0), D)
# Test using fit_method='LS'
model = TensorModel(gtab, fit_method='LS')
tensor_est = model.fit(y)
npt.assert_equal(tensor_est.shape, tuple())
npt.assert_array_almost_equal(tensor_est.evals, evals)
npt.assert_array_almost_equal(tensor_est.quadratic_form, tensor)
npt.assert_almost_equal(tensor_est.md, md)
npt.assert_array_almost_equal(tensor_est.lower_triangular(b0), D)
npt.assert_array_almost_equal(tensor_est.linearity, linearity(evals))
npt.assert_array_almost_equal(tensor_est.planarity, planarity(evals))
npt.assert_array_almost_equal(tensor_est.sphericity, sphericity(evals))
import numpy as np
import nibabel as nib
import dipy.reconst.dti as dti
import dipy.data as dpd
import dipy.core.gradients as grad
b0 = 1000.
bvecs, bval = dpd.read_bvec_file(dpd.get_data('55dir_grad.bvec'))
gtab = grad.gradient_table(bval, bvecs)
B = bval[1]
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
md = evals.mean()
tensor = dti.from_lower_triangular(D)
X = dti.design_matrix(bvecs, bval)
data = np.exp(np.dot(X,D))
data.shape = (-1,) + data.shape
dti_wls = dti.TensorModel(gtab)
fit_wls = dti_wls.fit(data)
fa1 = fit_wls.fa
noisy_data = np.copy(data)
noisy_data[..., -1] = 1.0
fit_wls_noisy = dti_wls.fit(noisy_data)
fa2 = fit_wls_noisy.fa
def wls_iter(design_matrix, sig, S0, Diso=3e-3, mdreg=2.7e-3,
min_signal=1.0e-6, piterations=3):
""" Applies weighted linear least squares fit of the water free elimination
model to single voxel signals.
Parameters
----------
design_matrix : array (g, 7)
Design matrix holding the covariants used to solve for the regression
coefficients.
sig : array (g, )
Diffusion-weighted signal for a single voxel data.
S0 : float
Non diffusion weighted signal (i.e. signal for b-value=0).
Diso : float, optional
Value of the free water isotropic diffusion. Default is set to 3e-3
$mm^{2}.s^{-1}$. Please ajust this value if you are assuming different
units of diffusion.
mdreg : float, optimal
DTI's mean diffusivity regularization threshold. If standard DTI
diffusion tensor's mean diffusivity is almost near the free water
diffusion value, the diffusion signal is assumed to be only free water
diffusion (i.e. volume fraction will be set to 1 and tissue's diffusion
parameters are set to zero). Default md_reg is 2.7e-3 $mm^{2}.s^{-1}$
(corresponding to 90% of the free water diffusion value).
min_signal : float
The minimum signal value. Needs to be a strictly positive
number. Default: minimal signal in the data provided to `fit`.
piterations : inter, optional
Number of iterations used to refine the precision of f. Default is set
to 3 corresponding to a precision of 0.01.
Returns
-------
All parameters estimated from the free water tensor 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) The volume fraction of the free water compartment
"""
W = design_matrix
# DTI ordinary linear least square solution
log_s = np.log(np.maximum(sig, min_signal))
# Define weights
S2 = np.diag(sig**2)
# DTI weighted linear least square solution
WTS2 = np.dot(W.T, S2)
inv_WT_S2_W = np.linalg.pinv(np.dot(WTS2, W))
invWTS2W_WTS2 = np.dot(inv_WT_S2_W, WTS2)
params = np.dot(invWTS2W_WTS2, log_s)
md = (params[0] + params[2] + params[5]) / 3
# Process voxel if it has significant signal from tissue
if md < mdreg and np.mean(sig) > min_signal and S0 > min_signal:
# General free-water signal contribution
fwsig = np.exp(np.dot(design_matrix,
np.array([Diso, 0, Diso, 0, 0, Diso, 0])))
df = 1 # initialize precision
flow = 0 # lower f evaluated
fhig = 1 # higher f evaluated
ns = 9 # initial number of samples per iteration
for p in range(piterations):
df = df * 0.1
fs = np.linspace(flow+df, fhig-df, num=ns) # sampling f
SFW = np.array([fwsig, ]*ns) # repeat contributions for all values
FS, SI = np.meshgrid(fs, sig)
SA = SI - FS*S0*SFW.T
# SA < 0 means that the signal components from the free water
# component is larger than the total fiber. This cases are present
# for inapropriate large volume fractions (given the current S0
# value estimated). To overcome this issue negative SA are replaced
# by data's min positive signal.
SA[SA <= 0] = min_signal
y = np.log(SA / (1-FS))
all_new_params = np.dot(invWTS2W_WTS2, y)
# Select params for lower F2
SIpred = (1-FS)*np.exp(np.dot(W, all_new_params)) + FS*S0*SFW.T
F2 = np.sum(np.square(SI - SIpred), axis=0)
Mind = np.argmin(F2)
params = all_new_params[:, Mind]
f = fs[Mind] # Updated f
flow = f - df # refining precision
fhig = f + df
ns = 19
evals, evecs = decompose_tensor(from_lower_triangular(params))
fw_params = np.concatenate((evals, evecs[0], evecs[1], evecs[2],
np.array([f])), axis=0)
else:
fw_params = np.zeros(13)
if md > mdreg:
fw_params[12] = 1.0
return fw_params
def nls_fit_fwdki(design_matrix, design_matrix_dki, data, S0, params=None, Diso=3e-3,
f_transform=True, mdreg=2.7e-3):
"""
Fit the water elimination DKI model using the non-linear least-squares.
Parameters
----------
design_matrix : array (g, 22)
Design matrix holding the covariants used to solve for the regression
coefficients.
data : ndarray ([X, Y, Z, ...], g)
Data or response variables holding the data. Note that the last
dimension should contain the data. It makes no copies of data.
S0 : ndarray ([X, Y, Z])
A first guess of the non-diffusion signal S0.
params : ndarray ([X, Y, Z, ...], 28), optional
A first model parameters guess (3 eigenvalues, 3 coordinates
of 3 eigenvalues, 15 elements of the kurtosis tensor and the volume
fraction of the free water compartment). If the initial params are
not given, for the diffusion and kurtosis tensor parameters, its
initial guess is obtain from the standard DKI model, while for the
free water fraction its value is estimated using the fwDTI model.
Default: None
Diso : float, optional
Value of the free water isotropic diffusion. Default is set to 3e-3
$mm^{2}.s^{-1}$. Please ajust this value if you are assuming different
units of diffusion.
f_transform : bool, optional
If true, the water volume fractions is converted during the convergence
procedure to ft = arcsin(2*f - 1) + pi/2, insuring f estimates between
0 and 1.
Default: True
mdreg : float, optimal
DTI's mean diffusivity regularization threshold. If standard DTI
diffusion tensor's mean diffusivity is almost near the free water
diffusion value, the diffusion signal is assumed to be only free water
diffusion (i.e. volume fraction will be set to 1 and tissue's diffusion
parameters are set to zero). Default md_reg is 2.7e-3 $mm^{2}.s^{-1}$
(corresponding to 90% of the free water diffusion value).
Returns
-------
fw_params : ndarray (x, y, z, 28)
Matrix containing in the dimention the free water model parameters in
the following order:
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) The volume fraction of the free water compartment
S0 : ndarray (x, y, z)
The models estimate of the non diffusion-weighted signal S0.
"""
# preparing data and initializing parameters
data = np.asarray(data)
data_flat = np.reshape(data, (-1, data.shape[-1]))
S0out = S0.copy()
S0out = S0out.ravel()
# Computing WLS DTI solution for MD regularization
dtiparams = dti.wls_fit_tensor(design_matrix, data_flat)
md = dti.mean_diffusivity(dtiparams[..., :3])
cond = md > mdreg # removal condition
data_cond = data_flat[~cond, :]
# Initializing fw_params according to selected initial guess
if np.any(params) is None:
params_out = np.zeros((len(data_flat), 28))
dkiparams = dki.wls_fit_dki(design_matrix_dki, data_flat)
fweparams, sd = fwdti.wls_fit_tensor(design_matrix, data_flat,
S0=S0, Diso=Diso,
mdreg=2.7e-3)
params_out[:, 0:27] = dkiparams
params_out[:, 27] = fweparams[:, 12]
else:
params_out = params.copy()
params_out = np.reshape(params_out, (-1, params_out.shape[-1]))
params_cond = params_out[~cond, :]
S0_cond = S0out[~cond]
for vox in range(data_cond.shape[0]):
if np.all(data_cond[vox] == 0):
raise ValueError("The data in this voxel contains only zeros")
params = params_cond[vox]
# converting evals and evecs to diffusion tensor elements
evals = params[:3]
evecs = params[3:12].reshape((3, 3))
dt = lower_triangular(vec_val_vect(evecs, evals))
kt = params[..., 12:27]
s0 = S0_cond[vox]
MD = evals.mean()
# f transformation if requested
if f_transform:
f = np.arcsin(2*params[27] - 1) + np.pi/2
else:
f = params[27]
# Use the Levenberg-Marquardt algorithm wrapped in opt.leastsq
start_params = np.concatenate((dt, kt*MD*MD, [np.log(s0), f]), axis=0)
this_tensor, status = opt.leastsq(_nls_err_func, start_params,
args=(design_matrix_dki,
data_cond[vox],
Diso, f_transform))
# Invert f transformation if this was requested
if f_transform:
this_tensor[22] = 0.5 * (1 + np.sin(this_tensor[22] - np.pi/2))
# The parameters are the evals and the evecs:
evals, evecs = decompose_tensor(from_lower_triangular(this_tensor[:6]))
MD = evals.mean()
params_cond[vox, :3] = evals
params_cond[vox, 3:12] = evecs.ravel()
params_cond[vox, 12:27] = this_tensor[6:21] / (MD ** 2)
params_cond[vox, 27] = this_tensor[22]
S0_cond[vox] = np.exp(-this_tensor[21])
params_out[~cond, :] = params_cond
params_out[cond, 27] = 1 # Only free water
params_out = np.reshape(params_out, (data.shape[:-1]) + (28,))
S0out[~cond] = S0_cond
S0out[cond] = \
np.mean(data_flat[cond, :] / \
np.exp(np.dot(design_matrix[..., :6],
np.array([Diso, 0, Diso, 0, 0, Diso]))),
-1) # Only free water
S0out = S0out.reshape(data.shape[:-1])
return params_out, S0out
def nls_iter_bounds(design_matrix, sig, S0, Diso=3e-3, mdreg=2.7e-3,
min_signal=1.0e-6, bounds=None, jac=True):
""" Applies non-linear least-squares fit with constraints of the water free
elimination model to single voxel signals.
Parameters
----------
design_matrix : array (g, 7)
Design matrix holding the covariants used to solve for the regression
coefficients.
sig : array (g, )
Diffusion-weighted signal for a single voxel data.
S0 : float
Non diffusion weighted signal (i.e. signal for b-value=0).
Diso : float, optional
Value of the free water isotropic diffusion. Default is set to 3e-3
$mm^{2}.s^{-1}$. Please ajust this value if you are assuming different
units of diffusion.
mdreg : float, optimal
DTI's mean diffusivity regularization threshold. If standard DTI
diffusion tensor's mean diffusivity is almost near the free water
diffusion value, the diffusion signal is assumed to be only free water
diffusion (i.e. volume fraction will be set to 1 and tissue's diffusion
parameters are set to zero). Default md_reg is 2.7e-3 $mm^{2}.s^{-1}$
(corresponding to 90% of the free water diffusion value).
min_signal : float
The minimum signal value. Needs to be a strictly positive
number.
bounds : 2-tuple of arrays with 14 elements, optional
Lower and upper bounds on fwdti model variables and the log of
non-diffusion signal S0. Use np.inf with an appropriate sign to
disable bounds on all or some variables. When bounds is set to None
the following default variable bounds is used:
([0., -Diso, 0., -Diso, -Diso, 0., 0., np.exp(-10.)],
[Diso, Diso, Diso, Diso, Diso, Diso, 1., np.exp(10.)])
jac : bool
Use the Jacobian? Default: False
Returns
-------
All parameters estimated from the free water tensor 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) The volume fraction of the free water compartment.
"""
# Initial guess
params = wls_iter(design_matrix, sig, S0,
min_signal=min_signal, Diso=Diso, mdreg=mdreg)
# Set bounds
if bounds is None:
bounds = ([0., -Diso, 0., -Diso, -Diso, 0., -10., 0],
[Diso, Diso, Diso, Diso, Diso, Diso, 10., 1])
else:
# In the helper subfunctions it was easier to have log(S0) first than
# the water volume. Therefore, we have to reorder the boundaries if
# specified by the user
S0low = np.log(bounds[0][7])
S0hig = np.log(bounds[1][7])
bounds[0][7] = bounds[0][6]
bounds[1][7] = bounds[1][6]
bounds[0][6] = S0low
bounds[1][6] = S0hig
# Process voxel if it has significant signal from tissue
if params[12] < 0.99 and np.mean(sig) > min_signal:
# converting evals and evecs to diffusion tensor elements
evals = params[:3]
evecs = params[3:12].reshape((3, 3))
dt = lower_triangular(vec_val_vect(evecs, evals))
f = params[12]
# Use the Levenberg-Marquardt algorithm wrapped in opt.leastsq
start_params = np.concatenate((dt, [-np.log(S0), f]), axis=0)
lb = np.array(bounds[0])
ub = np.array(bounds[1])
start_params[start_params < lb] = lb[start_params < lb]
start_params[start_params > ub] = ub[start_params > ub]
if jac:
out = opt.least_squares(_nls_err_func, start_params[:8],
args=(design_matrix, sig,
Diso, False, False),
jac=_nls_jacobian_func,
bounds=bounds)
else:
out = opt.least_squares(_nls_err_func, start_params[:8],
args=(design_matrix, sig,
Diso, False, False),
bounds=bounds)
this_tensor = out.x
# The parameters are the evals and the evecs:
evals, evecs = decompose_tensor(from_lower_triangular(this_tensor[:6]))
params = np.concatenate((evals, evecs[0], evecs[1], evecs[2],
np.array([this_tensor[7]])), axis=0)
return params
def nls_iter_bounds(design_matrix, sig, S0, Diso=3e-3,
min_signal=1.0e-6, bounds=None, jac=True):
""" Applies non-linear least-squares fit with constraints of the water free
elimination model to single voxel signals.
Parameters
----------
design_matrix : array (g, 7)
Design matrix holding the covariants used to solve for the regression
coefficients.
sig : array (g, )
Diffusion-weighted signal for a single voxel data.
S0 : float
Non diffusion weighted signal (i.e. signal for b-value=0).
Diso : float, optional
Value of the free water isotropic diffusion. Default is set to 3e-3
$mm^{2}.s^{-1}$. Please ajust this value if you are assuming different
units of diffusion.
min_signal : float
The minimum signal value. Needs to be a strictly positive
number.
bounds : 2-tuple of arrays with 14 elements, optional
Lower and upper bounds on fwdti model variables and the log of
non-diffusion signal S0. Use np.inf with an appropriate sign to
disable bounds on all or some variables. When bounds is set to None
the following default variable bounds is used:
([0., -Diso, 0., -Diso, -Diso, 0., 0., np.exp(-10.)],
[Diso, Diso, Diso, Diso, Diso, Diso, 1., np.exp(10.)])
jac : bool
Use the Jacobian? Default: False
Returns
-------
All parameters estimated from the free water tensor 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) The volume fraction of the free water compartment.
References
----------
.. [1] Henriques, R.N., Rokem, A., Garyfallidis, E., St-Jean, S., Peterson,
E.T., Correia, M.M., 2017. Re: Optimization of a free water
elimination two-compartmental model for diffusion tensor imaging.
ReScience
"""
# Initial guess
params = wls_iter(design_matrix, sig, S0,
min_signal=min_signal, Diso=Diso)
# Set bounds
if bounds is None:
bounds = ([0., -Diso, 0., -Diso, -Diso, 0., -10., 0],
[Diso, Diso, Diso, Diso, Diso, Diso, 10., 1])
else:
# In the helper subfunctions it was easier to have log(S0) first than
# the water volume. Therefore, we have to reorder the boundaries if
# specified by the user
S0low = np.log(bounds[0][7])
S0hig = np.log(bounds[1][7])
bounds[0][7] = bounds[0][6]
bounds[1][7] = bounds[1][6]
bounds[0][6] = S0low
bounds[1][6] = S0hig
# Process voxel if it has significant signal from tissue
if np.mean(sig) > min_signal and S0 > min_signal:
# converting evals and evecs to diffusion tensor elements
evals = params[:3]
evecs = params[3:12].reshape((3, 3))
dt = lower_triangular(vec_val_vect(evecs, evals))
f = params[12]
# Use the Levenberg-Marquardt algorithm wrapped in opt.leastsq
start_params = np.concatenate((dt, [-np.log(S0), f]), axis=0)
lb = np.array(bounds[0])
ub = np.array(bounds[1])
start_params[start_params < lb] = lb[start_params < lb]
start_params[start_params > ub] = ub[start_params > ub]
if jac:
out = opt.least_squares(_nls_err_func, start_params[:8],
args=(design_matrix, sig,
Diso, False, False),
jac=_nls_jacobian_func,
bounds=bounds)
else:
out = opt.least_squares(_nls_err_func, start_params[:8],
args=(design_matrix, sig,
Diso, False, False),
bounds=bounds)
this_tensor = out.x
# The parameters are the evals and the evecs:
evals, evecs = decompose_tensor(from_lower_triangular(this_tensor[:6]))
params = np.concatenate((evals, evecs[0], evecs[1], evecs[2],
np.array([this_tensor[7]])), axis=0)
return params
def test_tensor_model():
fdata, fbval, fbvec = get_data('small_25')
data = nib.load(fdata).get_data()
gtab = grad.gradient_table(fbval, fbvec)
dm = dti.TensorModel(gtab, 'LS')
dtifit = dm.fit(data[0, 0, 0])
assert_equal(dtifit.fa < 0.9, True)
dm = dti.TensorModel(gtab, 'WLS')
dtifit = dm.fit(data[0, 0, 0])
assert_equal(dtifit.fa < 0.9, True)
assert_equal(dtifit.fa > 0, True)
sphere = create_unit_sphere(4)
assert_equal(len(dtifit.odf(sphere)), len(sphere.vertices))
# Check that the multivoxel case works:
dtifit = dm.fit(data)
# Check that it works on signal that has already been normalized to S0:
dm_to_relative = dti.TensorModel(gtab)
relative_data = (data[0, 0, 0]/np.mean(data[0, 0, 0, gtab.b0s_mask]))
dtifit_to_relative = dm_to_relative.fit(relative_data)
npt.assert_almost_equal(dtifit.fa[0,0,0], dtifit_to_relative.fa, decimal=3)
# And smoke-test that all these operations return sensibly-shaped arrays:
assert_equal(dtifit.fa.shape, data.shape[:3])
assert_equal(dtifit.ad.shape, data.shape[:3])
assert_equal(dtifit.md.shape, data.shape[:3])
assert_equal(dtifit.rd.shape, data.shape[:3])
assert_equal(dtifit.trace.shape, data.shape[:3])
assert_equal(dtifit.mode.shape, data.shape[:3])
assert_equal(dtifit.linearity.shape, data.shape[:3])
assert_equal(dtifit.planarity.shape, data.shape[:3])
assert_equal(dtifit.sphericity.shape, data.shape[:3])
# Test for the shape of the mask
assert_raises(ValueError, dm.fit, np.ones((10, 10, 3)), np.ones((3,3)))
# Make some synthetic data
b0 = 1000.
bvecs, bvals = read_bvec_file(get_data('55dir_grad.bvec'))
gtab = grad.gradient_table_from_bvals_bvecs(bvals, bvecs.T)
# The first b value is 0., so we take the second one:
B = bvals[1]
# Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
md = evals.mean()
tensor = from_lower_triangular(D)
A_squiggle = tensor - (1 / 3.0) * np.trace(tensor) * np.eye(3)
mode = 3 * np.sqrt(6) * np.linalg.det(A_squiggle / np.linalg.norm(A_squiggle))
evecs = np.linalg.eigh(tensor)[1]
# Design Matrix
X = dti.design_matrix(gtab)
# Signals
Y = np.exp(np.dot(X, D))
assert_almost_equal(Y[0], b0)
Y.shape = (-1,) + Y.shape
# Test fitting with different methods:
for fit_method in ['OLS', 'WLS', 'NLLS']:
tensor_model = dti.TensorModel(gtab,
fit_method=fit_method)
tensor_fit = tensor_model.fit(Y)
assert_true(tensor_fit.model is tensor_model)
assert_equal(tensor_fit.shape, Y.shape[:-1])
assert_array_almost_equal(tensor_fit.evals[0], evals)
assert_array_almost_equal(tensor_fit.quadratic_form[0], tensor,
err_msg=\
"Calculation of tensor from Y does not compare to analytical solution")
assert_almost_equal(tensor_fit.md[0], md)
assert_array_almost_equal(tensor_fit.mode, mode, decimal=5)
assert_equal(tensor_fit.directions.shape[-2], 1)
assert_equal(tensor_fit.directions.shape[-1], 3)
# Test error-handling:
assert_raises(ValueError,
dti.TensorModel,
gtab,
fit_method='crazy_method')
# Test multi-voxel data
data = np.zeros((3, Y.shape[1]))
# Normal voxel
data[0] = Y
# High diffusion voxel, all diffusing weighted signal equal to zero
data[1, gtab.b0s_mask] = b0
data[1, ~gtab.b0s_mask] = 0
# Masked voxel, all data set to zero
data[2] = 0.
tensor_model = dti.TensorModel(gtab)
fit = tensor_model.fit(data)
assert_array_almost_equal(fit[0].evals, evals)
# Evals should be high for high diffusion voxel
assert_(all(fit[1].evals > evals[0] * .9))
# Evals should be zero where data is masked
assert_array_almost_equal(fit[2].evals, 0.)
def test_TensorModel():
data, gtab = dsi_voxels()
dm = dti.TensorModel(gtab, 'LS')
dtifit = dm.fit(data[0, 0, 0])
assert_equal(dtifit.fa < 0.5, True)
dm = dti.TensorModel(gtab, 'WLS')
dtifit = dm.fit(data[0, 0, 0])
assert_equal(dtifit.fa < 0.5, True)
sphere = create_unit_sphere(4)
assert_equal(len(dtifit.odf(sphere)), len(sphere.vertices))
assert_almost_equal(dtifit.fa, gfa(dtifit.odf(sphere)), 1)
# Check that the multivoxel case works:
dtifit = dm.fit(data)
# And smoke-test that all these operations return sensibly-shaped arrays:
assert_equal(dtifit.fa.shape, data.shape[:3])
assert_equal(dtifit.ad.shape, data.shape[:3])
assert_equal(dtifit.md.shape, data.shape[:3])
assert_equal(dtifit.rd.shape, data.shape[:3])
assert_equal(dtifit.trace.shape, data.shape[:3])
assert_equal(dtifit.mode.shape, data.shape[:3])
assert_equal(dtifit.linearity.shape, data.shape[:3])
assert_equal(dtifit.planarity.shape, data.shape[:3])
assert_equal(dtifit.sphericity.shape, data.shape[:3])
# Test for the shape of the mask
assert_raises(ValueError, dm.fit, np.ones((10, 10, 3)), np.ones((3,3)))
# Make some synthetic data
b0 = 1000.
bvecs, bvals = read_bvec_file(get_data('55dir_grad.bvec'))
gtab = grad.gradient_table_from_bvals_bvecs(bvals, bvecs.T)
# The first b value is 0., so we take the second one:
B = bvals[1]
# Scale the eigenvalues and tensor by the B value so the units match
D = np.array([1., 1., 1., 0., 0., 1., -np.log(b0) * B]) / B
evals = np.array([2., 1., 0.]) / B
md = evals.mean()
tensor = from_lower_triangular(D)
A_squiggle = tensor - (1 / 3.0) * np.trace(tensor) * np.eye(3)
mode = 3 * np.sqrt(6) * np.linalg.det(A_squiggle / np.linalg.norm(A_squiggle))
evecs = np.linalg.eigh(tensor)[1]
# Design Matrix
X = dti.design_matrix(gtab)
# Signals
Y = np.exp(np.dot(X, D))
assert_almost_equal(Y[0], b0)
Y.shape = (-1,) + Y.shape
# Test fitting with different methods:
for fit_method in ['OLS', 'WLS', 'NLLS']:
tensor_model = dti.TensorModel(gtab,
fit_method=fit_method)
tensor_fit = tensor_model.fit(Y)
assert_true(tensor_fit.model is tensor_model)
assert_equal(tensor_fit.shape, Y.shape[:-1])
assert_array_almost_equal(tensor_fit.evals[0], evals)
assert_array_almost_equal(tensor_fit.quadratic_form[0], tensor,
err_msg=\
"Calculation of tensor from Y does not compare to analytical solution")
assert_almost_equal(tensor_fit.md[0], md)
assert_array_almost_equal(tensor_fit.mode, mode, decimal=5)
assert_equal(tensor_fit.directions.shape[-2], 1)
assert_equal(tensor_fit.directions.shape[-1], 3)
# Test error-handling:
assert_raises(ValueError,
dti.TensorModel,
gtab,
fit_method='crazy_method')
bvecs_2s = np.concatenate((bvecs, bvecs), axis=0)
gtab_2s = gradient_table(bvals_2s, bvecs_2s)
# Simulation 1. signals of two crossing fibers are simulated
mevals_cross = np.array([[0.00099, 0, 0], [0.00226, 0.00087, 0.00087],
[0.00099, 0, 0], [0.00226, 0.00087, 0.00087]])
angles_cross = [(80, 10), (80, 10), (20, 30), (20, 30)]
fie = 0.49
frac_cross = [fie*50, (1-fie) * 50, fie*50, (1-fie) * 50]
# Noise free simulates
signal_cross, dt_cross, kt_cross = multi_tensor_dki(gtab_2s, mevals_cross,
S0=100,
angles=angles_cross,
fractions=frac_cross,
snr=None)
evals_cross, evecs_cross = decompose_tensor(from_lower_triangular(dt_cross))
crossing_ref = np.concatenate((evals_cross, evecs_cross[0], evecs_cross[1],
evecs_cross[2], kt_cross), axis=0)
# Simulation 2. Spherical kurtosis tensor.- for white matter, this can be a
# biological implaussible scenario, however this simulation is usefull for
# testing the estimation of directional apparent kurtosis and the mean
# kurtosis, since its directional and mean kurtosis ground truth are a constant
# which can be easly mathematicaly calculated.
Di = 0.00099
De = 0.00226
mevals_sph = np.array([[Di, Di, Di], [De, De, De]])
frac_sph = [50, 50]
signal_sph, dt_sph, kt_sph = multi_tensor_dki(gtab_2s, mevals_sph, S0=100,
fractions=frac_sph,
snr=None)
def nls_fit_fwdki(design_matrix,
design_matrix_dki,
data,
S0,
params=None,
Diso=3e-3,
f_transform=True,
mdreg=2.7e-3):
"""
Fit the water elimination DKI model using the non-linear least-squares.
Parameters
----------
design_matrix : array (g, 22)
Design matrix holding the covariants used to solve for the regression
coefficients.
data : ndarray ([X, Y, Z, ...], g)
Data or response variables holding the data. Note that the last
dimension should contain the data. It makes no copies of data.
S0 : ndarray ([X, Y, Z])
A first guess of the non-diffusion signal S0.
params : ndarray ([X, Y, Z, ...], 28), optional
A first model parameters guess (3 eigenvalues, 3 coordinates
of 3 eigenvalues, 15 elements of the kurtosis tensor and the volume
fraction of the free water compartment). If the initial params are
not given, for the diffusion and kurtosis tensor parameters, its
initial guess is obtain from the standard DKI model, while for the
free water fraction its value is estimated using the fwDTI model.
Default: None
Diso : float, optional
Value of the free water isotropic diffusion. Default is set to 3e-3
$mm^{2}.s^{-1}$. Please ajust this value if you are assuming different
units of diffusion.
f_transform : bool, optional
If true, the water volume fractions is converted during the convergence
procedure to ft = arcsin(2*f - 1) + pi/2, insuring f estimates between
0 and 1.
Default: True
mdreg : float, optimal
DTI's mean diffusivity regularization threshold. If standard DTI
diffusion tensor's mean diffusivity is almost near the free water
diffusion value, the diffusion signal is assumed to be only free water
diffusion (i.e. volume fraction will be set to 1 and tissue's diffusion
parameters are set to zero). Default md_reg is 2.7e-3 $mm^{2}.s^{-1}$
(corresponding to 90% of the free water diffusion value).
Returns
-------
fw_params : ndarray (x, y, z, 28)
Matrix containing in the dimention the free water model parameters in
the following order:
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) The volume fraction of the free water compartment
S0 : ndarray (x, y, z)
The models estimate of the non diffusion-weighted signal S0.
"""
# preparing data and initializing parameters
data = np.asarray(data)
data_flat = np.reshape(data, (-1, data.shape[-1]))
S0out = S0.copy()
S0out = S0out.ravel()
# Computing WLS DTI solution for MD regularization
dtiparams = dti.wls_fit_tensor(design_matrix, data_flat)
md = dti.mean_diffusivity(dtiparams[..., :3])
cond = md > mdreg # removal condition
data_cond = data_flat[~cond, :]
# Initializing fw_params according to selected initial guess
if np.any(params) is None:
params_out = np.zeros((len(data_flat), 28))
dkiparams = dki.wls_fit_dki(design_matrix_dki, data_flat)
fweparams, sd = fwdti.wls_fit_tensor(design_matrix,
data_flat,
S0=S0,
Diso=Diso,
mdreg=2.7e-3)
params_out[:, 0:27] = dkiparams
params_out[:, 27] = fweparams[:, 12]
else:
params_out = params.copy()
params_out = np.reshape(params_out, (-1, params_out.shape[-1]))
params_cond = params_out[~cond, :]
S0_cond = S0out[~cond]
for vox in range(data_cond.shape[0]):
if np.all(data_cond[vox] == 0):
raise ValueError("The data in this voxel contains only zeros")
params = params_cond[vox]
# converting evals and evecs to diffusion tensor elements
evals = params[:3]
evecs = params[3:12].reshape((3, 3))
dt = lower_triangular(vec_val_vect(evecs, evals))
kt = params[..., 12:27]
s0 = S0_cond[vox]
MD = evals.mean()
# f transformation if requested
if f_transform:
f = np.arcsin(2 * params[27] - 1) + np.pi / 2
else:
f = params[27]
# Use the Levenberg-Marquardt algorithm wrapped in opt.leastsq
start_params = np.concatenate((dt, kt * MD * MD, [np.log(s0), f]),
axis=0)
this_tensor, status = opt.leastsq(_nls_err_func,
start_params,
args=(design_matrix_dki,
data_cond[vox], Diso,
f_transform))
# Invert f transformation if this was requested
if f_transform:
this_tensor[22] = 0.5 * (1 + np.sin(this_tensor[22] - np.pi / 2))
# The parameters are the evals and the evecs:
evals, evecs = decompose_tensor(from_lower_triangular(this_tensor[:6]))
MD = evals.mean()
params_cond[vox, :3] = evals
params_cond[vox, 3:12] = evecs.ravel()
params_cond[vox, 12:27] = this_tensor[6:21] / (MD**2)
params_cond[vox, 27] = this_tensor[22]
S0_cond[vox] = np.exp(-this_tensor[21])
params_out[~cond, :] = params_cond
params_out[cond, 27] = 1 # Only free water
params_out = np.reshape(params_out, (data.shape[:-1]) + (28, ))
S0out[~cond] = S0_cond
S0out[cond] = \
np.mean(data_flat[cond, :] / \
np.exp(np.dot(design_matrix[..., :6],
np.array([Diso, 0, Diso, 0, 0, Diso]))),
-1) # Only free water
S0out = S0out.reshape(data.shape[:-1])
return params_out, S0out
