mdt.model_building.parameter_functions package

Submodules

mdt.model_building.parameter_functions.dependencies module

class mdt.model_building.parameter_functions.dependencies.AbstractParameterDependency

Bases: object

assignment_code

Get the assignment code (including a ;).

Returns:The assignment code. Return type:str

pre_transform_code

Some code that may be prefixed to this parameter dependency.

Here one can put more elaborate CL code. Please make sure that additional variables are unique.

Returns:The pre transformation code. This is prepended to the dependency function. Return type:str

class mdt.model_building.parameter_functions.dependencies.SimpleAssignment(assignment_code)

Bases: mdt.model_building.parameter_functions.dependencies.AbstractParameterDependency

Adds a simple parameter dependency rule for the given parameter.

This is for one parameter, a simple one-line transformation dependency.

Parameters:assignment_code (str) – the assignment code (in CL) for this parameter

assignment_code

Get the assignment code (including a ;).

Returns:The assignment code. Return type:str

mdt.model_building.parameter_functions.numdiff_info module

class mdt.model_building.parameter_functions.numdiff_info.NumDiffInfo

Bases: object

Encapsulates information necessary for numerical differentiation of a parameter.

max_step

Get the maximum numerical differentiation step size for this parameter.

Returns:the maximum step size for the parameter Return type:float

scaling_factor

A scaling factor for the parameter to ensure that it’s magnitude is close to unitary.

This should return a value such that when a parameter is scaled with this value, the value is close to unitary.

Returns:a scaling factor to use for the parameter Return type:float

use_bounds

If we should use the boundary conditions for this parameter when calculating a derivative.

This is typically set to True unless we are dealing with circular parameters.

Returns:

if we need to use the lower and upper bounds (defined in the parameter) when calculating

the derivatives for this model.

Return type:boolean

class mdt.model_building.parameter_functions.numdiff_info.SimpleNumDiffInfo(max_step=0.1, scale_factor=1, use_bounds=True, use_lower_bound=True, use_upper_bound=True)

Bases: mdt.model_building.parameter_functions.numdiff_info.NumDiffInfo

A basic implementation of the numerical differentiation info for a parameter.

Parameters:

• max_step (float) – the numerical differentiation step size
• scale_factor (float) – a scaling factor to rescale the parameter a unitary range
• use_bounds (boolean) – if we need to use the boundary condition for this parameter
• use_lower_bound (boolean) – if we are using bounds, if we are using the lower bound
• use_upper_bound (boolean) – if we are using bounds, if we are using the upper bound

max_step

Get the maximum numerical differentiation step size for this parameter.

Returns:the maximum step size for the parameter Return type:float

scaling_factor

A scaling factor for the parameter to ensure that it’s magnitude is close to unitary.

This should return a value such that when a parameter is scaled with this value, the value is close to unitary.

Returns:a scaling factor to use for the parameter Return type:float

use_bounds

If we should use the boundary conditions for this parameter when calculating a derivative.

This is typically set to True unless we are dealing with circular parameters.

Returns:

if we need to use the lower and upper bounds (defined in the parameter) when calculating

the derivatives for this model.

Return type:boolean

use_lower_bound

use_upper_bound

mdt.model_building.parameter_functions.priors module

class mdt.model_building.parameter_functions.priors.ARDBeta

Bases: mdt.model_building.parameter_functions.priors.SimpleParameterPrior

This is a collapsed form of the Beta PDF meant for use in Automatic Relevance Detection sampling.

In this prior the alpha parameter of the Beta prior is set to 1 which simplifies the equation. The parameter beta is still free and can be changed as desired.

The implemented prior is:

\[B(x; 1, \beta) = \beta * (1 - x)^{\beta - 1}\]

class mdt.model_building.parameter_functions.priors.ARDGaussian

Bases: mdt.model_building.parameter_functions.priors.SimpleParameterPrior

This is a Gaussian prior meant for use in Automatic Relevance Detection sampling.

This uses a Gaussian prior with mean at zero and a standard deviation determined by the alpha parameter with the relationship \(\sigma = 1/\sqrt(\alpha)\).

class mdt.model_building.parameter_functions.priors.AbsSinHalfPrior

Bases: mdt.model_building.parameter_functions.priors.SimpleParameterPrior

Angular prior: \(P(v) = |\sin(x)/2.0|\)

class mdt.model_building.parameter_functions.priors.AbsSinPrior

Bases: mdt.model_building.parameter_functions.priors.SimpleParameterPrior

Angular prior: \(P(v) = |\sin(v)|\)

class mdt.model_building.parameter_functions.priors.AlwaysOne

Bases: mdt.model_building.parameter_functions.priors.SimpleParameterPrior

The uniform prior is always 1. \(P(v) = 1\)

class mdt.model_building.parameter_functions.priors.AxialNormalPDF

Bases: mdt.model_building.parameter_functions.priors.SimpleParameterPrior

The axial normal PDF is a Normal distribution wrapped around 0 and \(\pi\).

It’s PDF is given by:

\[f(\theta; a, b) = \frac{\cosh(a\sin \theta + b\cos \theta)}{\pi I_{0}(\sqrt{a^{2} + b^{2}})}\]

where in this implementation \(a\) and \(b\) are parameterized with the input variables \(\mu\) and \(\sigma\) using:

\[\begin{split}\begin{align*} \kappa &= \frac{1}{\sigma^{2}} \\ a &= \kappa * \sin \mu \\ b &= \kappa * \cos \mu \end{align*}\end{split}\]

References

Barry C. Arnold, Ashis SenGupta (2006). Probability continuous_distributions and statistical inference for axial data. Environmental and Ecological Statistics, volume 13, issue 3, pages 271-285.

class mdt.model_building.parameter_functions.priors.NormalPDF

Bases: mdt.model_building.parameter_functions.priors.SimpleParameterPrior

Normal PDF on the given value: \(P(v) = N(v; \mu, \sigma)\)

class mdt.model_building.parameter_functions.priors.ParameterPrior(*args, **kw)

Bases: MockClass

The priors are used during model sample, indicating the a priori information one has about a parameter.

These priors are not in log space, we take the log in the model builder.

The signature of prior parameters must be:

get_extra_parameters()

Get the additional prior specific parameters.

Each prior has at least 3 parameters, the value, lower bound and upper bound, but it can have more parameters.

Returns:list of additional parameters Return type:list

class mdt.model_building.parameter_functions.priors.ReciprocalPrior

Bases: mdt.model_building.parameter_functions.priors.SimpleParameterPrior

The reciprocal of the current value. \(P(v) = 1/v\)

class mdt.model_building.parameter_functions.priors.SimpleParameterPrior(prior_name, prior_body, extra_params=None, dependencies=())

Bases: mdt.model_building.parameter_functions.priors.ParameterPrior, MockClass

A prior template function.

This will prepend to the given extra parameters the obligatory parameters (value, lower_bound, upper_bound).

Parameters:

• prior_name (str) – the name of this prior function
• prior_body (str) – the body of the prior
• extra_params (list) – additional parameters for this prior
• dependencies (list or tuple) – the list of dependency functions

get_extra_parameters()

Get the additional prior specific parameters.

Each prior has at least 3 parameters, the value, lower bound and upper bound, but it can have more parameters.

Returns:list of additional parameters Return type:list

class mdt.model_building.parameter_functions.priors.UniformWithinBoundsPrior

Bases: mdt.model_building.parameter_functions.priors.SimpleParameterPrior

This prior is 1 within the upper and lower bound of the parameter, 0 outside.

class mdt.model_building.parameter_functions.priors.VagueGammaPrior

Bases: mdt.model_building.parameter_functions.priors.SimpleParameterPrior

The vague gamma prior is meant as a proper uniform prior.

Lee & Wagenmakers:

The practice of assigning Gamma(0.001, 0.001) priors on precision parameters is theoretically motivated by scale invariance arguments, meaning that priors are chosen so that changing the measurement scale of the data does not affect inference. The invariant prior on precision lambda corresponds to a uniform distribution on log sigma, that is, rho(sigma^2) prop. to. 1/sigma^2, or a Gamma(a -> 0, b -> 0) distribution. This invariant prior distribution, however, is improper (i.e., the area under the curve is unbounded), which means it is not really a distribution, but the limit of a sequence of continuous_distributions (see Jaynes, 2003). WinBUGS requires the use of proper continuous_distributions, and the Gamma(0.001, 0.001) prior is intended as a proper approximation to the theoretically motivated improper prior. This raises the issue of whether inference is sensitive to the essentially arbitrary value 0.001, and it is sometimes the case that using other small values such as 0.01 or 0.1 leads to more stable sample in WinBUGS.

—Lee & Wagenmakers, Bayesian Cognitive Modeling, 2014, Chapter 4, Box 4.1

While this is not WinBUGS and improper priors are allowed in MOT, it is still useful to have this prior in case people desire proper priors.

mdt.model_building.parameter_functions.transformations module

class mdt.model_building.parameter_functions.transformations.AbsModPiTransform

Bases: mdt.model_building.parameter_functions.transformations.AbsModXTransform

class mdt.model_building.parameter_functions.transformations.AbsModTwoPiTransform

Bases: mdt.model_building.parameter_functions.transformations.AbsModXTransform

class mdt.model_building.parameter_functions.transformations.AbsModXTransform(x_cl, x_python)

Bases: mdt.model_building.parameter_functions.transformations.AbstractTransformation

Create an transformation that returns the absolute modulo x value of the input.

encode_bounds(lower_bounds, upper_bounds)

Encode the given bounds into the encoded parameter space.

Parameters:

• lower_bounds (floar or ndarray) – either a single bound, or per voxel a bound
• upper_bounds (floar or ndarray) – either a single bound, or per voxel a bound

Returns:

the transformed lower and upper bounds, same shape as inputs

Return type:

tuple

get_cl_decode()

Get the CL decode assignment constructor

Returns:The cl code assignment constructor for decoding the parameter. Return type:AssignmentConstructor

get_cl_encode()

Get the CL encode assignment constructor

Returns

AssignmentConstructor: The cl code assignment constructor for encoding the parameter.

class mdt.model_building.parameter_functions.transformations.AbstractTransformation

Bases: object

The transformations define the encode and decode operations needed to build a codec.

These objects define the transformation to and from model and optimization space.

encode_bounds(lower_bounds, upper_bounds)

Encode the given bounds into the encoded parameter space.

Parameters:

• lower_bounds (floar or ndarray) – either a single bound, or per voxel a bound
• upper_bounds (floar or ndarray) – either a single bound, or per voxel a bound

Returns:

the transformed lower and upper bounds, same shape as inputs

Return type:

tuple

get_cl_decode()

Get the CL decode assignment constructor

Returns:The cl code assignment constructor for decoding the parameter. Return type:AssignmentConstructor

get_cl_encode()

Get the CL encode assignment constructor

Returns

AssignmentConstructor: The cl code assignment constructor for encoding the parameter.

class mdt.model_building.parameter_functions.transformations.AssignmentConstructor

Bases: object

create_assignment(parameter_variable, lower_bound, upper_bound)

Create the assignment string.

Parameters:

• parameter_variable (str) – the name of the parameter variable holding the current value in the kernel
• lower_bound (str) – the value or the name of the variable holding the value for the lower bound
• upper_bound (str) – the value or the name of the variable holding the value for the upper bound

Returns:

the transformation assignment

Return type:

str

class mdt.model_building.parameter_functions.transformations.ClampTransform

Bases: mdt.model_building.parameter_functions.transformations.AbstractTransformation

The clamp transformation limits the parameter between its lower and upper bound using the clamp function.

encode_bounds(lower_bounds, upper_bounds)

Encode the given bounds into the encoded parameter space.

Parameters:

• lower_bounds (floar or ndarray) – either a single bound, or per voxel a bound
• upper_bounds (floar or ndarray) – either a single bound, or per voxel a bound

Returns:

the transformed lower and upper bounds, same shape as inputs

Return type:

tuple

get_cl_decode()

Get the CL decode assignment constructor

Returns:The cl code assignment constructor for decoding the parameter. Return type:AssignmentConstructor

get_cl_encode()

Get the CL encode assignment constructor

Returns

AssignmentConstructor: The cl code assignment constructor for encoding the parameter.

class mdt.model_building.parameter_functions.transformations.CosSqrClampTransform

Bases: mdt.model_building.parameter_functions.transformations.AbstractTransformation

The clamp transformation limits the parameter between its lower and upper bound using a cos(sqr()) transform.

encode_bounds(lower_bounds, upper_bounds)

Encode the given bounds into the encoded parameter space.

Parameters:

• lower_bounds (floar or ndarray) – either a single bound, or per voxel a bound
• upper_bounds (floar or ndarray) – either a single bound, or per voxel a bound

Returns:

the transformed lower and upper bounds, same shape as inputs

Return type:

tuple

get_cl_decode()

Get the CL decode assignment constructor

Returns:The cl code assignment constructor for decoding the parameter. Return type:AssignmentConstructor

get_cl_encode()

Get the CL encode assignment constructor

Returns

AssignmentConstructor: The cl code assignment constructor for encoding the parameter.

class mdt.model_building.parameter_functions.transformations.FormatAssignmentConstructor(assignment)

Bases: mdt.model_building.parameter_functions.transformations.AssignmentConstructor

Assignment constructor that formats the given assignment template.

This expects that the assignment string has elements like:

• {parameter_variable}: for the parameter variable
• {lower_bound}: for the lower bound
• {upper_bound}: for the upper bound

Parameters:assignment (str) – the string containing the assignment template.

create_assignment(parameter_variable, lower_bound, upper_bound)

Create the assignment string.

Parameters:

• parameter_variable (str) – the name of the parameter variable holding the current value in the kernel
• lower_bound (str) – the value or the name of the variable holding the value for the lower bound
• upper_bound (str) – the value or the name of the variable holding the value for the upper bound

Returns:

the transformation assignment

Return type:

str

class mdt.model_building.parameter_functions.transformations.IdentityTransform

Bases: mdt.model_building.parameter_functions.transformations.AbstractTransformation

The identity transform does no transformation and returns the input given.

encode_bounds(lower_bounds, upper_bounds)

Encode the given bounds into the encoded parameter space.

Parameters:

• lower_bounds (floar or ndarray) – either a single bound, or per voxel a bound
• upper_bounds (floar or ndarray) – either a single bound, or per voxel a bound

Returns:

the transformed lower and upper bounds, same shape as inputs

Return type:

tuple

get_cl_decode()

Get the CL decode assignment constructor

Returns:The cl code assignment constructor for decoding the parameter. Return type:AssignmentConstructor

get_cl_encode()

Get the CL encode assignment constructor

Returns

AssignmentConstructor: The cl code assignment constructor for encoding the parameter.

class mdt.model_building.parameter_functions.transformations.PositivityTransform

Bases: mdt.model_building.parameter_functions.transformations.AbstractTransformation

Restrain the parameter to the positive values, i.e. returns max(x, 0).

encode_bounds(lower_bounds, upper_bounds)

Encode the given bounds into the encoded parameter space.

Parameters:

• lower_bounds (floar or ndarray) – either a single bound, or per voxel a bound
• upper_bounds (floar or ndarray) – either a single bound, or per voxel a bound

Returns:

the transformed lower and upper bounds, same shape as inputs

Return type:

tuple

get_cl_decode()

Get the CL decode assignment constructor

Returns:The cl code assignment constructor for decoding the parameter. Return type:AssignmentConstructor

get_cl_encode()

Get the CL encode assignment constructor

Returns

AssignmentConstructor: The cl code assignment constructor for encoding the parameter.

class mdt.model_building.parameter_functions.transformations.ScaleClampTransform(scale)

Bases: mdt.model_building.parameter_functions.transformations.AbstractTransformation

Clamps the value to the given bounds and applies a scaling to bring the parameters in sensible ranges.

To encode, the parameter value is multiplied by the scaling factor. To decode, it is divided by the scaling factor.

Parameters:scale (float) – the scaling factor by which to scale the parameter

encode_bounds(lower_bounds, upper_bounds)

Encode the given bounds into the encoded parameter space.

Parameters:

• lower_bounds (floar or ndarray) – either a single bound, or per voxel a bound
• upper_bounds (floar or ndarray) – either a single bound, or per voxel a bound

Returns:

the transformed lower and upper bounds, same shape as inputs

Return type:

tuple

get_cl_decode()

Get the CL decode assignment constructor

Returns:The cl code assignment constructor for decoding the parameter. Return type:AssignmentConstructor

get_cl_encode()

Get the CL encode assignment constructor

Returns

AssignmentConstructor: The cl code assignment constructor for encoding the parameter.

class mdt.model_building.parameter_functions.transformations.ScaleTransform(scale)

Bases: mdt.model_building.parameter_functions.transformations.AbstractTransformation

Applies a scaling to bring the parameters in sensible ranges.

To encode, the parameter value is multiplied by the scaling factor. To decode, it is divided by the scaling factor.

Parameters:scale (float) – the scaling factor by which to scale the parameter

encode_bounds(lower_bounds, upper_bounds)

Encode the given bounds into the encoded parameter space.

Parameters:

• lower_bounds (floar or ndarray) – either a single bound, or per voxel a bound
• upper_bounds (floar or ndarray) – either a single bound, or per voxel a bound

Returns:

the transformed lower and upper bounds, same shape as inputs

Return type:

tuple

get_cl_decode()

Get the CL decode assignment constructor

Returns:The cl code assignment constructor for decoding the parameter. Return type:AssignmentConstructor

get_cl_encode()

Get the CL encode assignment constructor

Returns

AssignmentConstructor: The cl code assignment constructor for encoding the parameter.

class mdt.model_building.parameter_functions.transformations.SinSqrClampTransform

Bases: mdt.model_building.parameter_functions.transformations.AbstractTransformation

The clamp transformation limits the parameter between its lower and upper bound using a sin(sqr()) transform.

encode_bounds(lower_bounds, upper_bounds)

Encode the given bounds into the encoded parameter space.

Parameters:

• lower_bounds (floar or ndarray) – either a single bound, or per voxel a bound
• upper_bounds (floar or ndarray) – either a single bound, or per voxel a bound

Returns:

the transformed lower and upper bounds, same shape as inputs

Return type:

tuple

get_cl_decode()

Get the CL decode assignment constructor

Returns:The cl code assignment constructor for decoding the parameter. Return type:AssignmentConstructor

get_cl_encode()

Get the CL encode assignment constructor

Returns

AssignmentConstructor: The cl code assignment constructor for encoding the parameter.

class mdt.model_building.parameter_functions.transformations.SqrClampTransform

Bases: mdt.model_building.parameter_functions.transformations.AbstractTransformation

The clamp transformation limits the parameter between its lower and upper bound using a sqr() transform.

encode_bounds(lower_bounds, upper_bounds)

Encode the given bounds into the encoded parameter space.

Parameters:

• lower_bounds (floar or ndarray) – either a single bound, or per voxel a bound
• upper_bounds (floar or ndarray) – either a single bound, or per voxel a bound

Returns:

the transformed lower and upper bounds, same shape as inputs

Return type:

tuple

get_cl_decode()

Get the CL decode assignment constructor

Returns:The cl code assignment constructor for decoding the parameter. Return type:AssignmentConstructor

get_cl_encode()

Get the CL encode assignment constructor

Returns

AssignmentConstructor: The cl code assignment constructor for encoding the parameter.

Module contents