Transformations

Transformation objects provide methods to transform between different representations of a parameter space; for example from a “model space” (\(p\)) where parameters have units and some physical counterpart to a “search space” (e.g. \(q = \log(p)\)) where parameters are non-dimensionalised and less-recognisable to the modeller. The transformed space may in many cases prove simpler to work with for inference: leading to more effective and efficient optimisation and sampling.

To perform optimisation or sampling in a transformed space, users can choose to write their pints.ForwardModel in “search space” directly, but the issue with this is that we will no longer be correctly inferring the “model parameters”. An alternative is to write the ForwardModel in model parameters, and pass a Transformation object to e.g. an OptimisationController or MCMCController. Using the Transformation object ensures users get the correct statistics about the model parameters (not the search space parameters).

Parameter transformation can be useful in many situations, for example transforming from a constrained parameter space to an unconstrained search space using RectangularBoundariesTransformation leads to crucial performance improvements for many methods.

Example:

transform = pints.LogTransformation(n_parameters)
mcmc = pints.MCMCController(log_posterior, n_chains, x0, transform=transform)

Transformation types:

• ComposedTransformation

• IdentityTransformation

• LogitTransformation

• LogTransformation

• RectangularBoundariesTransformation

• ScalingTransformation

• UnitCubeTransformation

Transformed classes:

• Transformation

• TransformedBoundaries

• TransformedErrorMeasure

• TransformedLogLikelihood

• TransformedLogPDF

• TransformedLogPrior

Transformation types

class pints.Transformation

Abstract base class for objects that provide transformations between two parameter spaces: the model parameter space and a search space.

If trans is an instance of a Transformation class, you can apply the transformation of a parameter vector from the model space p to the search space q by using q = trans.to_search(p) and the inverse by using p = trans.to_model(q).

References

[1] (1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16)

How to Obtain Those Nasty Standard Errors From Transformed Data. Erik Jorgensen and Asger Roer Pedersen. http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.47.9023

[2]

The Matrix Cookbook. Kaare Brandt Petersen and Michael Syskind Pedersen. 2012.

convert_boundaries(boundaries)

Returns a transformed pints.Boundaries object.

convert_covariance_matrix(C, q)

Converts a convariance matrix C from the model space to the search space around a parameter vector q provided in the search space.

The transformation is performed using a first order linear approximation [1] with the Jacobian \(\mathbf{J}\):

\[\begin{split}\mathbf{C}(\boldsymbol{q}) &= \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \mathbf{C}(\boldsymbol{p}) \left( \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \right)^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2) \\ &= \mathbf{J}^{-1}(\boldsymbol{q}) \mathbf{C}(\boldsymbol{p}) (\mathbf{J}^{-1}(\boldsymbol{q}))^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2).\end{split}\]

Using the property that \(\mathbf{J}^{-1} = \frac{d\boldsymbol{g}}{d\boldsymbol{p}}\), from the inverse function theorem, i.e. the matrix inverse of the Jacobian matrix of an invertible function is the Jacobian matrix of the inverse function.

convert_error_measure(error_measure)

Returns a transformed pints.ErrorMeasure.

convert_log_pdf(log_pdf)

Returns a transformed pints.LogPDF.

If log_pdf is a LogPrior, a TransformedLogPrior will be returned, which also transforms the output of the sample() method.

If log_pdf is a LogLikelihood, a TransformedLogLikelihood is returned, which is assumed to be invariant with respect to the transform (because it is a probability of the data, not the parameters). For all other types (including LogPrior) a non-invariant transform is used, see TransformedLogPDF for details.

convert_log_prior(log_prior)

Deprecated function: Use convert_log_pdf() instead.

convert_standard_deviation(s, q)

Converts standard deviation s, either a scalar or a vector, from the model space to the search space around a parameter vector q provided in the search space.

The transformation is performed using a first order linear approximation [1] with the Jacobian \(\mathbf{J}\):

\[\begin{split}\mathbf{C}(\boldsymbol{q}) &= \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \mathbf{C}(\boldsymbol{p}) \left( \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \right)^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2) \\ &= \mathbf{J}^{-1}(\boldsymbol{q}) \mathbf{C}(\boldsymbol{p}) (\mathbf{J}^{-1}(\boldsymbol{q}))^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2).\end{split}\]

Using the property that \(\mathbf{J}^{-1} = \frac{d\boldsymbol{g}}{d\boldsymbol{p}}\), from the inverse function theorem, i.e. the matrix inverse of the Jacobian matrix of an invertible function is the Jacobian matrix of the inverse function.

To transform the provided standard deviation \(\boldsymbol{s}\), we assume the covariance matrix \(\mathbf{C}(\boldsymbol{p})\) above is a diagonal matrix with \(\boldsymbol{s}^2\) on the diagonal, such that

\[s_i(\boldsymbol{q}) = \left( \mathbf{J}^{-1} (\mathbf{J}^{-1})^T \right)^{1/2}_{i, i} s_i(\boldsymbol{p}).\]

elementwise()

Returns True if the transformation is element-wise.

An element-wise transformation is a transformation \(\boldsymbol{f}\) that can be carried out element by element: for a parameter vector \(\boldsymbol{p}\) in the model space and a parameter vector \(\boldsymbol{q}\) in the search space, then it has

\[q_i = f(p_i),\]

where \(x_i\) denotes the \(i^{\text{th}}\) element of the vector \(\boldsymbol{x}\), as opposed to a transformation in which multiple elements are combined to create the transformed elements.

jacobian(q)

Returns the Jacobian matrix of the transformation calculated at the parameter vector q in the search space. For a transformation \(\boldsymbol{q} = \boldsymbol{f}(\boldsymbol{p})\), the Jacobian matrix is defined as

\[\mathbf{J} = \left[\frac{\partial \boldsymbol{f}^{-1}}{\partial q_1} \quad \frac{\partial \boldsymbol{f}^{-1}}{\partial q_2} \quad \cdots \right].\]

This is an optional method. It is needed when transformation of standard deviation Transformation.convert_standard_deviation() or covariance matrix Transformation.convert_covariance_matrix() is needed, or when evaluateS1() is needed.

jacobian_S1(q)

Computes the Jacobian matrix of the transformation calculated at the parameter vector q in the search space, and returns the result along with the partial derivatives of the result with respect to the parameters.

The returned data is a tuple (S, S') where S is a n_parameters by n_parameters matrix and S' is a sequence of n_parameters matrices.

This is an optional method. It is needed when the transformation is used along with a non-element-wise transformation in ComposedTransformation.

log_jacobian_det(q)

Returns the logarithm of the absolute value of the determinant of the Jacobian matrix of the transformation Transformation.jacobian() calculated at the parameter vector q in the search space.

The default implementation numerically calculates the determinant of the full matrix which only works if the optional method Transformation.jacobian() is implemented. If there is an analytic expression for the specific transformation, a reimplementation of this method may be preferred.

This is an optional method. It is needed when transformation is performed on LogPDF and/or that requires evaluateS1(); e.g. not necessary if it’s used for ErrorMeasure without ErrorMeasure.evaluateS1().

log_jacobian_det_S1(q)

Computes the logarithm of the absolute value of the determinant of the Jacobian, and returns the result plus the partial derivatives of the result with respect to the parameters.

The returned data is a tuple (S, S') where S is a scalar value and S' is a sequence of length n_parameters.

Note that the derivative returned is of the log of the determinant of the Jacobian, so S' = d/dq log(|det(J(q))|), evaluated at input.

The absolute value of the determinant of the Jacobian is provided by Transformation.log_jacobian_det(). The default implementation calculates the derivatives of the log-determinant using [2]

\[\frac{d}{dq} \log(|det(\mathbf{J})|) = trace(\mathbf{J}^{-1} \frac{d}{dq} \mathbf{J}),\]

where the derivative of the Jacobian matrix is provided by Transformation.jacobian_S1() and the matrix inversion is numerically calculated. If there is an analytic expression for the specific transformation, a reimplementation of this method may be preferred.

This is an optional method. It is needed when transformation is performed on LogPDF and that requires evaluateS1().

n_parameters()

Returns the dimension of the parameter space this transformation is defined over.

to_model(q)

Transforms a parameter vector q from the search space to the model space.

to_search(p)

Transforms a parameter vector p from the model space to the search space.

class pints.ComposedTransformation(*transformations)

N-dimensional Transformation composed of one or more other \(N_i\)-dimensional sub-transformations, so that \(\sum _i N_i = N\).

The dimensionality of the individual transformations does not have to be the same, i.e. \(N_i\neq N_j\) is allowed.

For example, a composed transformation:

t = pints.ComposedTransformation(
    transformation_1, transformation_2, transformation_3)

where transformation_1, transformation_2, and transformation_3 have dimension 1, 2 and 1 respectively, will have dimension N=4.

The evaluation and transformation of the composed transformations assume that the input transformations are all independent from each other.

The input parameters of the ComposedTransformation are ordered in the same way as the individual tranforms for the parameter vector. In the above example the transformation may be performed by t.to_search(p), where:

p = [parameter_1_for_transformation_1,
     parameter_1_for_transformation_2,
     parameter_2_for_transformation_2,
     parameter_1_for_transformation_3]

Extends Transformation.

convert_boundaries(boundaries)

Returns a transformed pints.Boundaries object.

convert_covariance_matrix(C, q)

Converts a convariance matrix C from the model space to the search space around a parameter vector q provided in the search space.

The transformation is performed using a first order linear approximation [1] with the Jacobian \(\mathbf{J}\):

\[\begin{split}\mathbf{C}(\boldsymbol{q}) &= \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \mathbf{C}(\boldsymbol{p}) \left( \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \right)^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2) \\ &= \mathbf{J}^{-1}(\boldsymbol{q}) \mathbf{C}(\boldsymbol{p}) (\mathbf{J}^{-1}(\boldsymbol{q}))^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2).\end{split}\]

Using the property that \(\mathbf{J}^{-1} = \frac{d\boldsymbol{g}}{d\boldsymbol{p}}\), from the inverse function theorem, i.e. the matrix inverse of the Jacobian matrix of an invertible function is the Jacobian matrix of the inverse function.

convert_error_measure(error_measure)

Returns a transformed pints.ErrorMeasure.

convert_log_pdf(log_pdf)

Returns a transformed pints.LogPDF.

If log_pdf is a LogPrior, a TransformedLogPrior will be returned, which also transforms the output of the sample() method.

If log_pdf is a LogLikelihood, a TransformedLogLikelihood is returned, which is assumed to be invariant with respect to the transform (because it is a probability of the data, not the parameters). For all other types (including LogPrior) a non-invariant transform is used, see TransformedLogPDF for details.

convert_log_prior(log_prior)

Deprecated function: Use convert_log_pdf() instead.

convert_standard_deviation(s, q)

Converts standard deviation s, either a scalar or a vector, from the model space to the search space around a parameter vector q provided in the search space.

The transformation is performed using a first order linear approximation [1] with the Jacobian \(\mathbf{J}\):

\[\begin{split}\mathbf{C}(\boldsymbol{q}) &= \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \mathbf{C}(\boldsymbol{p}) \left( \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \right)^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2) \\ &= \mathbf{J}^{-1}(\boldsymbol{q}) \mathbf{C}(\boldsymbol{p}) (\mathbf{J}^{-1}(\boldsymbol{q}))^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2).\end{split}\]

Using the property that \(\mathbf{J}^{-1} = \frac{d\boldsymbol{g}}{d\boldsymbol{p}}\), from the inverse function theorem, i.e. the matrix inverse of the Jacobian matrix of an invertible function is the Jacobian matrix of the inverse function.

To transform the provided standard deviation \(\boldsymbol{s}\), we assume the covariance matrix \(\mathbf{C}(\boldsymbol{p})\) above is a diagonal matrix with \(\boldsymbol{s}^2\) on the diagonal, such that

\[s_i(\boldsymbol{q}) = \left( \mathbf{J}^{-1} (\mathbf{J}^{-1})^T \right)^{1/2}_{i, i} s_i(\boldsymbol{p}).\]

elementwise()

See Transformation.elementwise().

jacobian(q)

See Transformation.jacobian().

jacobian_S1(q)

See Transformation.jacobian_S1().

log_jacobian_det(q)

See Transformation.log_jacobian_det().

log_jacobian_det_S1(q)

See Transformation.log_jacobian_det_S1().

n_parameters()

See Transformation.n_parameters().

to_model(q)

See Transformation.to_model().

to_search(p)

See Transformation.to_search().

class pints.IdentityTransformation(n_parameters)

:class`Transformation` that returns the input (untransformed) parameters, i.e. the search space under this transformation is the same as the model space. And its Jacobian matrix is the identity matrix.

Extends Transformation.

Parameters:

n_parameters – Number of model parameters this transformation is defined over.

convert_boundaries(boundaries)

Returns a transformed pints.Boundaries object.

convert_covariance_matrix(C, q)

Converts a convariance matrix C from the model space to the search space around a parameter vector q provided in the search space.

The transformation is performed using a first order linear approximation [1] with the Jacobian \(\mathbf{J}\):

\[\begin{split}\mathbf{C}(\boldsymbol{q}) &= \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \mathbf{C}(\boldsymbol{p}) \left( \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \right)^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2) \\ &= \mathbf{J}^{-1}(\boldsymbol{q}) \mathbf{C}(\boldsymbol{p}) (\mathbf{J}^{-1}(\boldsymbol{q}))^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2).\end{split}\]

Using the property that \(\mathbf{J}^{-1} = \frac{d\boldsymbol{g}}{d\boldsymbol{p}}\), from the inverse function theorem, i.e. the matrix inverse of the Jacobian matrix of an invertible function is the Jacobian matrix of the inverse function.

convert_error_measure(error_measure)

Returns a transformed pints.ErrorMeasure.

convert_log_pdf(log_pdf)

Returns a transformed pints.LogPDF.

If log_pdf is a LogPrior, a TransformedLogPrior will be returned, which also transforms the output of the sample() method.

If log_pdf is a LogLikelihood, a TransformedLogLikelihood is returned, which is assumed to be invariant with respect to the transform (because it is a probability of the data, not the parameters). For all other types (including LogPrior) a non-invariant transform is used, see TransformedLogPDF for details.

convert_log_prior(log_prior)

Deprecated function: Use convert_log_pdf() instead.

convert_standard_deviation(s, q)

Converts standard deviation s, either a scalar or a vector, from the model space to the search space around a parameter vector q provided in the search space.

The transformation is performed using a first order linear approximation [1] with the Jacobian \(\mathbf{J}\):

\[\begin{split}\mathbf{C}(\boldsymbol{q}) &= \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \mathbf{C}(\boldsymbol{p}) \left( \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \right)^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2) \\ &= \mathbf{J}^{-1}(\boldsymbol{q}) \mathbf{C}(\boldsymbol{p}) (\mathbf{J}^{-1}(\boldsymbol{q}))^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2).\end{split}\]

Using the property that \(\mathbf{J}^{-1} = \frac{d\boldsymbol{g}}{d\boldsymbol{p}}\), from the inverse function theorem, i.e. the matrix inverse of the Jacobian matrix of an invertible function is the Jacobian matrix of the inverse function.

To transform the provided standard deviation \(\boldsymbol{s}\), we assume the covariance matrix \(\mathbf{C}(\boldsymbol{p})\) above is a diagonal matrix with \(\boldsymbol{s}^2\) on the diagonal, such that

\[s_i(\boldsymbol{q}) = \left( \mathbf{J}^{-1} (\mathbf{J}^{-1})^T \right)^{1/2}_{i, i} s_i(\boldsymbol{p}).\]

elementwise()

See Transformation.elementwise().

jacobian(q)

See Transformation.jacobian().

jacobian_S1(q)

See Transformation.jacobian_S1().

log_jacobian_det(q)

See Transformation.log_jacobian_det().

log_jacobian_det_S1(q)

See Transformation.log_jacobian_det_S1().

n_parameters()

See Transformation.n_parameters().

to_model(q)

See Transformation.to_model().

to_search(p)

See Transformation.to_search().

class pints.LogitTransformation(n_parameters)

Logit (or log-odds) transformation of the model parameters.

The transformation is given by

\[q = \text{logit}(p) = \log(\frac{p}{1 - p}),\]

where \(p\) is the model parameter vector and \(q\) is the search space vector.

The Jacobian adjustment of the logit transformation is given by

\[|\frac{d}{dq} \text{logit}^{-1}(q)| = \text{logit}^{-1}(q) \times (1 - \text{logit}^{-1}(q)).\]

And its derivative is given by

\[\frac{d^2}{dq^2} \text{logit}^{-1}(q) = \frac{d f^{-1}(q)}{dq} \times \left( \frac{\exp(-q) - 1}{exp(-q) + 1} \right).\]

The first order derivative of the log determinant of the Jacobian is

\[\frac{d}{dq} \log(|J(q)|) = 2 \times \exp(-q) \times \text{logit}^{-1}(q) - 1.\]

Extends Transformation.

Parameters:

n_parameters – Number of model parameters this transformation is defined over.

convert_boundaries(boundaries)

Returns a transformed pints.Boundaries object.

convert_covariance_matrix(C, q)

Converts a convariance matrix C from the model space to the search space around a parameter vector q provided in the search space.

The transformation is performed using a first order linear approximation [1] with the Jacobian \(\mathbf{J}\):

\[\begin{split}\mathbf{C}(\boldsymbol{q}) &= \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \mathbf{C}(\boldsymbol{p}) \left( \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \right)^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2) \\ &= \mathbf{J}^{-1}(\boldsymbol{q}) \mathbf{C}(\boldsymbol{p}) (\mathbf{J}^{-1}(\boldsymbol{q}))^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2).\end{split}\]

Using the property that \(\mathbf{J}^{-1} = \frac{d\boldsymbol{g}}{d\boldsymbol{p}}\), from the inverse function theorem, i.e. the matrix inverse of the Jacobian matrix of an invertible function is the Jacobian matrix of the inverse function.

convert_error_measure(error_measure)

Returns a transformed pints.ErrorMeasure.

convert_log_pdf(log_pdf)

Returns a transformed pints.LogPDF.

If log_pdf is a LogPrior, a TransformedLogPrior will be returned, which also transforms the output of the sample() method.

If log_pdf is a LogLikelihood, a TransformedLogLikelihood is returned, which is assumed to be invariant with respect to the transform (because it is a probability of the data, not the parameters). For all other types (including LogPrior) a non-invariant transform is used, see TransformedLogPDF for details.

convert_log_prior(log_prior)

Deprecated function: Use convert_log_pdf() instead.

convert_standard_deviation(s, q)

Converts standard deviation s, either a scalar or a vector, from the model space to the search space around a parameter vector q provided in the search space.

The transformation is performed using a first order linear approximation [1] with the Jacobian \(\mathbf{J}\):

\[\begin{split}\mathbf{C}(\boldsymbol{q}) &= \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \mathbf{C}(\boldsymbol{p}) \left( \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \right)^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2) \\ &= \mathbf{J}^{-1}(\boldsymbol{q}) \mathbf{C}(\boldsymbol{p}) (\mathbf{J}^{-1}(\boldsymbol{q}))^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2).\end{split}\]

Using the property that \(\mathbf{J}^{-1} = \frac{d\boldsymbol{g}}{d\boldsymbol{p}}\), from the inverse function theorem, i.e. the matrix inverse of the Jacobian matrix of an invertible function is the Jacobian matrix of the inverse function.

To transform the provided standard deviation \(\boldsymbol{s}\), we assume the covariance matrix \(\mathbf{C}(\boldsymbol{p})\) above is a diagonal matrix with \(\boldsymbol{s}^2\) on the diagonal, such that

\[s_i(\boldsymbol{q}) = \left( \mathbf{J}^{-1} (\mathbf{J}^{-1})^T \right)^{1/2}_{i, i} s_i(\boldsymbol{p}).\]

elementwise()

See Transformation.elementwise().

jacobian(q)

See Transformation.jacobian().

jacobian_S1(q)

See Transformation.jacobian_S1().

log_jacobian_det(q)

See Transformation.log_jacobian_det().

log_jacobian_det_S1(q)

See Transformation.log_jacobian_det_S1().

n_parameters()

See Transformation.n_parameters().

to_model(q)

See Transformation.to_model().

to_search(p)

See Transformation.to_search().

class pints.LogTransformation(n_parameters)

Logarithm transformation of the model parameters:

The transformation is given by

\[q = \log(p),\]

where \(p\) is the model parameter vector and \(q\) is the search space vector.

The Jacobian adjustment of the log transformation is given by

\[|\frac{d}{dq} \exp(q)| = \exp(q).\]

And its derivative is given by

\[\frac{d^2}{dq^2} \exp(q) = \exp(q).\]

The first order derivative of the log determinant of the Jacobian is

\[\frac{d}{dq} \log(|J(q)|) = 1.\]

Extends Transformation.

Parameters:

n_parameters – Number of model parameters this transformation is defined over.

convert_boundaries(boundaries)

Returns a transformed pints.Boundaries object.

convert_covariance_matrix(C, q)

Converts a convariance matrix C from the model space to the search space around a parameter vector q provided in the search space.

The transformation is performed using a first order linear approximation [1] with the Jacobian \(\mathbf{J}\):

\[\begin{split}\mathbf{C}(\boldsymbol{q}) &= \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \mathbf{C}(\boldsymbol{p}) \left( \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \right)^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2) \\ &= \mathbf{J}^{-1}(\boldsymbol{q}) \mathbf{C}(\boldsymbol{p}) (\mathbf{J}^{-1}(\boldsymbol{q}))^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2).\end{split}\]

Using the property that \(\mathbf{J}^{-1} = \frac{d\boldsymbol{g}}{d\boldsymbol{p}}\), from the inverse function theorem, i.e. the matrix inverse of the Jacobian matrix of an invertible function is the Jacobian matrix of the inverse function.

convert_error_measure(error_measure)

Returns a transformed pints.ErrorMeasure.

convert_log_pdf(log_pdf)

Returns a transformed pints.LogPDF.

If log_pdf is a LogPrior, a TransformedLogPrior will be returned, which also transforms the output of the sample() method.

If log_pdf is a LogLikelihood, a TransformedLogLikelihood is returned, which is assumed to be invariant with respect to the transform (because it is a probability of the data, not the parameters). For all other types (including LogPrior) a non-invariant transform is used, see TransformedLogPDF for details.

convert_log_prior(log_prior)

Deprecated function: Use convert_log_pdf() instead.

convert_standard_deviation(s, q)

Converts standard deviation s, either a scalar or a vector, from the model space to the search space around a parameter vector q provided in the search space.

The transformation is performed using a first order linear approximation [1] with the Jacobian \(\mathbf{J}\):

\[\begin{split}\mathbf{C}(\boldsymbol{q}) &= \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \mathbf{C}(\boldsymbol{p}) \left( \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \right)^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2) \\ &= \mathbf{J}^{-1}(\boldsymbol{q}) \mathbf{C}(\boldsymbol{p}) (\mathbf{J}^{-1}(\boldsymbol{q}))^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2).\end{split}\]

Using the property that \(\mathbf{J}^{-1} = \frac{d\boldsymbol{g}}{d\boldsymbol{p}}\), from the inverse function theorem, i.e. the matrix inverse of the Jacobian matrix of an invertible function is the Jacobian matrix of the inverse function.

To transform the provided standard deviation \(\boldsymbol{s}\), we assume the covariance matrix \(\mathbf{C}(\boldsymbol{p})\) above is a diagonal matrix with \(\boldsymbol{s}^2\) on the diagonal, such that

\[s_i(\boldsymbol{q}) = \left( \mathbf{J}^{-1} (\mathbf{J}^{-1})^T \right)^{1/2}_{i, i} s_i(\boldsymbol{p}).\]

elementwise()

See Transformation.elementwise().

jacobian(q)

See Transformation.jacobian().

jacobian_S1(q)

See Transformation.jacobian_S1().

log_jacobian_det(q)

See Transformation.log_jacobian_det().

log_jacobian_det_S1(q)

See Transformation.log_jacobian_det_S1().

n_parameters()

See Transformation.n_parameters().

to_model(q)

See Transformation.to_model().

to_search(p)

See Transformation.to_search().

class pints.RectangularBoundariesTransformation(lower_or_boundaries, upper=None)

A generalised version of the logit transformation for the model parameters, which transforms an interval or rectangular boundaries \([a, b)\) to all real number.

The transformation is given by

\[q = f(p) = \text{logit}\left(\frac{p - a}{b - p}\right) = \log(p - a) - \log(b - p),\]

where \(p\) is the model parameter vector and \(q\) is the search space vector. Note that LogitTransformation is a special case where \(a = 0\) and \(b = 1\).

The Jacobian adjustment of the transformation is given by

\[|\frac{d}{dq} f^{-1}(q)| = \frac{b - a}{\exp(q) (1 + \exp(-q)) ^ 2}.\]

And its derivative is given by

\[\frac{d^2}{dq^2} f^{-1}(q) = \frac{d f^{-1}(q)}{dq} \times \left( \frac{\exp(-q) - 1}{exp(-q) + 1} \right).\]

The log-determinant of the Jacobian matrix is given by

\[\log|\frac{d}{dq} f^{-1}(q)| = \sum_i \left( \log(b_i - a_i) - 2 \times \log(1 + \exp(-q_i)) - q_i \right)\]

The first order derivative of the log determinant of the Jacobian is

\[\frac{d}{dq} \log(|J(q)|) = 2 \times \exp(-q) \times \text{logit}^{-1}(q) - 1.\]

For example, to create a transformation with \(p_1 \in [0, 4)\), \(p_2 \in [1, 5)\), and \(p_3 \in [2, 6)\) use either:

transformation = pints.RectangularBoundariesTransformation([0, 1, 2],
                                                           [4, 5, 6])

or:

boundaries = pints.RectangularBoundaries([0, 1, 2], [4, 5, 6])
transformation = pints.RectangularBoundariesTransformation(boundaries)

Not to be confused with pints.TransformedRectangularBoundaries.

Extends Transformation.

convert_boundaries(boundaries)

Returns a transformed pints.Boundaries object.

convert_covariance_matrix(C, q)

Converts a convariance matrix C from the model space to the search space around a parameter vector q provided in the search space.

The transformation is performed using a first order linear approximation [1] with the Jacobian \(\mathbf{J}\):

\[\begin{split}\mathbf{C}(\boldsymbol{q}) &= \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \mathbf{C}(\boldsymbol{p}) \left( \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \right)^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2) \\ &= \mathbf{J}^{-1}(\boldsymbol{q}) \mathbf{C}(\boldsymbol{p}) (\mathbf{J}^{-1}(\boldsymbol{q}))^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2).\end{split}\]

Using the property that \(\mathbf{J}^{-1} = \frac{d\boldsymbol{g}}{d\boldsymbol{p}}\), from the inverse function theorem, i.e. the matrix inverse of the Jacobian matrix of an invertible function is the Jacobian matrix of the inverse function.

convert_error_measure(error_measure)

Returns a transformed pints.ErrorMeasure.

convert_log_pdf(log_pdf)

Returns a transformed pints.LogPDF.

If log_pdf is a LogPrior, a TransformedLogPrior will be returned, which also transforms the output of the sample() method.

If log_pdf is a LogLikelihood, a TransformedLogLikelihood is returned, which is assumed to be invariant with respect to the transform (because it is a probability of the data, not the parameters). For all other types (including LogPrior) a non-invariant transform is used, see TransformedLogPDF for details.

convert_log_prior(log_prior)

Deprecated function: Use convert_log_pdf() instead.

convert_standard_deviation(s, q)

Converts standard deviation s, either a scalar or a vector, from the model space to the search space around a parameter vector q provided in the search space.

The transformation is performed using a first order linear approximation [1] with the Jacobian \(\mathbf{J}\):

\[\begin{split}\mathbf{C}(\boldsymbol{q}) &= \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \mathbf{C}(\boldsymbol{p}) \left( \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \right)^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2) \\ &= \mathbf{J}^{-1}(\boldsymbol{q}) \mathbf{C}(\boldsymbol{p}) (\mathbf{J}^{-1}(\boldsymbol{q}))^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2).\end{split}\]

Using the property that \(\mathbf{J}^{-1} = \frac{d\boldsymbol{g}}{d\boldsymbol{p}}\), from the inverse function theorem, i.e. the matrix inverse of the Jacobian matrix of an invertible function is the Jacobian matrix of the inverse function.

To transform the provided standard deviation \(\boldsymbol{s}\), we assume the covariance matrix \(\mathbf{C}(\boldsymbol{p})\) above is a diagonal matrix with \(\boldsymbol{s}^2\) on the diagonal, such that

\[s_i(\boldsymbol{q}) = \left( \mathbf{J}^{-1} (\mathbf{J}^{-1})^T \right)^{1/2}_{i, i} s_i(\boldsymbol{p}).\]

elementwise()

See Transformation.elementwise().

jacobian(q)

See Transformation.jacobian().

jacobian_S1(q)

See Transformation.jacobian_S1().

log_jacobian_det(q)

See Transformation.log_jacobian_det().

log_jacobian_det_S1(q)

See Transformation.log_jacobian_det_S1().

n_parameters()

See Transformation.n_parameters().

to_model(q)

See Transformation.to_model().

to_search(p)

Transforms a parameter vector p from the model space to the search space.

class pints.ScalingTransformation(scalings, translation=None)

Scales the input parameters by multiplying with an array scalings and adding an optional array translation.

The transformation from model parameters p to search parameters q is performed as:

q = (p + translation) * scalings

Its Jacobian matrix is a diagonal matrix with 1 / scalings on the diagonal.

Extends Transformation.

convert_boundaries(boundaries)

Returns a transformed pints.Boundaries object.

convert_covariance_matrix(C, q)

Converts a convariance matrix C from the model space to the search space around a parameter vector q provided in the search space.

The transformation is performed using a first order linear approximation [1] with the Jacobian \(\mathbf{J}\):

\[\begin{split}\mathbf{C}(\boldsymbol{q}) &= \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \mathbf{C}(\boldsymbol{p}) \left( \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \right)^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2) \\ &= \mathbf{J}^{-1}(\boldsymbol{q}) \mathbf{C}(\boldsymbol{p}) (\mathbf{J}^{-1}(\boldsymbol{q}))^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2).\end{split}\]

Using the property that \(\mathbf{J}^{-1} = \frac{d\boldsymbol{g}}{d\boldsymbol{p}}\), from the inverse function theorem, i.e. the matrix inverse of the Jacobian matrix of an invertible function is the Jacobian matrix of the inverse function.

convert_error_measure(error_measure)

Returns a transformed pints.ErrorMeasure.

convert_log_pdf(log_pdf)

Returns a transformed pints.LogPDF.

If log_pdf is a LogPrior, a TransformedLogPrior will be returned, which also transforms the output of the sample() method.

If log_pdf is a LogLikelihood, a TransformedLogLikelihood is returned, which is assumed to be invariant with respect to the transform (because it is a probability of the data, not the parameters). For all other types (including LogPrior) a non-invariant transform is used, see TransformedLogPDF for details.

convert_log_prior(log_prior)

Deprecated function: Use convert_log_pdf() instead.

convert_standard_deviation(s, q)

Converts standard deviation s, either a scalar or a vector, from the model space to the search space around a parameter vector q provided in the search space.

The transformation is performed using a first order linear approximation [1] with the Jacobian \(\mathbf{J}\):

\[\begin{split}\mathbf{C}(\boldsymbol{q}) &= \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \mathbf{C}(\boldsymbol{p}) \left( \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \right)^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2) \\ &= \mathbf{J}^{-1}(\boldsymbol{q}) \mathbf{C}(\boldsymbol{p}) (\mathbf{J}^{-1}(\boldsymbol{q}))^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2).\end{split}\]

Using the property that \(\mathbf{J}^{-1} = \frac{d\boldsymbol{g}}{d\boldsymbol{p}}\), from the inverse function theorem, i.e. the matrix inverse of the Jacobian matrix of an invertible function is the Jacobian matrix of the inverse function.

To transform the provided standard deviation \(\boldsymbol{s}\), we assume the covariance matrix \(\mathbf{C}(\boldsymbol{p})\) above is a diagonal matrix with \(\boldsymbol{s}^2\) on the diagonal, such that

\[s_i(\boldsymbol{q}) = \left( \mathbf{J}^{-1} (\mathbf{J}^{-1})^T \right)^{1/2}_{i, i} s_i(\boldsymbol{p}).\]

elementwise()

See Transformation.elementwise().

jacobian(q)

See Transformation.jacobian().

jacobian_S1(q)

See Transformation.jacobian_S1().

log_jacobian_det(q)

See Transformation.log_jacobian_det().

log_jacobian_det_S1(q)

See Transformation.log_jacobian_det_S1().

n_parameters()

See Transformation.n_parameters().

to_model(q)

See Transformation.to_model().

to_search(p)

See Transformation.to_search().

class pints.UnitCubeTransformation(lower, upper)

Maps a parameter space onto the unit (hyper)cube.

Transformations from model parameters p to search parameters q are made as:

q = (p - lower) / (upper - lower)

Extends ScalingTransformation.

convert_boundaries(boundaries)

Returns a transformed pints.Boundaries object.

convert_covariance_matrix(C, q)

Converts a convariance matrix C from the model space to the search space around a parameter vector q provided in the search space.

The transformation is performed using a first order linear approximation [1] with the Jacobian \(\mathbf{J}\):

\[\begin{split}\mathbf{C}(\boldsymbol{q}) &= \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \mathbf{C}(\boldsymbol{p}) \left( \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \right)^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2) \\ &= \mathbf{J}^{-1}(\boldsymbol{q}) \mathbf{C}(\boldsymbol{p}) (\mathbf{J}^{-1}(\boldsymbol{q}))^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2).\end{split}\]

Using the property that \(\mathbf{J}^{-1} = \frac{d\boldsymbol{g}}{d\boldsymbol{p}}\), from the inverse function theorem, i.e. the matrix inverse of the Jacobian matrix of an invertible function is the Jacobian matrix of the inverse function.

convert_error_measure(error_measure)

Returns a transformed pints.ErrorMeasure.

convert_log_pdf(log_pdf)

Returns a transformed pints.LogPDF.

If log_pdf is a LogPrior, a TransformedLogPrior will be returned, which also transforms the output of the sample() method.

If log_pdf is a LogLikelihood, a TransformedLogLikelihood is returned, which is assumed to be invariant with respect to the transform (because it is a probability of the data, not the parameters). For all other types (including LogPrior) a non-invariant transform is used, see TransformedLogPDF for details.

convert_log_prior(log_prior)

Deprecated function: Use convert_log_pdf() instead.

convert_standard_deviation(s, q)

Converts standard deviation s, either a scalar or a vector, from the model space to the search space around a parameter vector q provided in the search space.

The transformation is performed using a first order linear approximation [1] with the Jacobian \(\mathbf{J}\):

\[\begin{split}\mathbf{C}(\boldsymbol{q}) &= \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \mathbf{C}(\boldsymbol{p}) \left( \frac{d\boldsymbol{g}(\boldsymbol{p})}{d\boldsymbol{p}} \right)^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2) \\ &= \mathbf{J}^{-1}(\boldsymbol{q}) \mathbf{C}(\boldsymbol{p}) (\mathbf{J}^{-1}(\boldsymbol{q}))^T + \mathcal{O}(\mathbf{C}(\boldsymbol{p})^2).\end{split}\]

Using the property that \(\mathbf{J}^{-1} = \frac{d\boldsymbol{g}}{d\boldsymbol{p}}\), from the inverse function theorem, i.e. the matrix inverse of the Jacobian matrix of an invertible function is the Jacobian matrix of the inverse function.

To transform the provided standard deviation \(\boldsymbol{s}\), we assume the covariance matrix \(\mathbf{C}(\boldsymbol{p})\) above is a diagonal matrix with \(\boldsymbol{s}^2\) on the diagonal, such that

\[s_i(\boldsymbol{q}) = \left( \mathbf{J}^{-1} (\mathbf{J}^{-1})^T \right)^{1/2}_{i, i} s_i(\boldsymbol{p}).\]

elementwise()

See Transformation.elementwise().

jacobian(q)

See Transformation.jacobian().

jacobian_S1(q)

See Transformation.jacobian_S1().

log_jacobian_det(q)

See Transformation.log_jacobian_det().

log_jacobian_det_S1(q)

See Transformation.log_jacobian_det_S1().

n_parameters()

See Transformation.n_parameters().

to_model(q)

See Transformation.to_model().

to_search(p)

See Transformation.to_search().

Transformed objects

class pints.TransformedBoundaries(boundaries, transformation)

A pints.Boundaries that accepts parameters in a transformed search space.

Extends pints.Boundaries.

Parameters:

• boundaries – A pints.Boundaries.

• transformation – A pints.Transformation.

check(q)

See Boundaries.check().

n_parameters()

See Boundaries.n_parameters().

sample(n=1)

See Boundaries.sample().

class pints.TransformedErrorMeasure(error, transformation)

A pints.ErrorMeasure that accepts parameters in a transformed search space.

For the first order sensitivity of a pints.ErrorMeasure \(E\) and a pints.Transformation \(\boldsymbol{q} = \boldsymbol{f}(\boldsymbol{p})\), the transformation is done using

\[\begin{split}\frac{\partial E(\boldsymbol{q})}{\partial q_i} &= \frac{\partial E(\boldsymbol{f}^{-1}(\boldsymbol{q}))}{\partial q_i}\\ &= \sum_l \frac{\partial E(\boldsymbol{p})}{\partial p_l} \frac{\partial p_l}{\partial q_i}.\end{split}\]

Extends pints.ErrorMeasure.

Parameters:

• error – A pints.ErrorMeasure.

• transformation – A pints.Transformation.

__call__(q)

Evaluates this error measure for parameters x.

evaluateS1(q)

See ErrorMeasure.evaluateS1().

n_parameters()

See ErrorMeasure.n_parameters().

class pints.TransformedLogLikelihood(log_likelihood, transformation)

A pints.LogLikelihood that accepts parameters in a transformed search space.

Unlike a TransformedLogPDF, a likelihood (a measure of how well the data, $boldsymbol{x}, is explained by a model, given fixed parameters) is invariant to a parameter transform (but not to a data transform), and so no Jacobian term appears. Instead for some Transformation \(\boldsymbol{q}=\boldsymbol{f}(\boldsymbol{p})\)

\[\underset{\boldsymbol{q}}{\text{max}}( \log L(\boldsymbol{q}|\boldsymbol{x})) = \underset{\boldsymbol{q}}{\text{max}}( \log L(\boldsymbol{f}^{-1}(\boldsymbol{q}|\boldsymbol{x}))).\]

For the first order sensitivity, the transformation is done using

\[\begin{split}\frac{\partial \log L(\boldsymbol{q}|\boldsymbol{x})}{\partial q_i} &= \frac{\partial \log L(\boldsymbol{f}^{-1}(\boldsymbol{q}) | \boldsymbol{x})}{\partial q_i} \\ &= \sum_l \frac{ \partial \log L(\boldsymbol{p|\boldsymbol{x}})}{\partial p_l} \frac{\partial p_l}{\partial q_i}.\end{split}\]

Extends pints.LogLikelihood.

Parameters:

• log_likelihood – A pints.LogLikelihood.

• transformation – A pints.Transformation.

__call__(q)

Evaluates this LogPDF for parameters x.

evaluateS1(q)

See LogPDF.evaluateS1().

n_parameters()

See LogPDF.n_parameters().

class pints.TransformedLogPDF(log_pdf, transformation)

A pints.LogPDF that accepts parameters in a transformed search space.

When a TransformedLogPDF object (initialised with a pints.LogPDF of \(\pi(\boldsymbol{p})\) and a Transformation of \(\boldsymbol{q} = \boldsymbol{f}(\boldsymbol{p})\)) is called with a vector argument \(\boldsymbol{q}\) in the search space, it returns \(\log(\pi(\boldsymbol{q}))`\) where \(\pi(\boldsymbol{q})\) is the transformed unnormalised PDF of the input PDF, using

\[\pi(\boldsymbol{q}) = \pi(\boldsymbol{f}^{-1}(\boldsymbol{q})) \,\, |det(\mathbf{J}(\boldsymbol{f}^{-1}(\boldsymbol{q})))|.\]

\(\mathbf{J}\) is the Jacobian matrix:

\[\mathbf{J} = \left[\frac{\partial \boldsymbol{f}^{-1}}{\partial q_1} \quad \frac{\partial \boldsymbol{f}^{-1}}{\partial q_2} \quad \cdots \right].\]

Hence

\[\log(\pi(\boldsymbol{q})) = \log(\pi(\boldsymbol{f}^{-1}(\boldsymbol{q}))) + \log(|det(\mathbf{J}(\boldsymbol{f}^{-1}(\boldsymbol{q})))|).\]

For the first order sensitivity, the transformation is done using

\[\frac{\partial \log(\pi(\boldsymbol{q}))}{\partial q_i} = \frac{\partial \log(\pi(\boldsymbol{f}^{-1}(\boldsymbol{q})))}{\partial q_i} + \frac{\partial \log(|det(\mathbf{J})|)}{\partial q_i}.\]

The first term can be calculated using the chain rule

\[\frac{\partial \log(\pi(\boldsymbol{f}^{-1}(\boldsymbol{q})))}{\partial q_i} = \sum_l \frac{\partial \log(\pi(\boldsymbol{p}))}{\partial p_l} \frac{\partial p_l}{\partial q_i}.\]

Extends pints.LogPDF.

Parameters:

• log_pdf – A pints.LogPDF.

• transformation – A pints.Transformation.

__call__(q)

Evaluates this LogPDF for parameters x.

evaluateS1(q)

See LogPDF.evaluateS1().

n_parameters()

See LogPDF.n_parameters().

class pints.TransformedLogPrior(log_prior, transformation)

A pints.LogPrior that accepts parameters in a transformed search space.

Extends pints.LogPrior, pints.TransformedLogPDF.

Parameters:

• log_prior – A pints.LogPrior.

• transformation – A pints.Transformation.

__call__(q)

Evaluates this LogPDF for parameters x.

cdf(x)

Returns the cumulative density function at point(s) x.

x should be an n x d array, where n is the number of input samples and d is the dimension of the parameter space.

convert_from_unit_cube(u)

Converts samples u uniformly drawn from the unit cube into those drawn from the prior space, typically by transforming using LogPrior.icdf().

u should be an n x d array, where n is the number of input samples and d is the dimension of the parameter space.

convert_to_unit_cube(x)

Converts samples from the prior x to be drawn uniformly from the unit cube, typically by transforming using LogPrior.cdf().

x should be an n x d array, where n is the number of input samples and d is the dimension of the parameter space.

evaluateS1(q)

See LogPDF.evaluateS1().

icdf(p)

Returns the inverse cumulative density function at cumulative probability/probabilities p.

p should be an n x d array, where n is the number of input samples and d is the dimension of the parameter space.

mean()

Returns the analytical value of the expectation of a random variable distributed according to this LogPDF.

n_parameters()

See LogPDF.n_parameters().

sample(n)

See pints.LogPrior.sample().

Note that this does not sample from the transformed log-prior but simply transforms the samples from the original log-prior.

class pints.TransformedRectangularBoundaries(boundaries, transformation)

A pints.RectangularBoundaries that accepts parameters in a transformed search space.

This transformation handles the special case where:

• the boundaries being transformed are pints.RectangularBoundaries

• the transformation is element-wise.

When these conditions are met, the lower and upper boundaries can simply be transformed and methods like lower() and range() can be provided.

Not to be confused with pints.RectangularBoundariesTransformation.

Extends pints.RectangularBoundaries.

Parameters:

• boundaries – A pints.RectangularBoundaries object.

• transformation – An element-wise transformation.

check(parameters)

See pints.Boundaries.check().

lower()

Returns the lower boundaries for all parameters (as a read-only NumPy array).

n_parameters()

See pints.Boundaries.n_parameters().

range()

Returns the size of the parameter space (i.e. upper - lower).

sample(n=1)

See Boundaries.sample().

upper()

Returns the upper boundary for all parameters (as a read-only NumPy array).