mcot.dippi.model

Probabilistic model

Classes

Model(shells[, T2, dual_phase, only_phase])	Model to fit to the DIPPI data
Parameters(as_dict, shells, …)	Object representing a set of model parameters across all shells and fibre populations (for a single voxel)
ShellParams(all_params, idx_fibre, idx_shell)	Dictionary-like object to read/write parameters for a single shell of diffusion-weighted phase data

Functions

alignment(phi, theta, bvec[, sympy])	Computes the dot-product between the fibre alignment and the gradient orientation
default_dependencies()	Defines which parameters depend on which variables
eddy_gradient(complex_signal, bvecs)	Estimates the phase gradient with bvecs
estimate_eddy(current_fit, data)	Estimates the first-order spherical harmonic components of the eddy currents
fit(parameters, data, model[, even_eddy, …])	Multi-step fitting procedure for diffusion-weighted phase data in a single voxel
get_bounds(parameters, tobound)	Defines the bounds
global_fit(best_fit, data, tofit, model)	Global fit to the chosen parameters using dual annealing
myelin_phase(shell, phi, theta, mean_log_g)	Computes the intra-axonal phase accumulation due to myelin in rad
single_fit(parameters, data, tofit, model[, …])	Local fit of parameters using scipy.optimize.minimize

alignment

mcot.dippi.model.alignment(phi, theta, bvec, sympy=True)

Computes the dot-product between the fibre alignment and the gradient orientation

Parameters

• phi – angle in x-y plane (longitude)

• theta – angle with respect to z-axis (latitude)

• bvec – (…, 3) array with gradient orientations

• sympy – set to True for sympy input, False for numpy input

Returns

(…, ) array with dot-product

default_dependencies

mcot.dippi.model.default_dependencies()

Defines which parameters depend on which variables

Returns

a (“param”x”depends”) boolean xarray, which is True if a specific parameter varies along a specific axis (e.g., log_g depends on fibre population, but not any of the acquisition parameters, so is only true for depends=fibre)

eddy_gradient

mcot.dippi.model.eddy_gradient(complex_signal, bvecs)

Estimates the phase gradient with bvecs

Parameters

• complex_signal – (N, ) array with complex signal

• bvecs – (N, 3) array with gradient orientations (should all be unit length)

Returns

(3, ) array with the gradients

estimate_eddy

mcot.dippi.model.estimate_eddy(current_fit: mcot.dippi.model.Parameters, data)

Estimates the first-order spherical harmonic components of the eddy currents

Parameters

• current_fit – current best fit parameters. The first three values of eddy_odd are updated in place.

• data – for each shell a length 2 sequence with the signal in both readouts

fit

mcot.dippi.model.fit(parameters, data, model: mcot.dippi.model.Model, even_eddy=False, only_myelin=False, movement_phase=True, nfit=100, return_all=False, fit_2D=False, verbose=False) → mcot.dippi.model.Parameters

Multi-step fitting procedure for diffusion-weighted phase data in a single voxel

Parameters

• parameters – acquisition parameters (can be created from Parameters.empty())

• data – for each shell a length 2 sequence with the signal in both readouts (complex if only_mag is False)

• model – which model to fit to the data

• even_eddy – if True include the effect of the even component of the eddy current spherical harmonics

• only_myelin – don’t fit the non-myelin contribution to the phase

• movement_phase – include random phase offsets before the first readout

• nfit – maximum number of fits during global optimisation

• return_all – return all local fits of global optimisation rather than just be best one

• fit_2D – fits data with gradients only in the x-y plane

• verbose – if True report on intermediate fits (2 for very verbose)

Returns

best-fit parameters

get_bounds

mcot.dippi.model.get_bounds(parameters: mcot.dippi.model.Parameters, tobound)

Defines the bounds

Parameters

• parameters – any set of parameters including definition of the acquisition

• tobound – names of parameters for which bounds will be returned

Returns

sequence of tuples with lower and upper bound for each parameter

global_fit

mcot.dippi.model.global_fit(best_fit: mcot.dippi.model.Parameters, data, tofit, model: mcot.dippi.model.Model) → mcot.dippi.model.Parameters

Global fit to the chosen parameters using dual annealing

Parameters

• best_fit – best fit in the optimisation so far

• data – for each shell a length 2 sequence with the signal in both readouts (complex if only_mag is False)

• tofit – sequence of which parameters to fit

• only_mag – if True only consider the magnitude (no complex signal)

• fit_T2 – if True use the values for R2 & R2i, rather than R2_attenuation

• dual_phase – if True use the dual population rather than single population model for log(g)

• even_eddy – if True include the effect of the even component of the eddy current spherical harmonics

Returns

new set of parameters after global optimisation

myelin_phase

mcot.dippi.model.myelin_phase(shell, phi, theta, mean_log_g, sympy=True)

Computes the intra-axonal phase accumulation due to myelin in rad

Parameters

• shell – acquisition details

• phi – fibre angle

• theta – fibre angle

• mean_log_g – average log(g) in the fibre population

• sympy – set to True for sympy input, False for numpy input

Returns

phase accumulated at second readout in rad

single_fit

mcot.dippi.model.single_fit(parameters: mcot.dippi.model.Parameters, data, tofit, model: mcot.dippi.model.Model, scipy_kwargs=None, only_mag=False, verbose=False) → mcot.dippi.model.Parameters

Local fit of parameters using scipy.optimize.minimize

Parameters

• parameters – initial guess of parameters (and acquisition parameters)

• data – for each shell a length 2 sequence with the signal in both readouts

• tofit – sequence of which parameters to fit

• model – model to fit to the data

• scipy_kwargs – keyword arguments to pass on to scipy

• only_mag – if True only consider the magnitude (no complex signal)

• verbose – if True report on intermediate fits (2 for very verbose)

Returns

updated estimate of parameters