# mdt.models package¶

## mdt.models.base module¶

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

Bases: object

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

get_constraints_function()[source]

The function for the (inequality) constraints.

Returns: the CL function for the inequality constraints of this model. mot.lib.cl_function.CLFunction
get_finalize_proposal_function()[source]

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. mot.lib.cl_function.CLFunction
get_free_param_names()[source]

Get the names of the free parameters.

Returns: the name of the free parameters List
get_initial_parameters()[source]

Get the initial parameters for each of the voxels.

Returns: 2d array with for every problem (first dimension) the initial parameters (second dimension). ndarray
get_input_data_problems(input_data=None)[source]

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. A list of InputDataProblem instances or subclasses of that baseclass. These objects indicate the problems with the protocol and this model. list of InputDataProblem
get_kernel_data()[source]

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 mot.lib.kernel_data.KernelData
get_log_likelihood_function()[source]

For sampling, get the log-likelihood function.

Returns: the CL function for the log likelihood function during MCMC sampling mot.lib.cl_function.CLFunction
get_log_prior_function()[source]

Get the prior function used during sampling.

Returns: the CL function for the log prior function during MCMC sampling mot.lib.cl_function.CLFunction
get_lower_bounds()[source]

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. List
get_mle_codec()[source]

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 mdt.model_building.utils.ParameterCodec
get_nmr_observations()[source]

Get the number of observations in the data.

Returns: the number of observations present in the data int
get_nmr_parameters()[source]

Get the number of estimable parameters in this model.

Returns: the number of estimable parameters int
get_objective_function()[source]

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

Returns: the CL function for the optimization routines in MOT. mot.lib.cl_function.CLFunction
get_post_optimization_output(optimized_parameters, roi_indices=None, parameters_dict=None)[source]

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. dictionary with results maps, can be nested which should translate to sub-directories. dict
get_post_sampling_maps(sampling_output, roi_indices=None)[source]

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 a dictionary with for every subdirectory the maps to save dict
get_random_parameter_positions(nmr_positions=1)[source]

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). ndarray
get_rwm_epsilons()[source]

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 list
get_rwm_proposal_stds()[source]

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 ndarray
get_upper_bounds()[source]

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. List
get_used_volumes(input_data=None)[source]

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. the list of volume indices with volumes to use. This indexes the input data. List
is_input_data_sufficient(input_data=None)[source]

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. True if there is enough information in the input data, false otherwise. boolean
name

The name of this model.

Returns: the name of this model. str
set_input_data(input_data, suppress_warnings=False)[source]

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 self for chainability
update_active_post_processing(processing_type, settings)[source]

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[source]

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)[source]
class mdt.models.base.NamedProtocolProblem(model_protocol_problem, model_name)[source]

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)[source]

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)[source]
get_cache_init_function()[source]

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. None or mot.lib.cl_function.CLFunction
get_cache_struct(address_space)[source]

Get the cache data for this compartment model.

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

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. None or mot.optimize.base.ConstraintFunction
get_extra_optimization_maps_funcs()[source]

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

Returns: the list of functions to be called list of functions
get_extra_sampling_maps_funcs()[source]

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 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)[source]

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)[source]
get_cache_init_function()[source]

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. None or mot.lib.cl_function.CLFunction
get_cache_struct(address_space)[source]

Get the cache data for this compartment model.

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

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. None or mot.optimize.base.ConstraintFunction
get_extra_optimization_maps_funcs()[source]

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

Returns: the list of functions to be called list of functions
get_extra_sampling_maps_funcs()[source]

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 list of functions
name

Get the name of this model function.

Returns: The name of this model function. str
class mdt.models.compartments.WeightCompartment(return_type, cl_function_name, parameters, cl_body, dependencies=None, model_function_priors=None, nickname=None)[source]

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()[source]

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. None or mot.lib.cl_function.CLFunction
get_cache_struct(address_space)[source]

Get the cache data for this compartment model.

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

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. None or mot.optimize.base.ConstraintFunction
get_extra_optimization_maps_funcs()[source]

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

Returns: the list of functions to be called list of functions
get_extra_sampling_maps_funcs()[source]

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 list of functions
name

Get the name of this model function.

Returns: The name of this model function. str

## mdt.models.composite module¶

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

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)[source]
get_model_function_parameters()[source]

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’. list of tuples
get_model_parameter_list()[source]

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. 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)[source]

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)[source]

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. for each voxel (first dimension ) a covariance matrix (second dimension) ndarray
fix(model_param_name, value)[source]

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 self for chainability
get_active_post_processing()[source]

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. dict
get_composite_model_function()[source]

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 CompositeModelFunction
get_constraints_function()[source]

The function for the (inequality) constraints.

get_covariance_output_names()[source]

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 List[str]
get_finalize_proposal_function()[source]

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. mot.lib.cl_function.CLFunction
get_free_param_names()[source]

Get the names of the free parameters

get_initial_parameters()[source]

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). ndarray
get_input_data()[source]

Get the input data actually being used by this model.

Returns: the input data being used by this model mdt.lib.input_data.MRIInputData
get_input_data_problems(input_data=None)[source]

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. A list of InputDataProblem instances or subclasses of that baseclass. These objects indicate the problems with the protocol and this model. list of InputDataProblem
get_kernel_data()[source]

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 mot.lib.kernel_data.KernelData
get_log_likelihood_function()[source]

For sampling, get the log-likelihood function.

get_log_prior_function()[source]

Get the prior function used during sampling.

get_lower_bounds()[source]

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. List
get_mle_codec()[source]

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 mdt.model_building.utils.ParameterCodec
get_model_eval_function()[source]
get_nmr_observations()[source]

Get the number of observations in the data.

Returns: the number of observations present in the data int
get_nmr_parameters()[source]

Get the number of estimable parameters in this model.

Returns: the number of estimable parameters int
get_objective_function()[source]

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

get_post_optimization_output(optimized_parameters, roi_indices=None, parameters_dict=None)[source]

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. dict
get_post_sampling_maps(sampling_output, roi_indices=None)[source]

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 a dictionary with for every subdirectory the maps to save dict
get_random_parameter_positions(nmr_positions=1)[source]

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). ndarray
get_required_protocol_names()[source]

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 list
get_rwm_epsilons()[source]

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 list
get_rwm_proposal_stds()[source]

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 ndarray
get_upper_bounds()[source]

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. List
get_used_volumes(input_data=None)[source]

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. the list of volume indices with volumes to use. This indexes the input data. List
has_parameter(model_param_name)[source]

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

Parameters: model_param_name (string) – A model.param name like ‘Ball.d’ true if the parameter is defined in this model, false otherwise. boolean
init(model_param_name, value)[source]

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 self for chainability
is_input_data_sufficient(input_data=None)[source]

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. True if there is enough information in the input data, false otherwise. boolean
name

The name of this model.

Returns: the name of this model. str
param_dict_to_array(volume_dict)[source]
set_initial_parameters(initial_params)[source]

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 (.) and as values numbers or arrays to be used as starting point
set_input_data(input_data, suppress_warnings=False)[source]

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 self for chainability
set_lower_bound(model_param_name, value)[source]

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 self for chainability
set_lower_bounds(lower_bounds)[source]

Apply multiple lower bounds from a dictionary.

Parameters: lower_bounds (dict) – per parameter a lower bound Returns self for chainability
set_upper_bound(model_param_name, value)[source]

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 self for chainability
set_upper_bounds(upper_bounds)[source]

Apply multiple upper bounds from a dictionary.

Parameters: upper_bounds (dict) – per parameter a upper bound Returns self for chainability
unfix(model_param_name)[source]

Unfix the given model.param

Parameters: model_param_name (string) – A model.param name like ‘Ball.d’ Returns self for chainability
update_active_post_processing(processing_type, settings)[source]

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)[source]

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)[source]

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 same as the current class but then with updated results ExtraOptimizationMapsInfo
get_input_data(parameter_name)[source]

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 either a scalar, a vector or a matrix with values for the given parameter. float, ndarray or None 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)[source]

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)[source]

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()[source]

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

get_compartment_models()[source]

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

Returns: the compartment models in this composite model list of mdt.models.compartments.CompartmentModel
get_default_parameter_value(parameter_name)[source]

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 float or ndarray
get_dependency_fixed_parameters_list(exclude_priors=False)[source]

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 the list of value fixed parameters list of tuple
get_estimable_parameters_list(exclude_priors=False)[source]

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 the list of estimable parameters list of tuple
get_estimable_weights()[source]

Get all the estimable weights.

Returns: the list of compartment models/parameter pairs for models that are a subclass of WeightType list of tuples
get_free_parameters_list(exclude_priors=False)[source]

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 the list of tuples containing (model, parameters) list of tuple
get_model_list()[source]

Get the list of all the applicable model functions

Returns: the list of model functions. list of mdt.model_building.model_functions.ModelCLFunction
get_model_parameter_by_name(parameter_name)[source]

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

Parameters: parameter_name (string) – the parameter name in dot format ., or in bar format _. If the bar format leads to ambiguous results, an exception will be raised. containing the (model, parameter) pair for the given parameter name tuple
get_model_parameter_list()[source]

Get a list of all model, parameter tuples.

Returns: the list of tuples containing (model, parameters) list of tuple
get_noise_std_param()[source]

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

Returns: the reference to the NoiseStdFreeParam of the likelihood model parameter
get_parameter_estimable_index(model, param)[source]

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 the index of the requested parameter in the list of optimized parameters int ValueError – if the given parameter could not be found as an estimable parameter.
get_parameter_estimable_index_by_name(model_param_name)[source]

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 the index of the requested parameter in the list of optimized parameters int ValueError – if the given parameter could not be found as an estimable parameter.
get_parameter_value(parameter_name)[source]

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

Returns: the value for the given parameter float or ndarray
get_protocol_parameter_by_name(protocol_name)[source]

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. the parameter matching the protocol name ProtocolParameter
get_unique_protocol_parameters()[source]

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 List[ProtocolParameter]
get_value_fixed_parameters_list(exclude_priors=False)[source]

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 the list of value fixed parameters list of tuple
get_weights()[source]

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. list
has_parameter(model_param_name)[source]

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

Parameters: model_param_name (string) – A model.param name like ‘Ball.d’ true if the parameter is defined in this model, false otherwise. boolean
has_protocol_parameter(parameter_name)[source]

Check if the model has the given protocol parameter defined.

Parameters: parameter_name (str) – the protocol parameter name. true if the given protocol parameter is defined in the model. boolean
is_fixed(parameter_name)[source]

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. if the parameter is fixed or not (can be fixed to a value or dependency). boolean
is_fixed_to_dependency(model, param)[source]

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 if the given parameter has a dependency boolean
is_fixed_to_value(parameter_name)[source]

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. if the parameter is fixed to a value or not boolean
is_parameter_estimable(model, param)[source]

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 true if the parameter is estimable, false otherwise boolean
set_parameter_value(parameter_name, value)[source]

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)[source]

Unfix the indicated parameter

Parameters: parameter_name (str) – the name of the parameter to fix or unfix
class mdt.models.composite.ProtocolAdaptionCallbacks[source]

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()[source]

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 CLFunction
get_kernel_input_data()[source]

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

Returns: additional kernel input data Dict[str, KernelData]
get_protocol_parameter_names()[source]

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

Returns: the list of protocol parameters needed List[str]
class mdt.models.composite.SamplingPostProcessingData(samples, param_names, fixed_parameters)[source]

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 dict
sampled_parameter_names

Get the names of the parameters that have been sampled.

Returns: the names of the parameters in the samples. 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. ndarray
mdt.models.composite.calculate_dependent_parameters(kernel_data, estimated_parameters_list, parameters_listing, dependent_parameter_names, cl_runtime_info=None)[source]

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 A dictionary with the calculated maps for the dependent parameters. dict