biogeme.expressions.base_expressions module

Arithmetic expressions accepted by Biogeme: generic class

author:: Michel Bierlaire
date:: Sat Sep 9 15:25:07 2023

class biogeme.expressions.base_expressions.Expression[source]

Bases: object

This is the general arithmetic expression in biogeme. It serves as a base class for concrete expressions.

audit(database=None)[source]

Performs various checks on the expressions.

Parameters:: database (Database) – database object
Returns:: tuple list_of_errors, list_of_warnings
Return type:: list(string), list(string)

central_controller: Central controller for the multiple expressions

change_init_values(betas)[source]

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.

check_draws()[source]

Set of draws defined outside of ‘MonteCarlo’

Return type:: set[str]
Returns:: List of names of variables

check_panel_trajectory()[source]

Set of variables defined outside of ‘PanelLikelihoodTrajectory’

Return type:: set[str]
Returns:: List of names of variables

check_rv()[source]

Set of random variables defined outside of ‘Integrate’

Return type:: set[str]
Returns:: List of names of variables

children: List of children expressions

configure_catalogs(configuration)[source]

Select the items in each catalog corresponding to the requested configuration

Parameters:: configuration (Configuration) – catalog configuration

contains_catalog(name)[source]

Check if the expression contains a specific catalog

Parameters:: name (str) – name of the catalog to search.
Returns:: True if the given catalog is contained in the expression. False otherwise.
Return type:: bool

countPanelTrajectoryExpressions()[source]

Warning

This function is deprecated. Use count_panel_trajectory_expressions() instead.

Kept for backward compatibility

Return type:: int

count_panel_trajectory_expressions()[source]

Count the number of times the PanelLikelihoodTrajectory is used in the formula. It should trigger an error if it is used more than once.

Returns:: number of times the PanelLikelihoodTrajectory is used in the formula
Return type:: int

createFunction(database=None, number_of_draws=1000, gradient=True, hessian=True, bhhh=False)[source]

Warning

This function is deprecated. Use create_function() instead.

Kept for backward compatibility

Return type:

Callable[[ndarray], float | BiogemeFunctionOutput]

Parameters:

database (Database | None)
number_of_draws (int)
gradient (bool)
hessian (bool)
bhhh (bool)

create_function(database=None, number_of_draws=1000, gradient=True, hessian=True, bhhh=False)[source]

Create a function based on the expression. The function takes as argument an array for the free parameters, and return the value of the function, the gradient, the hessian and the BHHH. The calculation of the derivatives is optional.

Parameters:

database (Database) – database. If no database is provided, the expression must not contain any variable.
number_of_draws (int) – number of draws if needed by Monte-Carlo integration.
gradient (bool) – if True, the gradient is calculated.
hessian (bool) – if True, the hessian is calculated.
bhhh (bool) – if True, the BHHH matrix is calculated.

Returns:

the function. It will return, in that order, the value of the function, the gradient, the hessian and the BHHH matrix. Only requested quantities will be returned. For instance, if the gradient and the BHHH matrix are requested, and not the hessian, the tuple that is returned is f, g, bhhh.

Return type:

fct(np.array)

Raises:

BiogemeError – if gradient is False and hessian or BHHH is True.

create_objective_function(database=None, number_of_draws=1000, gradient=True, hessian=True, bhhh=False)[source]

Create a function based on the expression that complies with the interface of the biogeme_optimization model. The function takes as argument an array for the free parameters, and return the value of the function, the gradient, the hessian and the BHHH. The calculation of the derivatives is optional.

Parameters:

database (Database) – database. If no database is provided, the expression must not contain any variable.
number_of_draws (int) – number of draws if needed by Monte-Carlo integration.
gradient (bool) – if True, the gradient is calculated.
hessian (bool) – if True, the hessian is calculated.
bhhh (bool) – if True, the BHHH matrix is calculated.

Returns:

the function object.

Return type:

FunctionToMinimize

Raises:

BiogemeError – if gradient is False and hessian or BHHH is True.

current_configuration()[source]

Obtain the current configuration of an expression

Returns:: configuration
Return type:: Configuration

dict_of_catalogs(ignore_synchronized=False)[source]

Returns a dict with all catalogs in the expression.

Return type:: dict[str, Catalog]
Returns:: dict with all the catalogs
Parameters:: ignore_synchronized (bool)

dict_of_draw_types()[source]

Extract a dict containing the types of draws involved in the expression

Return type:: dict[slice(<class ‘str’>, <class ‘str’>, None)]

dict_of_elementary_expression(the_type)[source]

Extract a dict with all elementary expressions of a specific type

Parameters:: the_type (TypeOfElementaryExpression) – the type of expression
Returns:: returns a dict with the variables appearing in the expression the keys being their names.
Return type:: dict(string:biogeme.expressions.Expression)

embedExpression(t)[source]

Warning

This function is deprecated. Use embed_expression() instead.

Kept for backward compatibility

Return type:: bool
Parameters:: t (str)

embed_expression(t)[source]

Check if the expression contains an expression of type t.

Typically, this would be used to check that a MonteCarlo expression contains a bioDraws expression.

Returns:: True if the expression contains an expression of type t.
Return type:: bool
Parameters:: t (str)

fix_betas(beta_values, prefix=None, suffix=None)[source]

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.

fixedBetaValues: values of the Beta that are not estimated

getClassName()[source]

Warning

This function is deprecated. Use get_class_name() instead.

Kept for backward compatibility

Return type:: str

getElementaryExpression(name)[source]

Warning

This function is deprecated. Use get_elementary_expression() instead.

Kept for backward compatibility

Return type:: Elementary | None
Parameters:: name (str)

getSignature()[source]

Warning

This function is deprecated. Use get_signature() instead.

Kept for backward compatibility

Return type:: list[bytes]

getStatusIdManager()[source]

Warning

This function is deprecated. Use get_status_id_manager() instead.

Kept for backward compatibility

Return type:: tuple[set[str], set[str]]

getValue()[source]

Warning

This function is deprecated. Use get_value() instead.

Kept for backward compatibility

Return type:: float

getValueAndDerivatives(betas=None, database=None, number_of_draws=1000, gradient=True, hessian=True, bhhh=True, aggregation=True, prepare_ids=False)[source]

Warning

This function is deprecated. Use get_value_and_derivatives() instead.

Kept for backward compatibility

Return type:

ndarray | FunctionOutput

Parameters:

betas (dict[str, float] | None)
database (Database | None)
number_of_draws (int)
gradient (bool)
hessian (bool)
bhhh (bool)
aggregation (bool)
prepare_ids (bool)

getValue_c(database=None, betas=None, number_of_draws=1000, aggregation=False, prepare_ids=False)[source]

Warning

This function is deprecated. Use get_value_c() instead.

Kept for backward compatibility

Parameters:

database (Database | None)
betas (dict[str, float] | None)
number_of_draws (int)
aggregation (bool)
prepare_ids (bool)

get_all_controllers()[source]

Provides all controllers controlling the specifications of a multiple expression

Returns:: a set of controllers
Return type:: set(Controller)

get_beta_values()[source]

Returns a dict with the initial values of Beta. Typically: useful for simulation.

Returns:: dict with the initial values of the Beta
Return type:: dict(str: float)

get_children()[source]

Retrieve the list of children

Returns:: list of children
Return type:: list(Expression)

get_class_name()[source]

Obtain the name of the top class of the expression structure

Returns:: the name of the class
Return type:: string

get_elementary_expression(name)[source]

Return: an elementary expression from its name if it appears in the expression.

Parameters:: name (string) – name of the elementary expression.
Returns:: the expression if it exists. None otherwise.
Return type:: biogeme.expressions.Expression

get_id()[source]

Retrieve the id of the expression used in the signature

Returns:: id of the object
Return type:: int

get_signature()[source]

The signature of a string characterizing an expression.

This is designed to be communicated to C++, so that the expression can be reconstructed in this environment.

The list contains the following elements:

the signatures of all the children expressions,

the name of the expression between < >

the id of the expression between { }

the number of children between ( )

the ids of each children, preceeded by a comma.

Consider the following expression:

\[2 \beta_1 V_1 - \frac{\exp(-\beta_2 V_2) } { \beta_3 (\beta_2 \geq \beta_1)}.\]

It is defined as:

2 * beta1 * Variable1 - expressions.exp(-beta2*Variable2) /
     (beta3 * (beta2 >= beta1))

And its signature is:

[b'<Numeric>{4780527008},2',
 b'<Beta>{4780277152}"beta1"[0],0,0',
 b'<Times>{4780526952}(2),4780527008,4780277152',
 b'<Variable>{4511837152}"Variable1",5,2',
 b'<Times>{4780527064}(2),4780526952,4511837152',
 b'<Beta>{4780277656}"beta2"[0],1,1',
 b'<UnaryMinus>{4780527120}(1),4780277656',
 b'<Variable>{4511837712}"Variable2",6,3',
 b'<Times>{4780527176}(2),4780527120,4511837712',
 b'<exp>{4780527232}(1),4780527176',
 b'<Beta>{4780277264}"beta3"[1],2,0',
 b'<Beta>{4780277656}"beta2"[0],1,1',
 b'<Beta>{4780277152}"beta1"[0],0,0',
 b'<GreaterOrEqual>{4780527288}(2),4780277656,4780277152',
 b'<Times>{4780527344}(2),4780277264,4780527288',
 b'<Divide>{4780527400}(2),4780527232,4780527344',
 b'<Minus>{4780527456}(2),4780527064,4780527400']

Returns:: list of the signatures of an expression and its children.
Return type:: list(string)

get_status_id_manager()[source]

Check the elementary expressions that are associated with an ID manager.

Return type:: tuple[set[str], set[str]]
Returns:: two sets of elementary expressions, those with and without an ID manager.

get_value()[source]

Abstract method

Return type:: float

get_value_and_derivatives(betas=None, database=None, number_of_draws=1000, gradient=True, hessian=True, bhhh=True, aggregation=True, prepare_ids=False, named_results=False)[source]

Evaluation of the expression

In Biogeme the complexity of some expressions requires a specific implementation, in C++. This function invokes the C++ code to evaluate the value of the expression for a series of entries in a database. Note that this function will generate draws if needed.

Parameters:

betas (list(float)) – values of the free parameters
database (Database) – database. If no database is provided, the expression must not contain any variable.
number_of_draws (int) – number of draws if needed by Monte-Carlo integration.
gradient (bool) – If True, the gradient is calculated.
hessian (bool) – if True, the hessian is calculated.
bhhh (bool) – if True, the BHHH matrix is calculated.
aggregation (bool) – if a database is provided, and this parameter is True, the expression is applied on each entry of the database, and all values are aggregated, so that the sum is returned. If False, the list of all values is returned.
prepare_ids (bool) – if True, it means that the IDs of the expression must be constructed before the evaluation of the expression.
named_results (bool) – if True, the gradients, hessians, etc. are reported as dicts associating the names of the variables with their corresponding entry.

Returns:

if a database is provided, a list where each entry is the result of applying the expression on one entry of the database. It returns a float, a vector, and a matrix, depending if derivatives are requested.

Return type:

np.array or float, numpy.array, numpy.array

Raises:

BiogemeError – if no database is given and the expressions involves variables.
BiogemeError – if gradient is False and hessian or BHHH is True.
BiogemeError – if derivatives are asked, and the expression is not simple.
BiogemeError – if the expression involves MonteCarlo integration, and no database is provided.

get_value_c(database=None, betas=None, number_of_draws=1000, aggregation=False, prepare_ids=False)[source]

Evaluation of the expression, without the derivatives

Parameters:

betas (list(float)) – values of the free parameters
database (Database) – database. If no database is provided, the expression must not contain any variable.
number_of_draws (int) – number of draws if needed by Monte-Carlo integration.
aggregation (bool) – if a database is provided, and this parameter is True, the expression is applied on each entry of the database, and all values are aggregated, so that the sum is returned. If False, the list of all values is returned.
prepare_ids (bool) – if True, it means that the IDs of the expression must be constructed before the evaluation of the expression.

Returns:

if a database is provided, a list where each entry is the result of applying the expression on one entry of the database. It returns a float.

Return type:

np.array or float

Raises:

BiogemeError – if no database is given, and the number of returned values is different from one.

id_manager: in charge of the IDs

keep_id_manager: a copy of the ID manager

missingData: Value interpreted as missing data

numberOfDraws: number of draws for Monte Carlo integration

number_of_multiple_expressions()[source]

Reports the number of multiple expressions available through the iterator

Returns:: number of multiple expressions
Return type:: int

prepare(database, number_of_draws)[source]

Prepare the expression to be evaluated

Parameters:

database (Database) – Biogeme database
number_of_draws (int) – number of draws for Monte-Carlo integration

Return type:

None

rename_elementary(names, prefix=None, suffix=None)[source]

Rename elementary expressions by adding a prefix and/or a suffix

Parameters:

names (list(str)) – names of expressions to rename
prefix (str) – if not None, the expression is renamed, with a prefix defined by this argument.
suffix (str) – if not None, the expression is renamed, with a suffix defined by this argument.

requiresDraws()[source]

Warning

This function is deprecated. Use requires_draws() instead.

Kept for backward compatibility

Return type:: bool

requires_draws()[source]

Checks if the expression requires draws

Returns:: True if it requires draws.
Return type:: bool

reset_expression_selection()[source]

In each group of expressions, select the first one

Return type:: None

select_expression(controller_name, index)[source]

Select a specific expression in a group

Parameters:

controller_name (str) – name of the controller
index (int) – index of the expression in the group

Raises:

BiogemeError – if index is out of range

setIdManager(id_manager)[source]

Warning

This function is deprecated. Use set_id_manager() instead.

Kept for backward compatibility

Return type:: None
Parameters:: id_manager (IdManager | None)

set_central_controller(the_central_controller=None)[source]

For multiple expressions, defines the central controller

Return type:: CentralController
Parameters:: the_central_controller (CentralController)

set_id_manager(id_manager)[source]

The ID manager contains the IDs of the elementary expressions.

It is externally created, as it may nee to coordinate the numbering of several expressions. It is stored only in the expressions of type Elementary.

Parameters:: id_manager (class IdManager) – ID manager to be propagated to the elementary expressions. If None, all the IDs are set to None.
Return type:: None

set_of_configurations()[source]

Provides the set of all possible configurations

Return type:: set[str]

set_of_elementary_expression(the_type)[source]

Extract a set with all elementary expressions of a specific type

Parameters:: the_type (TypeOfElementaryExpression) – the type of expression
Return type:: set[str]
Returns:: returns a set with the names of the elementary expressions

set_of_multiple_expressions()[source]

Set of the multiple expressions found in the current expression

Returns:: a set of descriptions of the multiple expressions
Return type:: set(MultipleExpressionDescription)