mdt.models package¶
Submodules¶
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. Return type: 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. Return type: mot.lib.cl_function.CLFunction
-
get_free_param_names
()[source]¶ Get the names of the free parameters.
Returns: the name of the free parameters Return type: 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). Return type: 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. 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
()[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 Return type: 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 Return type: 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 Return type: 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.
Return type: 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 Return type: 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 Return type: int
-
get_nmr_parameters
()[source]¶ Get the number of estimable parameters in this model.
Returns: the number of estimable parameters Return type: 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. Return type: 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.
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)[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
Returns: a dictionary with for every subdirectory the maps to save
Return type: 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). Return type: 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 Return type: 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 Return type: 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.
Return type: 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. 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)[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. 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)[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: 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
oroptimization
. - settings (dict) – the items to set in the post-processing information
- processing_type (str) – one of
-
-
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.
NamedProtocolProblem
(model_protocol_problem, model_name)[source]¶ 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)[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]¶ Bases:
mdt.model_building.model_functions.ModelCLFunction
-
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.
Return type: 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’ Returns: the cache structure Return type: 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.
Return type: None or mot.optimize.base.ConstraintFunction
-
-
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]¶ 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
-
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.
Return type: 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’ Returns: the cache structure Return type: 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.
Return type: 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 Return type: 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 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)[source]¶ 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
()[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.
Return type: 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’ Returns: the cache structure Return type: 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.
Return type: 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 Return type: 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 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)[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
-
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’.
Return type: list of tuples
-
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]¶ 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)[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.
Returns: for each voxel (first dimension ) a covariance matrix (second dimension)
Return type: 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: 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. Return type: 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 Return type: CompositeModelFunction
-
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 Return type: 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. Return type: mot.lib.cl_function.CLFunction
-
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). Return type: ndarray
-
get_input_data
()[source]¶ 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)[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. 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
()[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 Return type: mot.lib.kernel_data.KernelData
-
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.
Return type: 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
andmdt.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_nmr_observations
()[source]¶ Get the number of observations in the data.
Returns: the number of observations present in the data Return type: int
-
get_nmr_parameters
()[source]¶ Get the number of estimable parameters in this model.
Returns: the number of estimable parameters Return type: 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. Return type: 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
Returns: a dictionary with for every subdirectory the maps to save
Return type: 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). Return type: 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 Return type: 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 Return type: 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 Return type: 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.
Return type: 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. Returns: the list of volume indices with volumes to use. This indexes the input data. Return type: 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’ Returns: true if the parameter is defined in this model, false otherwise. Return type: 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: 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. 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_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 (<model>.<param>) 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: 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: 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: 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: 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: 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: 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
oroptimization
. - settings (dict) – the items to set in the post-processing information
- processing_type (str) – one of
-
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 Returns: same as the current class but then with updated results Return type: 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 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)[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 Return type: 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 Return type: 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 Returns: the list of value fixed parameters Return type: 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 Returns: the list of estimable parameters Return type: 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 Return type: 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 Returns: the list of tuples containing (model, parameters) Return type: list of tuple
-
get_model_list
()[source]¶ 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)[source]¶ 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
()[source]¶ 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
()[source]¶ 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)[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
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)[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 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)[source]¶ 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)[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. Returns: the parameter matching the protocol name Return type: 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 Return type: 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 Returns: the list of value fixed parameters Return type: 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. Return type: 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’ Returns: true if the parameter is defined in this model, false otherwise. Return type: 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. Returns: true if the given protocol parameter is defined in the model. Return type: 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. 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)[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
Returns: if the given parameter has a dependency
Return type: 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. Returns: if the parameter is fixed to a value or not Return type: 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
Returns: true if the parameter is estimable, false otherwise
Return type: 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.
-
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 Return type: CLFunction
-
-
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 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)[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
Returns: A dictionary with the calculated maps for the dependent parameters.
Return type: dict