biogeme.expressions.elementary_expressions module

Arithmetic expressions accepted by Biogeme: elementary expressions

author:

Michel Bierlaire

date:

Tue Mar 7 18:38:21 2023

class biogeme.expressions.elementary_expressions.DefineVariable(name, expression, database)[source]

Bases: Variable

Warning

This expression is obsolete. Replace new_var = DefineVariable(‘NEW_VAR’, expression, database) by new_var = database.DefineVariable(‘NEW_VAR’, expression)

Parameters:
class biogeme.expressions.elementary_expressions.Elementary(name)[source]

Bases: Expression

Elementary expression.

It is typically defined by a name appearing in an expression. It can be a variable (from the database), or a parameter (fixed or to be estimated using maximum likelihood), a random variable for numerical integration, or Monte-Carlo integration.

Parameters:

name (str)

elementaryIndex

The id should be unique for all elementary expressions appearing in a given set of formulas.

get_elementary_expression(name)[source]
Returns:

an elementary expression from its name if it appears in the expression. None otherwise.

Return type:

biogeme.Expression

Parameters:

name (str)

get_status_id_manager()[source]

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

Returns:

two lists of elementary expressions, those with and without an ID manager.

Return type:

tuple(list(str), list(str))

name

name of the elementary expression

number_of_multiple_expressions()[source]

Count the number of “parallel” expressions

Returns:

the number of expressions

Return type:

int

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.

class biogeme.expressions.elementary_expressions.RandomVariable(name)[source]

Bases: Elementary

Random variable for numerical integration

Parameters:

name (str)

check_rv()[source]

Set of random variables defined outside of ‘Integrate’

Returns:

List of names of variables

Return type:

list(str)

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

Return type:

dict[slice(<class ‘str’>, <class ‘biogeme.expressions.elementary_expressions.Elementary’>, None)]

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:

  1. the name of the expression between < >

  2. the id of the expression between { }

  3. the name of the random variable,

  4. the unique ID, preceded by a comma,

  5. the ID of the random variable.

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)

Raises:

  • BiogemeError – if no id has been defined for elementary expression

  • BiogemeError – if no id has been defined for random variable

set_id_manager(id_manager=None)[source]

The ID manager contains the IDs of the elementary expressions.

It is externally created, as it may need 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.

class biogeme.expressions.elementary_expressions.Variable(name)[source]

Bases: Elementary

Explanatory variable

This represents the explanatory variables of the choice model. Typically, they come from the data set.

Parameters:

name (str)

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)

Raises:

  • BiogemeError – if no database is provided.

  • BiogemeError – if the name of the variable does not appear in the database.

check_panel_trajectory()[source]

Set of variables defined outside of ‘PanelLikelihoodTrajectory’

Returns:

List of names of variables

Return type:

list(str)

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

Return type:

dict[slice(<class ‘str’>, <class ‘biogeme.expressions.elementary_expressions.Elementary’>, None)]

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:

  1. the name of the expression between < >

  2. the id of the expression between { }

  3. the name of the variable,

  4. the unique ID, preceded by a comma.

  5. the variable ID, preceded 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)

Raises:

  • BiogemeError – if no id has been defined for elementary expression

  • BiogemeError – if no id has been defined for variable

set_id_manager(id_manager=None)[source]

The ID manager contains the IDs of the elementary expressions.

It is externally created, as it may need 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.

class biogeme.expressions.elementary_expressions.bioDraws(name, draw_type)[source]

Bases: Elementary

Draws for Monte-Carlo integration

Parameters:

  • name (str)

  • draw_type (str)

check_draws()[source]

Set of draws defined outside of ‘MonteCarlo’

Returns:

List of names of variables

Return type:

list(str)

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

Return type:

dict[str, Elementary]

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:

  1. the name of the expression between < >

  2. the id of the expression between { }, preceded by a comma

  3. the name of the draws

  4. the unique ID (preceded by a comma),

  5. the draw ID (preceded 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)

Raises:

  • BiogemeError – if no id has been defined for elementary expression

  • BiogemeError – if no id has been defined for draw

set_id_manager(id_manager=None)[source]

The ID manager contains the IDs of the elementary expressions.

It is externally created, as it may need 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.