# gluonts.distribution.box_cox_tranform module¶

class gluonts.distribution.box_cox_tranform.BoxCoxTranform(lambda_1: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], lambda_2: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], tol_lambda_1: float = 0.01, F=None)[source]

Implements Box-Cox transformation of a uni-variate random variable. The Box-Cox transformation of an observation $$z$$ is given by

$\begin{split}BoxCox(z; \lambda_1, \lambda_2) = \begin{cases} ((z + \lambda_2)^{\lambda_1} - 1) / \lambda_1, \quad & \text{if } \lambda_1 \neq 0, \\ \log (z + \lambda_2), \quad & \text{otherwise.} \end{cases}\end{split}$

Here, $$\lambda_1$$ and $$\lambda_2$$ are learnable parameters. Note that the domain of the transformation is not restricted.

For numerical stability, instead of checking $$\lambda_1$$ is exactly zero, we use the condition

$|\lambda_1| < tol\_lambda\_1$

for a pre-specified tolerance tol_lambda_1.

Inverse of the Box-Cox Transform is given by

$\begin{split}BoxCox^{-1}(y; \lambda_1, \lambda_2) = \begin{cases} (y \lambda_1 + 1)^{(1/\lambda_1)} - \lambda_2, \quad & \text{if } \lambda_1 \neq 0, \\ \exp (y) - \lambda_2, \quad & \text{otherwise.} \end{cases}\end{split}$

Notes on numerical stability:

1. For the forward transformation, $$\lambda_2$$ must always be chosen such that

$z + \lambda_2 > 0.$

To achieve this one needs to know a priori the lower bound on the observations. This is set in BoxCoxTransformOutput, since $$\lambda_2$$ is learnable.

2. Similarly for the inverse transformation to work reliably, a sufficient condition is

$y \lambda_1 + 1 \geq 0,$

where $$y$$ is the input to the inverse transformation.

This cannot always be guaranteed especially when $$y$$ is a sample from a transformed distribution. Hence we always truncate $$y \lambda_1 + 1$$ at zero.

An example showing why this could happen in our case: consider transforming observations from the unit interval (0, 1) with parameters

\begin{split}\begin{align} \lambda_1 = &\ 1.1, \\ \lambda_2 = &\ 0. \end{align}\end{split}

Then the range of the transformation is (-0.9090, 0.0). If Gaussian is fit to the transformed observations and a sample is drawn from it, then it is likely that the sample is outside this range, e.g., when the mean is close to -0.9. The subsequent inverse transformation of the sample is not a real number anymore.

>>> y = -0.91
>>> lambda_1 = 1.1
>>> lambda_2 = 0.0
>>> (y * lambda_1 + 1) ** (1 / lambda_1) + lambda_2
(-0.0017979146510711471+0.0005279153735965289j)

Parameters: lambda_1 – lambda_2 – tol_lambda_1 – For numerical stability, treat lambda_1 as zero if it is less than tol_lambda_1 F –
arg_names = ['box_cox.lambda_1', 'box_cox.lambda_2']
args

List – current values of the parameters

event_dim
f(z: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol]) → Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol][source]

Forward transformation of observations z

Parameters: z – observations Transformed observations Tensor
f_inv(y: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol]) → Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol][source]

Inverse of the Box-Cox Transform

Parameters: y – Transformed observations Observations Tensor
log_abs_det_jac(z: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], y: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol] = None) → Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol][source]

Logarithm of the absolute value of the Jacobian determinant corresponding to the Box-Cox Transform is given by

$\begin{split}\log \frac{d}{dz} BoxCox(z; \lambda_1, \lambda_2) = \begin{cases} \log (z + \lambda_2) (\lambda_1 - 1), \quad & \text{if } \lambda_1 \neq 0, \\ -\log (z + \lambda_2), \quad & \text{otherwise.} \end{cases}\end{split}$

Note that the derivative of the transformation is always non-negative.

Parameters: z – observations y – not used Tensor
sign

Return the sign of the Jacobian’s determinant.

class gluonts.distribution.box_cox_tranform.BoxCoxTransformOutput(lb_obs: float = 0.0, fix_lambda_2: bool = True)[source]
args_dim = {'box_cox.lambda_1': 1, 'box_cox.lambda_2': 1}
bij_cls

alias of BoxCoxTranform

domain_map(F, *args) → Tuple[Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], ...][source]
event_shape
class gluonts.distribution.box_cox_tranform.InverseBoxCoxTransform(lambda_1: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], lambda_2: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], tol_lambda_1: float = 0.01, F=None)[source]

Implements the inverse of Box-Cox transformation as a bijection.

arg_names = ['box_cox.lambda_1', 'box_cox.lambda_2']
event_dim
class gluonts.distribution.box_cox_tranform.InverseBoxCoxTransformOutput(lb_obs: float = 0.0, fix_lambda_2: bool = True)[source]
args_dim = {'box_cox.lambda_1': 1, 'box_cox.lambda_2': 1}
bij_cls

alias of InverseBoxCoxTransform

event_shape