biogeme.expressions.boxcox module

Arithmetic expressions accepted by Biogeme: BoxCox

Michel Bierlaire Mon Nov 03 2025, 17:16:46

class biogeme.expressions.boxcox.BoxCox(x, ell)

Bases: BinaryOperator

Box–Cox transform with McLaurin expansion near \(\ell = 0\).

\[B(x, \ell) = \frac{x^{\ell} - 1}{\ell}\]

with the limit

\[\lim_{\ell \to 0} B(x, \ell) = \log(x).\]

To avoid numerical issues, we use a McLaurin expansion for small \(\ell\):

\[\log(x) + \ell \log(x)^2 + \frac{1}{6} \ell^2 \log(x)^3 + \frac{1}{24} \ell^3 \log(x)^4.\]

and a special case \(B(0, \ell) = 0\).

This class reproduces the behaviour of boxcox_old but implements the piecewise logic with JAX / PyTensor control flow instead of Elem, so it is compatible with JAX and PyMC backends.

Parameters:

• x (Expression)

• ell (Expression)

deep_flat_copy()

Provides a copy of the expression. It is deep in the sense that it generates copies of the children. It is flat in the sense that any MultipleExpression is transformed into the currently selected expression. The flat part is irrelevant for this expression.

Return type:

BoxCox

get_value()

Evaluate the Box–Cox transform for scalar values.

• If x == 0, returns 0.0.

• If |ell| < 1e-5, uses the McLaurin expansion around ell = 0.

• Otherwise, uses the standard Box–Cox formula.

Return type:

float

Returns:

Scalar value of the Box–Cox transform.

recursive_construct_jax_function(numerically_safe)

JAX implementation of the Box–Cox transform.

Uses: - regular formula when |ell| >= 1e-5, - McLaurin expansion when |ell| < 1e-5, - value 0.0 when x == 0.

Return type:

Callable[[Array, Array, Array, Array], array]

Parameters:

numerically_safe (bool)

recursive_construct_pymc_model_builder()

PyTensor implementation of the Box–Cox transform, mirroring the original boxcox_old piecewise logic with pt.switch.

Return type:

PymcModelBuilderType