biogeme.expressions.beta_parameters module

Representation of unknown parameters

author:

Michel Bierlaire

date:

Sat Apr 20 14:54:16 2024

class biogeme.expressions.beta_parameters.Beta(name, value, lowerbound, upperbound, status, sigma_prior=5.0, prior=None)

Bases: Elementary

Unknown parameters to be estimated from data.

Parameters:

• name (str)

• value (float)

• lowerbound (float | None)

• upperbound (float | None)

• status (int)

• sigma_prior (float)

• prior (PriorFactory | None)

change_init_values(betas)

Modifies the initial values of the Beta parameters.

The fact that the parameters are fixed or free is irrelevant here.

Parameters:

betas (dict(string:float)) – dictionary where the keys are the names of the parameters, and the values are the new value for the parameters.

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:

Beta

property expression_type: TypeOfElementaryExpression

Type of elementary expression

fix_betas(beta_values, prefix=None, suffix=None)

Fix all the values of the Beta parameters appearing in the dictionary

Parameters:

• beta_values (dict(str: float)) – dictionary containing the betas to be fixed (as key) and their value.

• prefix (str) – if not None, the parameter is renamed, with a prefix defined by this argument.

• suffix (str) – if not None, the parameter is renamed, with a suffix defined by this argument.

get_value()

Calculates the value of the expression if it is simple

Return type:

float

property is_fixed

property is_free

recursive_construct_jax_function(numerically_safe)

Returns a compiled JAX-compatible function that extracts the beta value from the parameter vector using its unique index.

Return type:

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

Parameters:

numerically_safe (bool)

recursive_construct_pymc_model_builder()

Build a PyMC node for a Beta parameter: - If free: return the (scalar) RV named self.name (create it if missing). - If fixed: return a scalar constant tensor (no named var collision).

Return type:

PymcModelBuilderType

property safe_beta_id: int

Check the presence of the ID before using it

class biogeme.expressions.beta_parameters.PriorFactory(*args, **kwargs)

Bases: Protocol

Protocol for user-defined priors used with Beta.

A prior factory is a callable that receives:

Parameters:

• name – The PyMC name of the parameter (string).

• initial_value – The initial value provided by the Biogeme model.

• lower_bound – The lower bound of the truncation or None if no lower bound

• upper_bound – The upper bound of the truncation, or None if no upper bound.

and must return a PyMC distribution (RandomVariable) suitable as a prior for that parameter. The returned object must be a valid PyMC distribution node, not a sampled value.

Example

Below is an example of a custom prior that uses a Student-t distribution and truncates it to enforce negative support. This is useful for parameters such as cost or travel-time sensitivities, where the coefficient is known a priori to be negative.

import pymc as pm
from pytensor.tensor import TensorVariable

def negative_student_prior(
    name: str,
    initial_value: float,
    lower_bound: float | None,
    upper_bound: float | None,
) -> TensorVariable:
    base = pm.StudentT.dist(mu=0.0, sigma=10.0, nu=5.0)
    # Lower bound is ignored.
    # Upper bound is enforced to 0, provided or not.
    upper = 0.0 if upper_bound is None else min(0.0, upper_bound)
    return pm.Truncated(
        name=name,
        dist=base,
        upper=upper,
        initval=initial_value,
    )

This function can then be passed to Beta as:

b_cost = Beta(
    'b_cost',
    value=-1.0,
    lowerbound=None,
    upperbound=None,
    status=0,
    prior=negative_student_prior,
)