transformations#

Classes#

`ComposedTransformation`	N-dimensional Transformation composed of one or more other N_i-dimensional
`IdentityTransformation`	This class implements a trivial transformation where the model parameter space
`LogTransformation`	This class implements a logarithmic transformation between the model parameter space
`ScaledTransformation`	This class implements a linear transformation between the model parameter space
`UnitHyperCube`	A class that implements a linear transformation between the model parameter space

Module Contents#

class transformations.ComposedTransformation(transformations: list[pybop.Transformation])[source]#

Bases: pybop.Transformation

N-dimensional Transformation composed of one or more other N_i-dimensional sub-transformations, where the sum of N_i equals N.

This class allows for the composition of multiple transformations, each potentially operating on a different number of dimensions. The total dimensionality of the composed transformation is the sum of the dimensionalities of its components.

The dimensionality of the individual transformations does not have to be the same, i.e., N_i != N_j is allowed.

Extends pybop.Transformation. Initially based on pints.ComposedTransformation class.

_append_transformation(transformation: pybop.Transformation)[source]#

Append a transformation to the internal list of transformations.

Parameters:: transformation (Transformation) – Transformation to append.
Raises:: ValueError – If the appended object is not a Transformation.

_iter_transformations()[source]#

Iterate over the transformations in the composition.

Yields:: Tuple[int, Transformation] – Tuple of starting index and transformation object for each sub-transformation.

_transform(data: numpy.ndarray, method: str) → numpy.ndarray[source]#: See Transformation._transform().

append(transformation: pybop.Transformation)[source]#

Append a new transformation to the existing composition.

Parameters:: transformation (Transformation) – The transformation to append.

is_elementwise() → bool[source]#: See Transformation.is_elementwise().

jacobian(q: numpy.ndarray) → numpy.ndarray[source]#

Compute the elementwise Jacobian of the composed transformation.

Parameters:: q (np.ndarray) – Input array.
Returns:: Diagonal matrix representing the elementwise Jacobian.
Return type:: np.ndarray

jacobian_S1(q: numpy.ndarray) → tuple[numpy.ndarray, numpy.ndarray][source]#: See Transformation.jacobian_S1().

log_jacobian_det(q: numpy.ndarray) → float[source]#

Compute the elementwise logarithm of the determinant of the Jacobian.

Parameters:: q (np.ndarray) – Input array.
Returns:: Sum of log determinants of individual transformations.
Return type:: float

log_jacobian_det_S1(q: numpy.ndarray) → tuple[float, numpy.ndarray][source]#

Compute the elementwise logarithm of the determinant of the Jacobian and its first-order sensitivities.

Parameters:: q (np.ndarray) – Input array.
Returns:: Tuple of sum of log determinants and concatenated first-order sensitivities.
Return type:: Tuple[float, np.ndarray]

_is_elementwise = True[source]#

_n_parameters = 0[source]#

_transformations = [][source]#

class transformations.IdentityTransformation(n_parameters: int = 1)[source]#

Bases: pybop.Transformation

This class implements a trivial transformation where the model parameter space and the search space are identical. It extends the base Transformation class.

The transformation is defined as: - to_search: y = x - to_model: x = y

Key properties: 1. Jacobian: Identity matrix 2. Log determinant of Jacobian: Always 0 3. Elementwise: True (each output dimension depends only on the corresponding input dimension)

Use cases: 1. When no transformation is needed between spaces 2. As a placeholder in composite transformations 3. For testing and benchmarking other transformations

Note: While this transformation doesn’t change the parameters, it still provides all the methods required by the Transformation interface, making it useful in scenarios where a transformation object is expected but no actual transformation is needed.

Initially based on pints.IdentityTransformation method.

_transform(x: numpy.ndarray, method: str) → numpy.ndarray[source]#: See Transformation._transform().

is_elementwise() → bool[source]#: See Transformation.is_elementwise().

jacobian(q: numpy.ndarray) → numpy.ndarray[source]#: See Transformation.jacobian().

jacobian_S1(q: numpy.ndarray) → tuple[numpy.ndarray, numpy.ndarray][source]#: See Transformation.jacobian_S1().

log_jacobian_det(q: numpy.ndarray) → float[source]#: See Transformation.log_jacobian_det().

log_jacobian_det_S1(q: numpy.ndarray) → tuple[float, numpy.ndarray][source]#: See Transformation.log_jacobian_det_S1().

_n_parameters = 1[source]#

class transformations.LogTransformation(n_parameters: int = 1)[source]#

Bases: pybop.Transformation

This class implements a logarithmic transformation between the model parameter space and a search space. It extends the base Transformation class.

The transformation is defined as: - to_search: y = log(x) - to_model: x = exp(y)

Where: - x is in the model parameter space (strictly positive) - y is in the search space (can be any real number)

This transformation is particularly useful for: 1. Parameters that are strictly positive and may span several orders of magnitude. 2. Converting multiplicative processes to additive ones in the search space. 3. Ensuring positivity constraints without explicit bounds in optimisation.

Note: Care should be taken when using this transformation, as it can introduce bias in the parameter estimates if not accounted for properly in the likelihood or cost function. Simply, E[log(x)] <= log(E[x]) as per to Jensen’s inequality. For more information, see Jensen’s inequality: https://en.wikipedia.org/w/index.php?title=Jensen%27s_inequality&oldid=1212437916#Probabilistic_form

Initially based on pints.LogTransformation class.

_transform(x: numpy.ndarray, method: str) → numpy.ndarray[source]#: See Transformation._transform().

is_elementwise() → bool[source]#: See Transformation.is_elementwise().

jacobian(q: numpy.ndarray) → numpy.ndarray[source]#: See Transformation.jacobian().

jacobian_S1(q: numpy.ndarray) → tuple[numpy.ndarray, numpy.ndarray][source]#: See Transformation.jacobian_S1().

log_jacobian_det(q: numpy.ndarray) → float[source]#: See Transformation.log_jacobian_det().

log_jacobian_det_S1(q: numpy.ndarray) → tuple[float, numpy.ndarray][source]#: See Transformation.log_jacobian_det_S1().

_n_parameters = 1[source]#

class transformations.ScaledTransformation(coefficient: list | float | numpy.ndarray, intercept: list | float | numpy.ndarray = 0, n_parameters: int = 1)[source]#

Bases: pybop.Transformation

This class implements a linear transformation between the model parameter space and a search space, using a coefficient (scale factor) and an intercept (offset). It extends the base Transformation class.

The transformation is defined as: - to_search: y = coefficient * (x + intercept) - to_model: x = y / coefficient - intercept

Where: - x is in the model parameter space - y is in the search space - coefficient is the scaling factor - intercept is the offset

This transformation is useful for scaling and shifting parameters to a more suitable range for optimisation algorithms.

Based on pints.ScaledTransformation class.

_transform(x: numpy.ndarray, method: str) → numpy.ndarray[source]#: See Transformation._transform().

is_elementwise() → bool[source]#: See Transformation.is_elementwise().

jacobian(q: numpy.ndarray) → numpy.ndarray[source]#: See Transformation.jacobian().

jacobian_S1(q: numpy.ndarray) → tuple[numpy.ndarray, numpy.ndarray][source]#: See Transformation.jacobian_S1().

log_jacobian_det(q: numpy.ndarray) → float[source]#: See Transformation.log_jacobian_det().

log_jacobian_det_S1(q: numpy.ndarray) → tuple[float, numpy.ndarray][source]#: See Transformation.log_jacobian_det_S1().

_n_parameters = 1[source]#

coefficient[source]#

intercept[source]#

inverse_coeff[source]#

class transformations.UnitHyperCube(lower: float | list | numpy.ndarray, upper: float | list | numpy.ndarray)[source]#

Bases: ScaledTransformation

A class that implements a linear transformation between the model parameter space and a normalized search space (unit hypercube), using an inverse scale factor.

This transformation maps the input parameters from a given range [lower, upper] to a unit range [0, 1].

Initially based on pints.UnitCubeTransformation method.

Parameters:

lower (float or array-like of shape (n,)) – The lower bound(s) of the model parameter space.
upper (float or array-like of shape (n,)) – The upper bound(s) of the model parameter space.

lower[source]#

The lower bound of the input space for each parameter.

Type:: np.ndarray

upper[source]#

The upper bound of the input space for each parameter.

Type:: np.ndarray

coeff[source]#

The scaling coefficient (1 / (upper - lower)) for each parameter.

Type:: np.ndarray

inter[source]#

The intercept (-lower) to shift the input parameters.

Type:: np.ndarray

coeff[source]#

inter[source]#

lower[source]#

upper[source]#