mdt.models package

Submodules

mdt.models.base module

class mdt.models.base.EstimableModel(*args, **kwargs)

Bases: object

This is an interface for all methods needed to be able to optimize and sample a model.

get_constraints_function()

The function for the (inequality) constraints.

Returns:the CL function for the inequality constraints of this model. Return type:mot.lib.cl_function.CLFunction

get_finalize_proposal_function()

Get the function used to finalize the proposal.

This function is used to finalize the proposals during sampling.

Returns:the CL function used to finalize a proposal during sampling. Return type:mot.lib.cl_function.CLFunction

get_free_param_names()

Get the names of the free parameters.

Returns:the name of the free parameters Return type:List

get_initial_parameters()

Get the initial parameters for each of the voxels.

Returns:2d array with for every problem (first dimension) the initial parameters (second dimension). Return type:ndarray

get_input_data_problems(input_data=None)

Get all the problems with the protocol.

Parameters:input_data (mdt.lib.input_data.MRIInputData) – The input data we intend on using with this model. Returns:

A list of

InputDataProblem instances or subclasses of that baseclass. These objects indicate the problems with the protocol and this model.

Return type:list of InputDataProblem

get_kernel_data()

Get the kernel data this model needs for evaluation in OpenCL.

This is needed for evaluating the priors, likelihoods and other functions.

Returns:the kernel data used by this model Return type:mot.lib.kernel_data.KernelData

get_log_likelihood_function()

For sampling, get the log-likelihood function.

Returns:the CL function for the log likelihood function during MCMC sampling Return type:mot.lib.cl_function.CLFunction

get_log_prior_function()

Get the prior function used during sampling.

Returns:the CL function for the log prior function during MCMC sampling Return type:mot.lib.cl_function.CLFunction

get_lower_bounds()

Get the lower bounds.

Returns:

for every parameter a lower bound which can either be None, a scalar or a vector with a

lower bound per problem instance.

Return type:List

get_mle_codec()

Get a parameter codec that can be used to transform the parameters to and from optimization and model space.

Returns:an instance of a parameter codec Return type:mdt.model_building.utils.ParameterCodec

get_nmr_observations()

Get the number of observations in the data.

Returns:the number of observations present in the data Return type:int

get_nmr_parameters()

Get the number of estimable parameters in this model.

Returns:the number of estimable parameters Return type:int

get_objective_function()

For minimization, get the negative of the log-likelihood function.

Returns:the CL function for the optimization routines in MOT. Return type:mot.lib.cl_function.CLFunction

get_post_optimization_output(optimized_parameters, roi_indices=None, parameters_dict=None)

Get the output after optimization.

This is called by the processing strategy to finalize the optimization of a batch of voxels.

Parameters:

• optimized_parameters (ndarray) – the array of optimized parameters
• roi_indices (Iterable or None) – if set, the problem instances optimized in this batch
• parameters_dict (dict) – same data as optimized_parameters, only then represented as a dict. Only needed if available, to speed up this function.

Returns:

dictionary with results maps, can be nested which should translate to sub-directories.

Return type:

dict

get_post_sampling_maps(sampling_output, roi_indices=None)

Get the post sampling volume maps.

This will return a dictionary mapping folder names to dictionaries with volumes to write.

Parameters:

• sampling_output (mot.sample.base.SamplingOutput) – the output of the sampler
• roi_indices (Iterable or None) – if set, the problem instances sampled in this batch

Returns:

a dictionary with for every subdirectory the maps to save

Return type:

dict

get_random_parameter_positions(nmr_positions=1)

Get one or more random parameter positions centered around the initial parameters.

This can be used to generate random starting points for sampling routines with multiple walkers.

Per position requested, this function generates a normal distribution around the initial parameters (using get_initial_parameters()) with the standard deviation derived from the random walk metropolis std.

Returns:a 3d matrix for (voxels, parameters, nmr_positions). Return type:ndarray

get_rwm_epsilons()

Get per parameter a value small relative to the parameter’s standard deviation.

This is used in, for example, the SCAM Random Walk Metropolis sampling routine to add to the new proposal standard deviation to ensure it does not collapse to zero.

Returns:per parameter an epsilon, relative to the proposal standard deviation Return type:list

get_rwm_proposal_stds()

Get the Random Walk Metropolis proposal standard deviations for every parameter and every problem instance.

These proposal standard deviations are used in Random Walk Metropolis MCMC sample.

Returns:the proposal standard deviations of each free parameter, for each problem instance Return type:ndarray

get_upper_bounds()

Get the upper bounds.

Returns:

for every parameter an upper bound which can either be None, a scalar or a vector with a

upper bound per problem instance.

Return type:List

get_used_volumes(input_data=None)

Get the indices of the input data volumes used by this model.

Parameters:input_data (mdt.lib.input_data.MRIInputData) – if given, limit the analysis to this input data. Returns:the list of volume indices with volumes to use. This indexes the input data. Return type:List

is_input_data_sufficient(input_data=None)

Check if the input data has enough information for this model to work.

Parameters:input_data (mdt.lib.input_data.MRIInputData) – The input data we intend on using with this model. Returns:True if there is enough information in the input data, false otherwise. Return type:boolean

name

The name of this model.

Returns:the name of this model. Return type:str

set_input_data(input_data, suppress_warnings=False)

Set the input data this model will deal with.

Parameters:

• input_data (mdt.lib.input_data.MRIInputData) – The container for the data we will use for this model.
• suppress_warnings (boolean) – set to suppress all warnings

Returns:

Returns self for chainability

update_active_post_processing(processing_type, settings)

Update the active post-processing semaphores.

It is possible to control which post-processing routines get run by overwriting them using this method. For a list of post-processors, please see the default mdt configuration file under active_post_processing.

Parameters:

• processing_type (str) – one of sample or optimization.
• settings (dict) – the items to set in the post-processing information

class mdt.models.base.InputDataProblem

Bases: object

The base class for indicating problems with the input data.

These are meant to be returned from the function get_input_data_problems().

Each of these problems is supposed to overwrite the function __str__() for reporting the problem.

class mdt.models.base.MissingProtocolInput(missing_columns)

Bases: mdt.models.base.InputDataProblem

class mdt.models.base.NamedProtocolProblem(model_protocol_problem, model_name)

Bases: mdt.models.base.InputDataProblem

This extends the given model protocol problem to also include the name of the model.

Parameters:

• model_protocol_problem (InputDataProblem) – The name for the problem with the given model.
• model_name (str) – the name of the model

mdt.models.compartments module

class mdt.models.compartments.CacheInfo(fields, cl_code)

Bases: object

A storage container for the cache info of an compartment function.

Parameters:

• fields (list of tuple) – the list of fields used in the cache. Each tuple element consists of (ctype, name, nmr_elements).
• cl_code (str) – the body of the CL code needed for the cache initialization. This will be turned into a function by the compartment model.

class mdt.models.compartments.CompartmentModel(*args, **kw)

Bases: mdt.model_building.model_functions.ModelCLFunction

get_cache_init_function()

Get the CL function for initializing the cache struct of this compartment.

Please note that this function does not the struct type definitions of the cache. These need to be appended manually using the get_cache_struct().

Returns:

the CL function for initializing the cache. This function

should have the same signature as the compartment model function.

Return type:None or mot.lib.cl_function.CLFunction

get_cache_struct(address_space)

Get the cache data for this compartment model.

Parameters:address_space (str) – the address space for the cache, either ‘local’ or ‘private’ Returns:the cache structure Return type:Optional[mdt.model_building.computation_caching.CacheStruct]

get_constraints_func()

Get a tuple with the constraint function information.

If no constraints are defined for this model function, return None

Returns:

None if no constraints are defined for this model. Else,

a constraint function.

Return type:None or mot.optimize.base.ConstraintFunction

get_extra_optimization_maps_funcs()

Get a list of functions to produce additional results post optimization.

Returns:the list of functions to be called Return type:list of functions

get_extra_sampling_maps_funcs()

Get a list of functions to produce additional results post sampling.

These functions can return additional maps as sampling output.

Returns:the list of functions to be called Return type:list of functions

class mdt.models.compartments.DMRICompartmentModelFunction(return_type, cl_function_name, parameters, cl_body, dependencies=None, constraints_func=None, model_function_priors=None, extra_optimization_maps_funcs=None, extra_sampling_maps_funcs=None, nickname=None, cache_info=None)

Bases: mdt.models.compartments.CompartmentModel, mdt.model_building.model_functions.SimpleModelCLFunction

Create a new dMRI compartment model function.

Parameters:

• return_type (str) – the CL return type
• cl_function_name (str) – the name of this function in the CL kernel
• parameters (list of CLFunctionParameter) – the list of the function parameters
• cl_body (str) – the body of the CL code
• dependencies (list) – the list of functions we depend on inside the kernel
• constraints_func (mot.optimize.base.ConstraintFunction) – a constraint function for this compartment
• model_function_priors (list of mot.lib.cl_function.CLFunction) – additional compartment priors on top of the parameter priors.
• extra_optimization_maps_funcs (None or list or tuple) – a list of modification callbacks to add new maps after optimization.
• extra_sampling_maps_funcs (None or list or tuple) – a list of functions that can return additional maps after sampling.
• nickname (str or None) – the nickname of this compartment model function. If given, this is the name of this compartment in a composite model function tree
• cache_info (Optional[CacheInfo]) – the cache information for this compartment

evaluate(*args, **kwargs)

get_cache_init_function()

Get the CL function for initializing the cache struct of this compartment.

Please note that this function does not the struct type definitions of the cache. These need to be appended manually using the get_cache_struct().

Returns:

the CL function for initializing the cache. This function

should have the same signature as the compartment model function.

Return type:None or mot.lib.cl_function.CLFunction

get_cache_struct(address_space)

Get the cache data for this compartment model.

Parameters:address_space (str) – the address space for the cache, either ‘local’ or ‘private’ Returns:the cache structure Return type:Optional[mdt.model_building.computation_caching.CacheStruct]

get_constraints_func()

Get a tuple with the constraint function information.

If no constraints are defined for this model function, return None

Returns:

None if no constraints are defined for this model. Else,

a constraint function.

Return type:None or mot.optimize.base.ConstraintFunction

get_extra_optimization_maps_funcs()

Get a list of functions to produce additional results post optimization.

Returns:the list of functions to be called Return type:list of functions

get_extra_sampling_maps_funcs()

Get a list of functions to produce additional results post sampling.

These functions can return additional maps as sampling output.

Returns:the list of functions to be called Return type:list of functions

name

Get the name of this model function.

Returns:The name of this model function. Return type:str

class mdt.models.compartments.WeightCompartment(return_type, cl_function_name, parameters, cl_body, dependencies=None, model_function_priors=None, nickname=None)

Bases: mdt.models.compartments.CompartmentModel, mdt.model_building.model_functions.WeightType

Create a new weight for use in composite models

Parameters:

• cl_function_name (str) – the name of this function in the CL kernel
• parameters (list of CLFunctionParameter) – the list of the function parameters
• cl_body (str) – the body of the CL code
• dependencies (list) – the list of functions we depend on inside the kernel
• return_type (str) – the CL return type
• model_function_priors (list of mot.lib.cl_function.CLFunction) – additional compartment priors on top of the parameter priors.
• nickname (str or None) – the nickname of this compartment model function. If given, this is the name of this compartment in a composite model function tree

get_cache_init_function()

Get the CL function for initializing the cache struct of this compartment.

Please note that this function does not the struct type definitions of the cache. These need to be appended manually using the get_cache_struct().

Returns:

the CL function for initializing the cache. This function

should have the same signature as the compartment model function.

Return type:None or mot.lib.cl_function.CLFunction

get_cache_struct(address_space)

Get the cache data for this compartment model.

Parameters:address_space (str) – the address space for the cache, either ‘local’ or ‘private’ Returns:the cache structure Return type:Optional[mdt.model_building.computation_caching.CacheStruct]

get_constraints_func()

Get a tuple with the constraint function information.

If no constraints are defined for this model function, return None

Returns:

None if no constraints are defined for this model. Else,

a constraint function.

Return type:None or mot.optimize.base.ConstraintFunction

get_extra_optimization_maps_funcs()

Get a list of functions to produce additional results post optimization.

Returns:the list of functions to be called Return type:list of functions

get_extra_sampling_maps_funcs()

Get a list of functions to produce additional results post sampling.

These functions can return additional maps as sampling output.

Returns:the list of functions to be called Return type:list of functions

name

Get the name of this model function.

Returns:The name of this model function. Return type:str

mdt.models.composite module

class mdt.models.composite.CompositeModelFunction(model_tree, signal_noise_model=None)

Bases: MockClass

The model function for the total constructed model.

This combines all the functions in the model tree into one big function and exposes that function and its parameters.

Parameters:

• model_tree (mdt.model_building.trees.CompartmentModelTree) – the model tree object
• signal_noise_model (mdt.model_building.signal_noise_models.SignalNoiseModel) – the optional signal noise model to use to add noise to the model prediction

evaluate(inputs, nmr_instances, **kwargs)

get_model_function_parameters()

Get the parameters to use in the model function.

Returns:

per parameter a tuple with (model, parameter, cl_name, external_name)

where the cl_name is how we reference the parameter in the CL code and the external_name is how we reference the parameter in a call to for example ‘evaluate’.

Return type:list of tuples

get_model_parameter_list()

Get the model and parameter tuples that constructed this composite model.

This is used by the model builder, to construct the model function call.

Returns:the list of (model, parameter) tuples for each of the models and parameters. Return type:list of tuple

class mdt.models.composite.DMRICompositeModel(model_name, model_tree, likelihood_function, signal_noise_model=None, input_data=None, enforce_weights_sum_to_one=True, volume_selection=True)

Bases: mdt.models.base.EstimableModel

A model builder for a composite dMRI sample and optimization model.

It implements some protocol check functions. These are used by the fit_model functions in MDT to check if the protocol is correct for the model we try to fit.

Parameters:

• model_name (str) – the name of the model
• model_tree (mdt.model_building.trees.CompartmentModelTree) – the model tree object
• likelihood_function (mdt.model_building.likelihood_functions.LikelihoodFunction) – the likelihood function to use for the resulting complete model.
• signal_noise_model (mdt.model_building.signal_noise_models.SignalNoiseModel) – the optional signal noise model to use to add noise to the model prediction
• input_data (mdt.lib.input_data.MRIInputData) – the input data container
• enforce_weights_sum_to_one (boolean) – if we want to enforce that weights sum to one. This does the following things; it fixes the first weight to the sum of the others and it adds a transformation that ensures that those other weights sum to at most one.
• volume_selection (boolean) – if we should do volume selection or not, set this before calling set_input_data.

_constraints

the constraint functions

Type:List[mot.optimize.base.ConstraintFunction]

_model_priors

the list of model priors this class will also use (next to the priors defined in the parameters).

Type:List[mot.lib.cl_function.CLFunction]

_proposal_callbacks

the list of proposal callbacks. Each element in the list consists of a tuple with two elements, first a reference to the used compartments (as a list of (compartment, parameter) tuples), second the CL function to call (using those parameters).

Proposals generated during sample may sometimes require transformations to transform the proposal vector. For example, in the case of sample a spherical coordinate system, this callback can be used to transform both the inclination and the azimuth at the same time to an antipodal point.

Type:Iterable[Tuple[Tuple[CompartmentFunction, CLFunctionParameter], CLFunction]]

compute_covariance_matrix(parameters, roi_indices=None)

Calculate the covariance and correlation matrix by taking the inverse of the Hessian.

This first calculates/approximates the Hessian at each of the points using numerical differentiation. Afterwards we inverse the Hessian to return the covariance matrix.

This function only returns the upper triangular data of the covariance matrix.

Parameters:

• parameters (ndarray) – for each voxel, the optimized parameters
• roi_indices (Iterable or None) – if set, the problem instances optimized in this batch.

Returns:

for each voxel (first dimension ) a covariance matrix (second dimension)

Return type:

ndarray

fix(model_param_name, value)

Fix the given model.param to the given value.

Parameters:

• model_param_name (string) – A model.param name like ‘Ball.d’
• value (scalar or vector or string or AbstractParameterDependency) – The value or dependency to fix the given parameter to.

Returns:

Returns self for chainability

get_active_post_processing()

Get a dictionary with the active post processing.

This returns a dictionary with as first level the processing type and as second level the post-processing options.

Returns:the dictionary with the post-processing options for both sample and optimization. Return type:dict

get_composite_model_function()

Get the composite model function for the current model tree.

The output model function of this class is a subclass of CLFunction meaning it can be used to evaluate the model given some input parameters.

This function does not incorporate the likelihood function (Gaussian, Rician, etc.), but does incorporate the signal noise model (JohnsonNoise for example).

Returns:the model function for the composite model Return type:CompositeModelFunction

get_constraints_function()

The function for the (inequality) constraints.

get_covariance_output_names()

Get pretty names for each of the covariance matrix outputs.

This corresponds to the output array from compute_covariance_matrix().

Returns:for each elements in the upper triangular covariance vector, a pretty name Return type:List[str]

get_finalize_proposal_function()

Get the function used to finalize the proposal.

This function is used to finalize the proposals during sampling.

Returns:the CL function used to finalize a proposal during sampling. Return type:mot.lib.cl_function.CLFunction

get_free_param_names()

Get the names of the free parameters

get_initial_parameters()

Get the initial parameters for all the voxels in the input data.

Returns:2d array with for every problem (first dimension) the initial parameters (second dimension). Return type:ndarray

get_input_data()

Get the input data actually being used by this model.

Returns:the input data being used by this model Return type:mdt.lib.input_data.MRIInputData

get_input_data_problems(input_data=None)

Get all the problems with the protocol.

Parameters:input_data (mdt.lib.input_data.MRIInputData) – The input data we intend on using with this model. Returns:

A list of

InputDataProblem instances or subclasses of that baseclass. These objects indicate the problems with the protocol and this model.

Return type:list of InputDataProblem

get_kernel_data()

Get the kernel data this model needs for evaluation in OpenCL.

This is needed for evaluating the priors, likelihoods and other functions.

Returns:the kernel data used by this model Return type:mot.lib.kernel_data.KernelData

get_log_likelihood_function()

For sampling, get the log-likelihood function.

get_log_prior_function()

Get the prior function used during sampling.

get_lower_bounds()

Get the lower bounds.

Returns:

for every parameter a lower bound which can either be None, a scalar or a vector with a

lower bound per problem instance.

Return type:List

get_mle_codec()

Get a parameter codec that can be used to transform the parameters to and from optimization and model space.

This does two things: - It applies the transformation of each of the parameters - For compartments with both a mdt.model_building.parameters.PolarAngleParameter and

mdt.model_building.parameters.AzimuthAngleParameter, we apply the right spherical transformation to put the spherical coordinates in the right spherical hemisphere.

Returns:an instance of a parameter codec Return type:mdt.model_building.utils.ParameterCodec

get_model_eval_function()

get_nmr_observations()

Get the number of observations in the data.

Returns:the number of observations present in the data Return type:int

get_nmr_parameters()

Get the number of estimable parameters in this model.

Returns:the number of estimable parameters Return type:int

get_objective_function()

For minimization, get the negative of the log-likelihood function.

get_post_optimization_output(optimized_parameters, roi_indices=None, parameters_dict=None)

Get the output after optimization.

This is called by the processing strategy to finalize the optimization of a batch of voxels.

Returns:dictionary with results maps, can be nested which should translate to sub-directories. Return type:dict

get_post_sampling_maps(sampling_output, roi_indices=None)

Get the post sample volume maps.

This will return a dictionary mapping folder names to dictionaries with volumes to write.

Parameters:

• sampling_output (mot.sample.base.SamplingOutput) – the output of the sampler
• roi_indices (Iterable or None) – if set, the problem instances optimized in this batch

Returns:

a dictionary with for every subdirectory the maps to save

Return type:

dict

get_random_parameter_positions(nmr_positions=1)

Get one or more random parameter positions centered around the initial parameters.

This can be used to generate random starting points for sampling routines with multiple walkers.

Per position requested, this function generates a normal distribution around the initial parameters (using get_initial_parameters()) with the standard deviation derived from the random walk metropolis std.

Returns:a 3d matrix for (voxels, parameters, nmr_positions). Return type:ndarray

get_required_protocol_names()

Get a list with the constant data names that are needed for this model to work.

For example, an implementing diffusion MRI model might require the presence of the protocol parameter ‘g’ and ‘b’. This function should then return (‘g’, ‘b’).

Returns:A list of columns names that need to be present in the protocol Return type:list

get_rwm_epsilons()

Get per parameter a value small relative to the parameter’s standard deviation.

This is used in, for example, the SCAM Random Walk Metropolis sampling routine to add to the new proposal standard deviation to ensure it does not collapse to zero.

Returns:per parameter an epsilon, relative to the proposal standard deviation Return type:list

get_rwm_proposal_stds()

Get the Random Walk Metropolis proposal standard deviations for every parameter and every problem instance.

These proposal standard deviations are used in Random Walk Metropolis MCMC sample.

Returns:the proposal standard deviations of each free parameter, for each problem instance Return type:ndarray

get_upper_bounds()

Get the upper bounds.

Returns:

for every parameter an upper bound which can either be None, a scalar or a vector with a

upper bound per problem instance.

Return type:List

get_used_volumes(input_data=None)

Get the indices of the input data volumes used by this model.

Parameters:input_data (mdt.lib.input_data.MRIInputData) – if given, limit the analysis to this input data. Returns:the list of volume indices with volumes to use. This indexes the input data. Return type:List

has_parameter(model_param_name)

Check to see if the given parameter is defined in this model.

Parameters:model_param_name (string) – A model.param name like ‘Ball.d’ Returns:true if the parameter is defined in this model, false otherwise. Return type:boolean

init(model_param_name, value)

Init the given model.param to the given value.

Parameters:

• model_param_name (string) – A model.param name like ‘Ball.d’
• value (scalar or vector) – The value to initialize the given parameter to

Returns:

Returns self for chainability

is_input_data_sufficient(input_data=None)

Check if the input data has enough information for this model to work.

Parameters:input_data (mdt.lib.input_data.MRIInputData) – The input data we intend on using with this model. Returns:True if there is enough information in the input data, false otherwise. Return type:boolean

name

The name of this model.

Returns:the name of this model. Return type:str

param_dict_to_array(volume_dict)

set_initial_parameters(initial_params)

Update the initial parameters for this model by the given values.

This only affects free parameters.

Parameters:initial_params (dict) – a dictionary containing as keys full parameter names (<model>.<param>) and as values numbers or arrays to be used as starting point

set_input_data(input_data, suppress_warnings=False)

Set the input data this model will deal with.

Parameters:

• input_data (mdt.lib.input_data.MRIInputData) – The container for the data we will use for this model.
• suppress_warnings (boolean) – set to suppress all warnings

Returns:

Returns self for chainability

set_lower_bound(model_param_name, value)

Set the lower bound for the given parameter to the given value.

Parameters:

• model_param_name (string) – A model.param name like ‘Ball.d’
• value (scalar or vector) – The value to set the lower bounds to, either a single value for every voxel or a value per voxel.

Returns:

Returns self for chainability

set_lower_bounds(lower_bounds)

Apply multiple lower bounds from a dictionary.

Parameters:lower_bounds (dict) – per parameter a lower bound Returns:Returns self for chainability

set_upper_bound(model_param_name, value)

Set the upper bound for the given parameter to the given value.

Parameters:

• model_param_name (string) – A model.param name like ‘Ball.d’
• value (scalar or vector) – The value to set the upper bounds to, either a single value for every voxel or a value per voxel.

Returns:

Returns self for chainability

set_upper_bounds(upper_bounds)

Apply multiple upper bounds from a dictionary.

Parameters:upper_bounds (dict) – per parameter a upper bound Returns:Returns self for chainability

unfix(model_param_name)

Unfix the given model.param

Parameters:model_param_name (string) – A model.param name like ‘Ball.d’ Returns:Returns self for chainability

update_active_post_processing(processing_type, settings)

Update the active post-processing semaphores.

It is possible to control which post-processing routines get run by overwriting them using this method. For a list of post-processors, please see the default mdt configuration file under active_post_processing.

Parameters:

• processing_type (str) – one of sample or optimization.
• settings (dict) – the items to set in the post-processing information

class mdt.models.composite.ExtraOptimizationMapsInfo(model, results, input_data, roi_indices)

Bases: collections.abc.Mapping

Container holding information usable for computing extra optimization maps, after optimization.

For backwards compatibility, this class functions both as a dictionary as well as a data container. That is, one can index this object with map names and it will forward those indices to the results container. Additionally, it provides some auxiliary data and functions for getting protocol information.

Parameters:

• model (DMRICompositeModel) – the model used to compute the results
• results (dict) – the dictionary with all the optimization results
• input_data (mdt.lib.input_data.MRIInputData) – the input data used during the optimization
• roi_indices (ndarray) – a one dimensional array with indices in the region of interest This holds the voxels we are currently optimizing.

copy_with_different_results(new_results)

Create a copy of this optimization maps info but then with different result maps.

Parameters:results (dict) – the dictionary with the new set of optimization results Returns:same as the current class but then with updated results Return type:ExtraOptimizationMapsInfo

get_input_data(parameter_name)

Get the input data for the given parameter.

This gets the input data from the protocol and for maps it only returns the voxels within the voxel roi indices we optimized.

Parameters:parameter_name (str) – the name of the parameter for which we want to get input data Returns:either a scalar, a vector or a matrix with values for the given parameter. Return type:float, ndarray or None Raises:ValueError – if no suitable value can be found.

class mdt.models.composite.ModelFunctionsInformation(model_tree, likelihood_function, signal_noise_model=None, enable_prior_parameters=False)

Bases: object

Contains centralized information about the model functions in the model builder parent.

Parameters:

• model_tree (mdt.model_building.trees.CompartmentModelTree) – the model tree object
• likelihood_function (mdt.model_building.likelihood_functions.LikelihoodFunction) – the likelihood function to use for the resulting complete model
• signal_noise_model (mdt.model_building.signal_noise_models.SignalNoiseModel) – the signal noise model to use to add noise to the model prediction
• enable_prior_parameters (boolean) – adds possible prior parameters to the list of parameters in the model

fix_parameter(parameter_name, value)

Fix the indicated free parameter to the given value.

Parameters:

• parameter_name (string) – A model.param name like ‘Ball.d’
• value (scalar or vector or string or AbstractParameterDependency) – The value or dependency to fix the given parameter to.

get_all_protocol_parameters()

Gets the protocol parameters (as model, parameter tuples) from the model listing.

get_compartment_models()

Get a list of all the compartment models in the model.

Returns:the compartment models in this composite model Return type:list of mdt.models.compartments.CompartmentModel

get_default_parameter_value(parameter_name)

Get the default parameter value for the given parameter. This is regardless of model fixation.

The default parameter value is the parameter value as originally defined in the model parameter.

Returns:the value for the given parameter Return type:float or ndarray

get_dependency_fixed_parameters_list(exclude_priors=False)

Gets a list (as model, parameter tuples) of all parameters that are fixed to a dependency.

Parameters:exclude_priors (boolean) – if we want to exclude the parameters for the priors Returns:the list of value fixed parameters Return type:list of tuple

get_estimable_parameters_list(exclude_priors=False)

Gets a list (as model, parameter tuples) of all parameters that are estimable.

Parameters:exclude_priors (boolean) – if we want to exclude the parameters for the priors Returns:the list of estimable parameters Return type:list of tuple

get_estimable_weights()

Get all the estimable weights.

Returns:the list of compartment models/parameter pairs for models that are a subclass of WeightType Return type:list of tuples

get_free_parameters_list(exclude_priors=False)

Gets the free parameters as (model, parameter) tuples from the model listing. This does not incorporate checking for fixed parameters.

Parameters:exclude_priors (boolean) – if we want to exclude the parameters for the priors Returns:the list of tuples containing (model, parameters) Return type:list of tuple

get_model_list()

Get the list of all the applicable model functions

Returns:the list of model functions. Return type:list of mdt.model_building.model_functions.ModelCLFunction

get_model_parameter_by_name(parameter_name)

Get the parameter object of the given full parameter name in dot format.

Parameters:parameter_name (string) – the parameter name in dot format <model>.<param>, or in bar format <model>_<param>. If the bar format leads to ambiguous results, an exception will be raised. Returns:containing the (model, parameter) pair for the given parameter name Return type:tuple

get_model_parameter_list()

Get a list of all model, parameter tuples.

Returns:the list of tuples containing (model, parameters) Return type:list of tuple

get_noise_std_param()

Get a reference to the noise standard deviation parameter in the likelihood model.

Returns:the reference to the NoiseStdFreeParam of the likelihood model Return type:parameter

get_parameter_estimable_index(model, param)

Get the index of this parameter in the parameters list

This returns the position of this parameter in the ‘x’, parameter vector in the CL kernels.

Parameters:

• model (mdt.model_building.model_functions.ModelCLFunction) – the model function
• param (mot.cl_parameter.CLFunctionParameter) – the parameter

Returns:

the index of the requested parameter in the list of optimized parameters

Return type:

int

Raises:

ValueError – if the given parameter could not be found as an estimable parameter.

get_parameter_estimable_index_by_name(model_param_name)

Get the index of this parameter in the parameters list

This returns the position of this parameter in the ‘x’, parameter vector in the CL kernels.

Parameters:model_param_name (str) – the model parameter name Returns:the index of the requested parameter in the list of optimized parameters Return type:int Raises:ValueError – if the given parameter could not be found as an estimable parameter.

get_parameter_value(parameter_name)

Get the parameter value for the given parameter. This is regardless of model fixation.

Returns:the value for the given parameter Return type:float or ndarray

get_protocol_parameter_by_name(protocol_name)

Get the first instance of a protocol parameter that matches the given name.

Parameters:protocol_name (str) – the protocol parameter name for which we want the corresponding parameter object. Returns:the parameter matching the protocol name Return type:ProtocolParameter

get_unique_protocol_parameters()

Gets the unique protocol parameters from the model listing.

This does not return the corresponding compartment model, only the parameters.

Returns:the list of protocol parameters Return type:List[ProtocolParameter]

get_value_fixed_parameters_list(exclude_priors=False)

Gets a list (as model, parameter tuples) of all parameters that are fixed to a value.

Parameters:exclude_priors (boolean) – if we want to exclude the parameters for the priors Returns:the list of value fixed parameters Return type:list of tuple

get_weights()

Get all the model functions/parameter tuples of the models that are a subclass of WeightType

Returns:the list of compartment models that are a subclass of WeightType as (model, parameter) tuples. Return type:list

has_parameter(model_param_name)

Check to see if the given parameter is defined in this model.

Parameters:model_param_name (string) – A model.param name like ‘Ball.d’ Returns:true if the parameter is defined in this model, false otherwise. Return type:boolean

has_protocol_parameter(parameter_name)

Check if the model has the given protocol parameter defined.

Parameters:parameter_name (str) – the protocol parameter name. Returns:true if the given protocol parameter is defined in the model. Return type:boolean

is_fixed(parameter_name)

Check if the given (free) parameter is fixed or not (either to a value or to a dependency).

Parameters:parameter_name (str) – the name of the parameter to check if it is fixed, in dot format. Returns:if the parameter is fixed or not (can be fixed to a value or dependency). Return type:boolean

is_fixed_to_dependency(model, param)

Check if the given model and parameter name combo has a dependency.

Parameters:

• model (mdt.model_building.model_functions.ModelCLFunction) – the model function
• param (mot.cl_parameter.CLFunctionParameter) – the parameter

Returns:

if the given parameter has a dependency

Return type:

boolean

is_fixed_to_value(parameter_name)

Check if the given (free) parameter is fixed to a value.

Parameters:parameter_name (str) – the name of the parameter to check if it is fixed, in dot format. Returns:if the parameter is fixed to a value or not Return type:boolean

is_parameter_estimable(model, param)

Check if the given model parameter is estimable.

A parameter is estimable if it is of the Free parameter type and is not fixed.

Parameters:

• model (mdt.model_building.model_functions.ModelCLFunction) – the model function
• param (mot.cl_parameter.CLFunctionParameter) – the parameter

Returns:

true if the parameter is estimable, false otherwise

Return type:

boolean

set_parameter_value(parameter_name, value)

Set the value we will use for the given parameter.

If the parameter is a fixed free parameter we will set the fixed value to the given value.

Parameters:

• parameter_name (string) – A model.param name like ‘Ball.d’
• value (scalar or vector or string or AbstractParameterDependency) – The value or dependency to fix the given parameter to. Dependency objects and strings are only value for fixed free parameters.

unfix(parameter_name)

Unfix the indicated parameter

Parameters:parameter_name (str) – the name of the parameter to fix or unfix

class mdt.models.composite.ProtocolAdaptionCallbacks

Bases: object

Information container for the protocol adaption callbacks.

During model evaluation, it may be necessary to apply a transformation on some or all of the protocol inputs. For example, this allows loading the gradient deviations as a matrix that transforms the gradient vector just prior to model evaluation. The alternative would be to load the transformed protocol parameters directly as protocol values, which can be costly, hence these callback functions.

get_callback_function()

Get the CL callback function we will execute just prior model evaluation.

The parameters of this callback function should be as follows. First the list of protocol parameter names, second the list of kernel input data elements and finally an uint for the current observation index.

Returns:the CL function we will use Return type:CLFunction

get_kernel_input_data()

Get the additional kernel input data needed for this proposal callback to work.

Returns:additional kernel input data Return type:Dict[str, KernelData]

get_protocol_parameter_names()

Get the names of the protocol parameters need for this proposal adaption callback.

Returns:the list of protocol parameters needed Return type:List[str]

class mdt.models.composite.SamplingPostProcessingData(samples, param_names, fixed_parameters)

Bases: collections.abc.Mapping

Stores the sample output for use in the model defined post-processing routines.

In general, this class acts as a dictionary with as keys the parameter names (as <compartment>.<parameter>). Each value may be a scalar, a 1d map or a 2d set of samples. Additional object attributes can also be used by the post-processing routines.

Parameters:

• samples (ndarray) – a matrix of shape (d, p, n) with d problems, p parameters and n samples
• param_names (list of str) – the list containing the names of the parameters in the samples array
• fixed_parameters (dict) – for every fixed parameter the fixed values (either a scalar or a map).

fixed_parameters

Get the dictionary with all the fixed parameter values.

Returns:the names and values of the fixed parameters Return type:dict

sampled_parameter_names

Get the names of the parameters that have been sampled.

Returns:the names of the parameters in the samples. Return type:list of str

samples

Get the array of samples as returned by the sample routine.

For the names of the corresponding parameters, please see sampled_parameter_names.

Returns:a matrix of shape (d, p, n) with d problems, p parameters and n samples. Return type:ndarray

mdt.models.composite.calculate_dependent_parameters(kernel_data, estimated_parameters_list, parameters_listing, dependent_parameter_names, cl_runtime_info=None)

Calculate the dependent parameters

Some of the models may contain parameter dependencies. We would like to return the maps for these parameters as well as all the other maps. Since the dependencies are specified in CL, we have to recourse to CL to calculate these maps.

This uses the calculated parameters in the results dictionary to run the parameters_listing in CL to obtain the maps for the dependent parameters.

Parameters:

• (dict[str (kernel_data) – mot.lib.utils.KernelData]): the list of additional data to load
• estimated_parameters_list (list of ndarray) – The list with the one-dimensional ndarray of estimated parameters
• parameters_listing (str) – The parameters listing in CL
• dependent_parameter_names (list of list of str) – Per parameter we would like to obtain the CL name and the result map name. For example: ((‘Wball_w’, ‘Wball.w’),)
• cl_runtime_info (mot.configuration.CLRuntimeInfo) – the runtime information

Returns:

A dictionary with the calculated maps for the dependent parameters.

Return type:

dict

Module contents