# mdt.model_building.parameter_functions package¶

## mdt.model_building.parameter_functions.dependencies module¶

class mdt.model_building.parameter_functions.dependencies.AbstractParameterDependency[source]

Bases: object

assignment_code

Get the assignment code (including a ;).

Returns: The assignment code. 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. str
class mdt.model_building.parameter_functions.dependencies.SimpleAssignment(assignment_code)[source]

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. str

## mdt.model_building.parameter_functions.numdiff_info module¶

class mdt.model_building.parameter_functions.numdiff_info.NumDiffInfo[source]

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

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 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 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. boolean
use_lower_bound
use_upper_bound

## mdt.model_building.parameter_functions.priors module¶

class mdt.model_building.parameter_functions.priors.ARDBeta[source]

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

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

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

class mdt.model_building.parameter_functions.priors.AbsSinPrior[source]

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

class mdt.model_building.parameter_functions.priors.AlwaysOne[source]

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

class mdt.model_building.parameter_functions.priors.AxialNormalPDF[source]

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

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

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

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

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 list
class mdt.model_building.parameter_functions.priors.ReciprocalPrior[source]

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

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

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 list
class mdt.model_building.parameter_functions.priors.UniformWithinBoundsPrior[source]

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

class mdt.model_building.parameter_functions.priors.VagueGammaPrior[source]

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[source]
class mdt.model_building.parameter_functions.transformations.AbsModTwoPiTransform[source]
class mdt.model_building.parameter_functions.transformations.AbsModXTransform(x_cl, x_python)[source]

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

encode_bounds(lower_bounds, upper_bounds)[source]

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 the transformed lower and upper bounds, same shape as inputs tuple
get_cl_decode()[source]

Get the CL decode assignment constructor

Returns: The cl code assignment constructor for decoding the parameter. AssignmentConstructor
get_cl_encode()[source]

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

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

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 the transformed lower and upper bounds, same shape as inputs tuple
get_cl_decode()[source]

Get the CL decode assignment constructor

Returns: The cl code assignment constructor for decoding the parameter. AssignmentConstructor
get_cl_encode()[source]

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

Bases: object

create_assignment(parameter_variable, lower_bound, upper_bound)[source]

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 the transformation assignment str
class mdt.model_building.parameter_functions.transformations.ClampTransform[source]

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

encode_bounds(lower_bounds, upper_bounds)[source]

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 the transformed lower and upper bounds, same shape as inputs tuple
get_cl_decode()[source]

Get the CL decode assignment constructor

Returns: The cl code assignment constructor for decoding the parameter. AssignmentConstructor
get_cl_encode()[source]

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

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

encode_bounds(lower_bounds, upper_bounds)[source]

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 the transformed lower and upper bounds, same shape as inputs tuple
get_cl_decode()[source]

Get the CL decode assignment constructor

Returns: The cl code assignment constructor for decoding the parameter. AssignmentConstructor
get_cl_encode()[source]

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

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

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 the transformation assignment str
class mdt.model_building.parameter_functions.transformations.IdentityTransform[source]

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

encode_bounds(lower_bounds, upper_bounds)[source]

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 the transformed lower and upper bounds, same shape as inputs tuple
get_cl_decode()[source]

Get the CL decode assignment constructor

Returns: The cl code assignment constructor for decoding the parameter. AssignmentConstructor
get_cl_encode()[source]

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

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

encode_bounds(lower_bounds, upper_bounds)[source]

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 the transformed lower and upper bounds, same shape as inputs tuple
get_cl_decode()[source]

Get the CL decode assignment constructor

Returns: The cl code assignment constructor for decoding the parameter. AssignmentConstructor
get_cl_encode()[source]

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

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

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 the transformed lower and upper bounds, same shape as inputs tuple
get_cl_decode()[source]

Get the CL decode assignment constructor

Returns: The cl code assignment constructor for decoding the parameter. AssignmentConstructor
get_cl_encode()[source]

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

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

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 the transformed lower and upper bounds, same shape as inputs tuple
get_cl_decode()[source]

Get the CL decode assignment constructor

Returns: The cl code assignment constructor for decoding the parameter. AssignmentConstructor
get_cl_encode()[source]

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

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

encode_bounds(lower_bounds, upper_bounds)[source]

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 the transformed lower and upper bounds, same shape as inputs tuple
get_cl_decode()[source]

Get the CL decode assignment constructor

Returns: The cl code assignment constructor for decoding the parameter. AssignmentConstructor
get_cl_encode()[source]

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

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

encode_bounds(lower_bounds, upper_bounds)[source]

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 the transformed lower and upper bounds, same shape as inputs tuple
get_cl_decode()[source]

Get the CL decode assignment constructor

Returns: The cl code assignment constructor for decoding the parameter. AssignmentConstructor
get_cl_encode()[source]

Get the CL encode assignment constructor

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