pcntoolkit.math_functions.warp

Classes

WarpAffine	Affine warping function.
WarpBase	Base class for likelihood warping functions.
WarpBoxCox	Box-Cox warping function.
WarpCompose	Composition of multiple warping functions.
WarpLog	Logarithmic warping function.
WarpSinhArcsinh	Sin-hyperbolic arcsin warping function.

Functions

parseWarpString(→ WarpBase)

Parse a string into a WarpBase object.

Module Contents

class WarpAffine

Bases: WarpBase

Affine warping function.

Implements affine transformation y = a + b*x where:

• a: offset parameter

• b: scale parameter (constrained positive through exp transform)

df(x: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Compute derivative of affine warp.

Parameters:

• x (NDArray[np.float64]) – Input values

• params (NDArray[np.float64]) – Affine parameters [a, log(b)]

Returns:

Constant derivative b

Return type:

NDArray[np.float64]

f(x: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Apply affine warping.

Parameters:

• x (NDArray[np.float64]) – Input values

• params (NDArray[np.float64]) – Affine parameters [a, log(b)]

Returns:

a + b*x

Return type:

NDArray[np.float64]

invf(y: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Apply inverse affine warping.

Parameters:

• y (NDArray[np.float64]) – Input values

• params (NDArray[np.float64]) – Affine parameters [a, log(b)]

Returns:

(y - a)/b

Return type:

NDArray[np.float64]

n_params = 2

class WarpBase

Bases: abc.ABC

Base class for likelihood warping functions.

This class implements warping functions following Rios and Torab (2019) Compositionally-warped Gaussian processes [1]_.

All Warps must define the following methods:

• get_n_params(): Return number of parameters

• f(): Warping function (Non-Gaussian field -> Gaussian)

• invf(): Inverse warp

• df(): Derivatives

• warp_predictions(): Compute predictive distribution

References

[1]

Rios, G., & Tobar, F. (2019). Compositionally-warped Gaussian processes. Neural Networks, 118, 235-246. https://www.sciencedirect.com/science/article/pii/S0893608019301856

abstractmethod df(x: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Return the derivative of the warp, dw(x)/dx.

Parameters:

• x (NDArray[np.float64]) – Input values

• param (NDArray[np.float64]) – Warping parameters

Returns:

Derivative values

Return type:

NDArray[np.float64]

abstractmethod f(x: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Evaluate the warping function.

Maps non-Gaussian response variables to Gaussian variables.

Parameters:

• x (NDArray[np.float64]) – Input values to warp

• param (NDArray[np.float64]) – Warping parameters

Returns:

Warped values

Return type:

NDArray[np.float64]

get_n_params() → int

Return the number of parameters required by the warping function.

Returns:

Number of parameters

Return type:

int

Raises:

AssertionError – If warp function is not initialized

abstractmethod invf(y: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Evaluate the inverse warping function.

Maps Gaussian latent variables to non-Gaussian response variables.

Parameters:

• y (NDArray[np.float64]) – Input values to inverse warp

• param (NDArray[np.float64]) – Warping parameters

Returns:

Inverse warped values

Return type:

NDArray[np.float64]

warp_predictions(mu: numpy.typing.NDArray[numpy.float64], s2: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64], percentiles: List[float] | None = None) → Tuple[numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64]]

Compute warped predictions from a Gaussian predictive distribution.

Parameters:

• mu (NDArray[np.float64]) – Gaussian predictive mean

• s2 (NDArray[np.float64]) – Predictive variance

• param (NDArray[np.float64]) – Warping parameters

• percentiles (List[float], optional) – Desired percentiles of the warped likelihood, by default [0.025, 0.975]

Returns:

• median: Median of the predictive distribution

• pred_interval: Predictive interval(s)

Return type:

Tuple[NDArray[np.float64], NDArray[np.float64]]

n_params: int = 0

class WarpBoxCox

Bases: WarpBase

Box-Cox warping function.

Implements the Box-Cox transform with a single parameter (lambda): y = (sign(x) * abs(x) ** lambda - 1) / lambda

This follows the generalization in Bicken and Doksum (1981) JASA 76 and allows x to assume negative values.

References

[1]

Bickel, P. J., & Doksum, K. A. (1981). An analysis of transformations revisited. Journal of the American Statistical Association, 76(374), 296-311.

df(x: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Compute derivative of Box-Cox warp.

Parameters:

x (NDArray[np.float64]) – Input values params : NDArray[np.float64] Box-Cox parameter [log(lambda)]

Returns:

Derivative values

Return type:

NDArray[np.float64]

f(x: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Apply Box-Cox warping.

Parameters:

• x (NDArray[np.float64]) – Input values

• params (NDArray[np.float64]) – Box-Cox parameter [log(lambda)]

Returns:

Warped values

Return type:

NDArray[np.float64]

invf(y: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Apply inverse Box-Cox warping.

Parameters:

• y (NDArray[np.float64]) – Input values

• params (NDArray[np.float64]) – Box-Cox parameter [log(lambda)]

Returns:

Inverse warped values

Return type:

NDArray[np.float64]

n_params = 1

class WarpCompose(warps: List[WarpBase])

Bases: WarpBase

Composition of multiple warping functions.

Allows chaining multiple warps together. Warps are applied in sequence: y = warp_n(…warp_2(warp_1(x)))

Initialize composed warp.

Parameters:

warpnames (Optional[List[str]], optional) – List of warp class names to compose, by default None

Raises:

ValueError – If warpnames is None

df(x: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Compute derivative of composed warping functions.

Parameters:

• x (NDArray[np.float64]) – Input values

• param (NDArray[np.float64]) – Combined parameters for all warps

Return type:

Determinant of the Jacobian of the composed warping functions

f(x: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Apply composed warping functions.

Parameters:

• x (NDArray[np.float64]) – Input values

• param (NDArray[np.float64]) – Combined parameters for all warps

Returns:

Warped values after applying all transforms

Return type:

NDArray[np.float64]

invf(y: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Apply inverse composed warping functions.

Parameters:

• y (NDArray[np.float64]) – Input values

• param (NDArray[np.float64]) – Combined parameters for all warps

Returns:

Inverse warped values after applying all inverse transforms

Return type:

NDArray[np.float64]

n_params = 0

warps

class WarpLog

Bases: WarpBase

Logarithmic warping function.

Implements y = log(x) warping transformation.

df(x: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Compute derivative of logarithmic warp.

Parameters:

• x (NDArray[np.float64]) – Input values

• params (NDArray[np.float64]) – Not used for logarithmic warp

Returns:

1/x

Return type:

NDArray[np.float64]

f(x: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64] | None = None) → numpy.typing.NDArray[numpy.float64]

Apply logarithmic warping.

Parameters:

• x (NDArray[np.float64]) – Input values (must be strictly positive)

• params (Optional[NDArray[np.float64]], optional) – Not used for logarithmic warp, by default None

Returns:

log(x)

Return type:

NDArray[np.float64]

Raises:

ValueError – If input contains zero or negative values

invf(y: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64] | None = None) → numpy.typing.NDArray[numpy.float64]

Apply inverse logarithmic warping.

Parameters:

• y (NDArray[np.float64]) – Input values

• params (Optional[NDArray[np.float64]], optional) – Not used for logarithmic warp, by default None

Returns:

exp(y)

Return type:

NDArray[np.float64]

n_params = 0

class WarpSinhArcsinh

Bases: WarpBase

Sin-hyperbolic arcsin warping function.

Implements warping function y = sinh(b * arcsinh(x) - a) with two parameters:

• a: controls skew

• b: controls kurtosis (constrained positive through exp transform)

Properties:

• a = 0: symmetric

• a > 0: positive skew

• a < 0: negative skew

• b = 1: mesokurtic

• b > 1: leptokurtic

• b < 1: platykurtic

Uses alternative parameterization from Jones and Pewsey (2019) where: y = sinh(b * arcsinh(x) + epsilon * b) and a = -epsilon*b

References

[1]

Jones, M. C., & Pewsey, A. (2019). Sigmoid-type distributions: Generation and inference. Significance, 16(1), 12-15.

[2]

Jones, M. C., & Pewsey, A. (2009). Sinh-arcsinh distributions. Biometrika, 96(4), 761-780.

df(x: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Compute derivative of sinh-arcsinh warp.

Parameters:

• x (NDArray[np.float64]) – Input values

• params (NDArray[np.float64]) – Parameters [epsilon, log(b)]

Returns:

(b * cosh(b * arcsinh(x) - a)) / sqrt(1 + x^2)

Return type:

NDArray[np.float64]

f(x: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Apply sinh-arcsinh warping.

Parameters:

• x (NDArray[np.float64]) – Input values

• params (NDArray[np.float64]) – Parameters [epsilon, log(b)]

Returns:

sinh(b * arcsinh(x) - a)

Return type:

NDArray[np.float64]

invf(y: numpy.typing.NDArray[numpy.float64], param: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Apply inverse sinh-arcsinh warping.

Parameters:

• y (NDArray[np.float64]) – Input values

• params (NDArray[np.float64]) – Parameters [epsilon, log(b)]

Returns:

sinh((arcsinh(y) + a) / b)

Return type:

NDArray[np.float64]

n_params = 2

parseWarpString(warp_string: str) → WarpBase

Parse a string into a WarpBase object.

Parameters:

warp_string (str) – String of a warp name or a composition of warps