mdt.model_building package

Submodules

mdt.model_building.likelihood_functions module

class mdt.model_building.likelihood_functions.Gaussian[source]

Bases: mdt.model_building.likelihood_functions.LikelihoodFunction

This uses the log of the Gaussian PDF for the likelihood function.

The PDF is defined as:

PDF = 1/(sigma * sqrt(2*pi)) * exp(-(observation - evaluation)^2 / (2 * sigma^2))

Taking the log, we get:

log(PDF) = - ((observation - evaluation)^2 / (2 * sigma^2)) - log(sigma * sqrt(2*pi))
class mdt.model_building.likelihood_functions.LikelihoodFunction(return_type, cl_function_name, parameters, cl_body, dependencies=None, model_function_priors=None)[source]

Bases: mdt.model_building.model_functions.SimpleModelCLFunction

The likelihood function is the model under which you evaluate the model estimates against observations.

A default implementation of a This CL function is for all estimable models

Parameters:
  • return_type (str) – the CL return type of the function
  • cl_function_name (string) – The name of the CL function
  • parameters (list or tuple of CLFunctionParameter) – The list of parameters required for this function
  • cl_body (str) – the cl body of this function
  • dependencies (list or tuple of CLFunction) – The list of CL libraries this function depends on
  • model_function_priors (list of mot.lib.cl_function.CLFunction) – list of priors concerning this whole model function. The parameter names of the given functions must match those of this function.
class mdt.model_building.likelihood_functions.OffsetGaussian[source]

Bases: mdt.model_building.likelihood_functions.LikelihoodFunction

This uses the log of an ‘offset Gaussian’ PDF for the likelihood function.

The PDF is defined as:

PDF = 1/(sigma * sqrt(2*pi)) * exp(-(observation - sqrt(evaluation^2 + sigma^2))^2 / (2 * sigma^2))

Where the log of the PDF is given by:

log(PDF) = - ((observation - sqrt(evaluation^2 + sigma^2))^2 / (2 * sigma^2)) - log(sigma * sqrt(2*pi))
class mdt.model_building.likelihood_functions.Rician[source]

Bases: mdt.model_building.likelihood_functions.LikelihoodFunction

This uses the log of the Rice PDF for the likelihood function.

The PDF is defined as:

PDF = (observation/sigma^2)
        * exp(-(observation^2 + evaluation^2) / (2 * sigma^2))
        * bessel_i0((observation * evaluation) / sigma^2)

Where where bessel_i0(z) is the modified Bessel function of the first kind with order zero.

The log of the PDF is given by:

log(PDF) = log(observation/sigma^2)
            - (observation^2 + evaluation^2) / (2 * sigma^2)
            + log(bessel_i0((observation * evaluation) / sigma^2))

mdt.model_building.model_functions module

class mdt.model_building.model_functions.ModelCLFunction(*args, **kw)[source]

Bases: MockClass

Extends a CLFunction with modeling information.

get_free_parameters()[source]

Get all the free parameters in this model

Returns:list of all the model parameters of type FreeParameter in this model
Return type:list of CLFunctionParameter
get_model_function_priors()[source]

Get all the model function priors.

Returns:
the priors for this model function,
these are supposed to be used in conjunction to the parameter priors.
Return type:list of mot.lib.cl_function.CLFunction
get_prior_parameters(parameter)[source]

Get the prior parameters of the given parameter.

Parameters:parameter (FreeParameter) – one of the parameters of this model function
Returns:the list of prior parameters for the given parameter
Return type:list of parameters
name

Get the name of this model function.

Returns:The name of this model function.
Return type:str
class mdt.model_building.model_functions.SimpleModelCLFunction(return_type, cl_function_name, parameters, cl_body, dependencies=None, model_function_priors=None)[source]

Bases: mdt.model_building.model_functions.ModelCLFunction, MockClass

A default implementation of a This CL function is for all estimable models

Parameters:
  • return_type (str) – the CL return type of the function
  • cl_function_name (string) – The name of the CL function
  • parameters (list or tuple of CLFunctionParameter) – The list of parameters required for this function
  • cl_body (str) – the cl body of this function
  • dependencies (list or tuple of CLFunction) – The list of CL libraries this function depends on
  • model_function_priors (list of mot.lib.cl_function.CLFunction) – list of priors concerning this whole model function. The parameter names of the given functions must match those of this function.
get_free_parameters()[source]

Get all the free parameters in this model

Returns:the list of free parameters in this model
Return type:list
get_model_function_priors()[source]

Get all the model function priors.

Returns:
the priors for this model function, these are supposed to be used in
conjunction to the parameter priors.
Return type:list[mot.lib.cl_function.CLFunction]
get_prior_parameters(parameter)[source]

Get the parameters referred to by the priors of each of the free parameters.

This returns a list of all the parameters referenced by the priors of the parameters, recursively.

Returns:
the list of additional parameters used by each of the
parameter priors
Return type:list of mot.lib.cl_function.CLFunctionParameter
name

Get the name of this model function, used in the composite model function

Returns:The name of this model function.
Return type:str
class mdt.model_building.model_functions.SimpleWeight(name='Weight', param_name='w', value=0.5, lower_bound=0.0, upper_bound=1.0, parameter_kwargs=None)[source]

Bases: mdt.model_building.model_functions.WeightType

A class that by itself defines the notion of a Weight.

Some of the code checks for type Weight, be sure to use this model function if you want to represent a Weight.

A weight is meant to be a model volume fraction.

Parameters:
  • name (str) – The name of the model
  • value (number or ndarray) – The initial value for the single free parameter of this function.
  • lower_bound (number or ndarray) – The initial lower bound for the single free parameter of this function.
  • upper_bound (number or ndarray) – The initial upper bound for the single free parameter of this function.
class mdt.model_building.model_functions.WeightType(return_type, cl_function_name, parameters, cl_body, dependencies=None, model_function_priors=None)[source]

Bases: mdt.model_building.model_functions.SimpleModelCLFunction

A class that defines the notion of a weighted compartment.

Some of the code checks for this class type, be sure to subclass this class if you want to represent a Weight.

A default implementation of a This CL function is for all estimable models

Parameters:
  • return_type (str) – the CL return type of the function
  • cl_function_name (string) – The name of the CL function
  • parameters (list or tuple of CLFunctionParameter) – The list of parameters required for this function
  • cl_body (str) – the cl body of this function
  • dependencies (list or tuple of CLFunction) – The list of CL libraries this function depends on
  • model_function_priors (list of mot.lib.cl_function.CLFunction) – list of priors concerning this whole model function. The parameter names of the given functions must match those of this function.

mdt.model_building.parameters module

mdt.model_building.signal_noise_models module

class mdt.model_building.signal_noise_models.JohnsonNoise[source]

Bases: mdt.model_building.signal_noise_models.SignalNoiseModel

Johnson noise adds noise to the signal using the formula:

sqrt(signal^2 + eta^2)
class mdt.model_building.signal_noise_models.SignalNoiseModel(return_type, cl_function_name, parameters, cl_body, dependencies=None, model_function_priors=None)[source]

Bases: mdt.model_building.model_functions.SimpleModelCLFunction

Signal noise models can add noise to the signal resulting from the model.

They require the signal resulting from the model and zero or more parameters and they return a new signal with noise added. This should have a model signature like:

double fname(double signal, <noise model parameters ...>);

For example, if the noise model has only one parameter ‘sigma’ the function should look like:

double fname(double signal, double sigma);
The CL function should return a single double that represents the signal with the signal noise
added to it.

A default implementation of a This CL function is for all estimable models

Parameters:
  • return_type (str) – the CL return type of the function
  • cl_function_name (string) – The name of the CL function
  • parameters (list or tuple of CLFunctionParameter) – The list of parameters required for this function
  • cl_body (str) – the cl body of this function
  • dependencies (list or tuple of CLFunction) – The list of CL libraries this function depends on
  • model_function_priors (list of mot.lib.cl_function.CLFunction) – list of priors concerning this whole model function. The parameter names of the given functions must match those of this function.

mdt.model_building.trees module

class mdt.model_building.trees.CompartmentModelTree(model_lists)[source]

Bases: mdt.model_building.trees.Tree

Builds a multi modal multi compartment model from the given model tree.

Valid model trees abides this grammar:

tree ::= model | ‘(‘ tree ‘)’ | ‘(‘ tree ‘,’ operator ‘)’ model ::= CompartmentModel [‘(‘ nickname ‘)’] operator ::= ‘*’ | ‘/’ | ‘+’ | ‘-‘

This means that one can build complex models consisting of compartment models combined using basic math operators.

Parameters:model_lists (list of mdt.models.compartments.CompartmentModel) – The model tree list
get_compartment_models()[source]

Get the compartment models that are part of this tree.

This basically just returns the leaves of the tree.

Returns:the compartments in this tree
Return type:list of mdt.models.compartments.CompartmentModel
class mdt.model_building.trees.Tree(data=None, tag=None, children=None, parent=None)[source]

Bases: object

Create a new Tree.

In this tree, every node is a tree object as well. The tree is implemented as a linked list. Each node has a reference to its children and to its parent node.

Parameters:
  • data – The data object
  • tag (str) – The tag used for displaying this node
  • children (list of Tree) – The list of children to this node
  • parent (Tree) – The parent tree node.
data

The data object

tag

The tag used for displaying this node

Type:str
children

The list of children to this node

Type:list of Tree
parent

The parent tree node.

Type:Tree
internal_nodes

Get all the non-leaves under this tree (the internal nodes).

Returns:A list of all non-leaves under this tree.
Return type:list
leaves

Get all the leaves under this tree.

Returns:A list of all leaves under this tree.
Return type:list

mdt.model_building.utils module

class mdt.model_building.utils.ParameterCodec(encode_func, decode_func, encode_bounds_func=None)[source]

Bases: object

Create a parameter codec container.

Parameters:
  • encode_func (mot.lib.cl_function.CLFunction) –

    An OpenCL function that is used in the CL kernel to transform the parameters from model space to encoded space so they can be used as input to an CL routine. The signature of the CL function is:

    void <fname>(void* data, local mot_float_type* x);
  • decode_func (mot.lib.cl_function.CLFunction) –

    An OpenCL function that is used in the CL kernel to transform the parameters from encoded space to model space so they can be used as input to the model. The signature of the CL function is:

    void <fname>(void* data, local mot_float_type* x);
  • encode_bounds_func (Callable[[array, array], Tuple[array, array]]) – encode the lower and upper bounds to bounds of the encoded parameter space. If not set, we won’t encode the bounds
decode(parameters, kernel_data=None, cl_runtime_info=None)[source]

Decode the given parameters using the given model.

This transforms the data from optimization space to model space.

Parameters:
  • parameters (ndarray) – The parameters to transform
  • (dict[str (kernel_data) – mot.lib.utils.KernelData]): the additional data to load
  • cl_runtime_info (mot.configuration.CLRuntimeInfo) – the runtime information
Returns:

The array with the transformed parameters.
Return type:

ndarray
encode(parameters, kernel_data=None, cl_runtime_info=None)[source]

Encode the given parameters using the given model.

This transforms the data from model space to optimization space.

Parameters:
  • parameters (ndarray) – The parameters to transform
  • (dict[str (kernel_data) – mot.lib.utils.KernelData]): the additional data to load
  • cl_runtime_info (mot.configuration.CLRuntimeInfo) – the runtime information
Returns:

The array with the transformed parameters.
Return type:

ndarray
encode_bounds(lower_bounds, upper_bounds)[source]

Encode the given bounds to the encoded parameter space.

Parameters:
  • lower_bounds (list) – for each parameter the lower bound(s). Each element can either be a scalar or a vector.
  • upper_bounds (list) – for each parameter the upper bound(s). Each element can either be a scalar or a vector.
Returns:

the lower and the upper bounds, in a similar structure as the input
Return type:

tuple
encode_decode(parameters, kernel_data=None, cl_runtime_info=None)[source]

First apply an encoding operation and then apply a decoding operation again.

This can be used to enforce boundary conditions in the parameters.

Parameters:
  • parameters (ndarray) – The parameters to transform
  • (dict[str (kernel_data) – mot.lib.utils.KernelData]): the additional data to load
  • cl_runtime_info (mot.configuration.CLRuntimeInfo) – the runtime information
Returns:

The array with the transformed parameters.
Return type:

ndarray
get_decode_function()[source]

Get a CL function that can transform the model parameters from encoded space to model space.

Returns:
An OpenCL function that is used in the CL kernel to transform the parameters
from encoded space to model space so they can be used as input to the model. The signature of the CL function is:
void <fname>(void* data, local mot_float_type* x);
Return type:mot.lib.cl_function.CLFunction
get_encode_function()[source]

Get a CL function that can transform the model parameters from model space to an encoded space.

Returns:
An OpenCL function that is used in the CL kernel to transform the parameters
from model space to encoded space so they can be used as input to an CL routine. The signature of the CL function is:
void <fname>(void* data, local mot_float_type* x);
Return type:mot.lib.cl_function.CLFunction
class mdt.model_building.utils.ParameterDecodingWrapper(nmr_parameters, decode_function)[source]

Bases: object

Wrap the objective function and constraint function with parameter decoding.

Parameters:
  • nmr_parameters (int) – the number of parameters to decode
  • decode_function (mot.lib.cl_function.CLFunction) –

    An OpenCL function that is used in the CL kernel to transform the parameters from encoded space to model space so they can be used as input to the model. The signature of the CL function is:

    void <fname>(void* data, local mot_float_type* x);
wrap_constraints_function(constraints_func)[source]

Decorates the given constraint function with parameter decoding.

Parameters:constraints_func (mot.optimize.base.ConstraintFunction) –

A CL function with the signature:

void <func_name>(local mot_float_type* x,
                 void* data,
                 local mot_float_type* constraints);
Returns:the wrapped constraint function.
Return type:mot.optimize.base.ConstraintFunction
wrap_input_data(input_data)[source]

Wrap the input data with extra information this wrapper might need.

Parameters:input_data (mot.lib.kernel_data.KernelData) – the kernel data we will wrap
Returns:the wrapped kernel data
Return type:mot.lib.kernel_data.KernelData
wrap_objective_function(objective_function)[source]

Decorates the given objective function with parameter decoding.

Parameters:objective_function (mot.lib.cl_function.CLFunction) –

A CL function with the signature:

double <func_name>(local mot_float_type* x,
                   void* data,
                   local mot_float_type* objective_list);
Returns:the wrapped objective function.
Return type:mot.lib.cl_function.CLFunction

Module contents