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:
ComposedTransformation
IdentityTransformation
LogitTransformation
LogTransformation
RectangularBoundariesTransformation
ScalingTransformation
Transformation
TransformedBoundaries
TransformedErrorMeasure
TransformedLogPDF
TransformedLogPrior
-
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)
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)[source]¶ Scaling transformation scales the input parameters by multiplying with an array
scalings
element-wisely. And its Jacobian matrix is a diagonal matrix with the values of1 / 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.
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
[1] (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14) 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_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.
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)¶ Returns
n
random samples from within the boundaries, for example to use as starting points for an optimisation.The returned value is a NumPy array with shape
(n, d)
wheren
is the requested number of samples, andd
is the dimension of the parameter space these boundaries are defined on.Note that implementing :meth:`sample()` is optional, so some boundary types may not support it.
Parameters: n (int) – The number of points to sample
- boundaries – A
-
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
.
- error – A
-
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()
.
- log_pdf – A
-
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
()¶
- log_prior – A