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)
Overview:
Transformation types¶
- class pints.Transformation[source]¶
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 aTransformation
class, you can apply the transformation of a parameter vector from the model spacep
to the search spaceq
by usingq = trans.to_search(p)
and the inverse by usingp = trans.to_model(q)
.References
- convert_covariance_matrix(C, q)[source]¶
Converts a convariance matrix
C
from the model space to the search space around a parameter vectorq
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_standard_deviation(s, q)[source]¶
Converts standard deviation
s
, either a scalar or a vector, from the model space to the search space around a parameter vectorq
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()[source]¶
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)[source]¶
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 matrixTransformation.convert_covariance_matrix()
is needed, or whenevaluateS1()
is needed.
- jacobian_S1(q)[source]¶
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')
whereS
is an_parameters
byn_parameters
matrix andS'
is a sequence ofn_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)[source]¶
Returns the logarithm of the absolute value of the determinant of the Jacobian matrix of the transformation
Transformation.jacobian()
calculated at the parameter vectorq
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 requiresevaluateS1()
; e.g. not necessary if it’s used forErrorMeasure
withoutErrorMeasure.evaluateS1()
.
- log_jacobian_det_S1(q)[source]¶
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')
whereS
is a scalar value andS'
is a sequence of lengthn_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 requiresevaluateS1()
.
- class pints.ComposedTransformation(*transformations)[source]¶
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
, andtransformation_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 byt.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 boundaries class.
- convert_covariance_matrix(C, q)¶
Converts a convariance matrix
C
from the model space to the search space around a parameter vectorq
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 error measure class.
- convert_log_pdf(log_pdf)¶
Returns a transformed log-PDF class.
- convert_log_prior(log_prior)¶
Returns a transformed log-prior class.
- 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 vectorq
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}).\]
- class pints.IdentityTransformation(n_parameters)[source]¶
: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 boundaries class.
- convert_covariance_matrix(C, q)¶
Converts a convariance matrix
C
from the model space to the search space around a parameter vectorq
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 error measure class.
- convert_log_pdf(log_pdf)¶
Returns a transformed log-PDF class.
- convert_log_prior(log_prior)¶
Returns a transformed log-prior class.
- 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 vectorq
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}).\]
- class pints.LogitTransformation(n_parameters)[source]¶
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 boundaries class.
- convert_covariance_matrix(C, q)¶
Converts a convariance matrix
C
from the model space to the search space around a parameter vectorq
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 error measure class.
- convert_log_pdf(log_pdf)¶
Returns a transformed log-PDF class.
- convert_log_prior(log_prior)¶
Returns a transformed log-prior class.
- 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 vectorq
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}).\]
- class pints.LogTransformation(n_parameters)[source]¶
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 boundaries class.
- convert_covariance_matrix(C, q)¶
Converts a convariance matrix
C
from the model space to the search space around a parameter vectorq
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 error measure class.
- convert_log_pdf(log_pdf)¶
Returns a transformed log-PDF class.
- convert_log_prior(log_prior)¶
Returns a transformed log-prior class.
- 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 vectorq
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}).\]
- class pints.RectangularBoundariesTransformation(lower_or_boundaries, upper=None)[source]¶
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 boundaries class.
- convert_covariance_matrix(C, q)¶
Converts a convariance matrix
C
from the model space to the search space around a parameter vectorq
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 error measure class.
- convert_log_pdf(log_pdf)¶
Returns a transformed log-PDF class.
- convert_log_prior(log_prior)¶
Returns a transformed log-prior class.
- 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 vectorq
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}).\]
- class pints.ScalingTransformation(scalings, translation=None)[source]¶
Scales the input parameters by multiplying with an array
scalings
and adding an optional arraytranslation
.The transformation from model parameters
p
to search parametersq
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 boundaries class.
- convert_covariance_matrix(C, q)¶
Converts a convariance matrix
C
from the model space to the search space around a parameter vectorq
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 error measure class.
- convert_log_pdf(log_pdf)¶
Returns a transformed log-PDF class.
- convert_log_prior(log_prior)¶
Returns a transformed log-prior class.
- 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 vectorq
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}).\]
- class pints.UnitCubeTransformation(lower, upper)[source]¶
Maps a parameter space onto the unit (hyper)cube.
Transformations from model parameters
p
to search parametersq
are made as:q = (p - lower) / (upper - lower)
Extends
ScalingTransformation
.- convert_boundaries(boundaries)¶
Returns a transformed boundaries class.
- convert_covariance_matrix(C, q)¶
Converts a convariance matrix
C
from the model space to the search space around a parameter vectorq
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 error measure class.
- convert_log_pdf(log_pdf)¶
Returns a transformed log-PDF class.
- convert_log_prior(log_prior)¶
Returns a transformed log-prior class.
- 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 vectorq
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()¶
- jacobian(q)¶
- jacobian_S1(q)¶
- log_jacobian_det(q)¶
- log_jacobian_det_S1(q)¶
- n_parameters()¶
- to_model(q)¶
- to_search(p)¶
Transformed objects¶
- class pints.TransformedBoundaries(boundaries, transformation)[source]¶
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)[source]¶
See
Boundaries.check()
.
- sample(n=1)[source]¶
See
Boundaries.sample()
.
- class pints.TransformedErrorMeasure(error, transformation)[source]¶
A
pints.ErrorMeasure
that accepts parameters in a transformed search space.For the first order sensitivity of a
pints.ErrorMeasure
\(E\) and apints.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
.
- class pints.TransformedLogPDF(log_pdf, transformation)[source]¶
A
pints.LogPDF
that accepts parameters in a transformed search space.When a
TransformedLogPDF
object (initialised with apints.LogPDF
of \(\pi(\boldsymbol{p})\) and aTransformation
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
.
- evaluateS1(q)[source]¶
See
LogPDF.evaluateS1()
.
- class pints.TransformedLogPrior(log_prior, transformation)[source]¶
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
.
- cdf(x)¶
Returns the cumulative density function at point(s)
x
.x
should be ann x d
array, wheren
is the number of input samples andd
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 usingLogPrior.icdf()
.u
should be ann x d
array, wheren
is the number of input samples andd
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 usingLogPrior.cdf()
.x
should be ann x d
array, wheren
is the number of input samples andd
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 ann x d
array, wheren
is the number of input samples andd
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()¶
- class pints.TransformedRectangularBoundaries(boundaries, transformation)[source]¶
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()
andrange()
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)¶
- lower()¶
Returns the lower boundaries for all parameters (as a read-only NumPy array).
- n_parameters()¶
- range()¶
Returns the size of the parameter space (i.e.
upper - lower
).
- sample(n=1)[source]¶
See
Boundaries.sample()
.
- upper()¶
Returns the upper boundary for all parameters (as a read-only NumPy array).