Expressions
Mathematical expressions
biogeme.expressions module
Defines the various arithmetic expressions accepted by Biogeme.
- author:
Michel Bierlaire
- date:
Tue Mar 26 16:47:49 2019
- class biogeme.expressions.And(left, right)[source]
Bases:
BinaryOperator
Logical and
- __init__(left, right)[source]
Constructor
- Parameters:
left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression
- class biogeme.expressions.Beta(name, value, lowerbound, upperbound, status)[source]
Bases:
Elementary
Unknown parameters to be estimated from data.
- __init__(name, value, lowerbound, upperbound, status)[source]
Constructor
- Parameters:
name (string) – name of the parameter.
value (float) – default value.
lowerbound (float) – if different from None, imposes a lower bound on the value of the parameter during the optimization.
upperbound (float) – if different from None, imposes an upper bound on the value of the parameter during the optimization.
status (int) – if different from 0, the parameter is fixed to its default value, and not modified by the optimization algorithm.
- Raises:
BiogemeError – if the first parameter is not a str.
BiogemeError – if the second parameter is not a int or a float.
- 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.
- 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)
- 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.
- getSignature()[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 name of the expression between < >
the id of the expression between { }
the name of the parameter,
the status between [ ]
the unique ID, preceeded by a comma
the beta ID, 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)
- Raises:
biogeme.exceptions.BiogemeError – if no id has been defined for elementary expression
biogeme.exceptions.BiogemeError – if no id has been defined for parameter
- getValue()[source]
Evaluates the value of the expression
- Returns:
value of the expression
- Return type:
float
- setIdManager(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.BinaryOperator(left, right)[source]
Bases:
Expression
Base class for arithmetic expressions that are binary operators. This expression is the result of the combination of two expressions, typically addition, substraction, multiplication or division.
- __init__(left, right)[source]
Constructor
- Parameters:
left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- left
left child
- right
right child
- class biogeme.expressions.ComparisonOperator(left, right)[source]
Bases:
BinaryOperator
Base class for comparison expressions.
- __init__(left, right)[source]
Constructor
- Parameters:
left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression
- class biogeme.expressions.DefineVariable(name, expression, database)[source]
Bases:
Variable
Expression that defines a new variable and add a column in the database.
This expression allows the use to define a new variable that will be added to the database. It avoids that it is recalculated each time it is needed.
- __init__(name, expression, database)[source]
Constructor
- Parameters:
name (string) – name of the variable.
expression (biogeme.expressions.Expression) – formula that defines the variable
database (biogeme.database.Database) – object identifying the database.
- Raises:
BiogemeError – if the expression is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- class biogeme.expressions.Derive(child, name)[source]
Bases:
UnaryOperator
Derivative with respect to an elementary expression
- __init__(child, name)[source]
Constructor
- Parameters:
child (biogeme.expressions.Expression) – first arithmetic expression
- getSignature()[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 the child expression,
the name of the expression between < >
the id of the expression between { }
the id of the child, 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)
- class biogeme.expressions.Divide(left, right)[source]
Bases:
BinaryOperator
Division expression
- __init__(left, right)[source]
Constructor
- Parameters:
left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression
- class biogeme.expressions.Elem(dictOfExpressions, keyExpression)[source]
Bases:
Expression
This returns the element of a dictionary. The key is evaluated from an expression and must return an integer, possibly negative.
- __init__(dictOfExpressions, keyExpression)[source]
Constructor
- Parameters:
dictOfExpressions (dict(int: biogeme.expressions.Expression)) – dict of objects with numerical keys.
keyExpression (biogeme.expressions.Expression) – object providing the key of the element to be evaluated.
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- dictOfExpressions
dict of expressions
- getSignature()[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 signature of the expression defining the key
the signatures of all the children expressions,
the name of the expression between < >
the id of the expression between { }
the number of elements between ( )
the id of the expression defining the key
for each element: the value of the key and the id of the expression, separated by commas.
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)
- getValue()[source]
Evaluates the value of the expression
- Returns:
value of the expression
- Return type:
float
- Raises:
BiogemeError – if the calcuated key is not present in the dictionary.
- keyExpression
expression for the key
- class biogeme.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 numrerical integration, or Monte-Carlo integration.
- elementaryIndex
The id should be unique for all elementary expressions appearing in a given set of formulas.
- getElementaryExpression(name)[source]
- Returns:
an elementary expression from its name if it appears in the expression. None otherwise.
- Return type:
biogeme.Expression
- getStatusIdManager()[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 expressiom
- 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.Equal(left, right)[source]
Bases:
ComparisonOperator
Logical equal
- __init__(left, right)[source]
Constructor
- Parameters:
left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression
- class biogeme.expressions.Expression[source]
Bases:
object
This is the general arithmetic expression in biogeme. It serves as a base class for concrete expressions.
- __add__(other)[source]
Operator overloading. Generate an expression for addition.
- Parameters:
other (biogeme.expressions.Expression) – expression to be added
- Returns:
self + other
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __and__(other)[source]
Operator overloading. Generate an expression for logical and.
- Parameters:
other (biogeme.expressions.Expression) – expression for logical and
- Returns:
self and other
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __div__(other)[source]
Operator overloading. Generate an expression for division.
- Parameters:
other (biogeme.expressions.Expression) – expression for division
- Returns:
self / other
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __eq__(other)[source]
Operator overloading. Generate an expression for comparison.
- Parameters:
other (biogeme.expressions.Expression) – expression for equality
- Returns:
self == other
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __ge__(other)[source]
Operator overloading. Generate an expression for comparison.
- Parameters:
other (biogeme.expressions.Expression) – expression for greater or equal
- Returns:
self >= other
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __gt__(other)[source]
Operator overloading. Generate an expression for comparison.
- Parameters:
other (biogeme.expressions.Expression) – expression for greater than
- Returns:
self > other
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __le__(other)[source]
Operator overloading. Generate an expression for comparison.
- Parameters:
other (biogeme.expressions.Expression) – expression for less or equal
- Returns:
self <= other
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __lt__(other)[source]
Operator overloading. Generate an expression for comparison.
- Parameters:
other (biogeme.expressions.Expression) – expression for less than
- Returns:
self < other
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __mul__(other)[source]
Operator overloading. Generate an expression for multiplication.
- Parameters:
other (biogeme.expressions.Expression) – expression to be multiplied
- Returns:
self * other
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __ne__(other)[source]
Operator overloading. Generate an expression for comparison.
- Parameters:
other (biogeme.expressions.Expression) – expression for difference
- Returns:
self != other
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __neg__()[source]
Operator overloading. Generate an expression for unary minus.
- Returns:
-self
- Return type:
- __or__(other)[source]
Operator overloading. Generate an expression for logical or.
- Parameters:
other (biogeme.expressions.Expression) – expression for logical or
- Returns:
self or other
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __pow__(other)[source]
Operator overloading. Generate an expression for power.
- Parameters:
other (biogeme.expressions.Expression) – expression for power
- Returns:
self ^ other
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __radd__(other)[source]
Operator overloading. Generate an expression for addition.
- Parameters:
other (biogeme.expressions.Expression) – expression to be added
- Returns:
other + self
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __rdiv__(other)[source]
Operator overloading. Generate an expression for division.
- Parameters:
other (biogeme.expressions.Expression) – expression for division
- Returns:
other / self
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __rmul__(other)[source]
Operator overloading. Generate an expression for multiplication.
- Parameters:
other (biogeme.expressions.Expression) – expression to be multiplied
- Returns:
other * self
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __rpow__(other)[source]
Operator overloading. Generate an expression for power.
- Parameters:
other (biogeme.expressions.Expression) – expression for power
- Returns:
other ^ self
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __rsub__(other)[source]
Operator overloading. Generate an expression for substraction.
- Parameters:
other (biogeme.expressions.Expression) – expression to be substracted
- Returns:
other - self
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __rtruediv__(other)[source]
Operator overloading. Generate an expression for division.
- Parameters:
other (biogeme.expressions.Expression) – expression for division
- Returns:
other / self
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __sub__(other)[source]
Operator overloading. Generate an expression for substraction.
- Parameters:
other (biogeme.expressions.Expression) – expression to substract
- Returns:
self - other
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- __truediv__(other)[source]
Operator overloading. Generate an expression for division.
- Parameters:
other (biogeme.expressions.Expression) – expression for division
- Returns:
self / other
- Return type:
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- audit(database=None)[source]
Performs various checks on the expressions.
- Parameters:
database (biogeme.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’
- Returns:
List of names of variables
- Return type:
set(str)
- check_panel_trajectory()[source]
Set of variables defined outside of ‘PanelLikelihoodTrajectory’
- Returns:
List of names of variables
- Return type:
set(str)
- check_rv()[source]
Set of random variables defined outside of ‘Integrate’
- Returns:
List of names of variables
- Return type:
set(str)
- children
List of children expressions
- configure_catalogs(configuration)[source]
Select the items in each catalog corresponding to the requested configuration
- Parameters:
configuration (biogeme.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]
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
- cpp
Interface to the C++ implementation
- createFunction(database=None, numberOfDraws=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 (biogeme.database.Database) – database. If no database is provided, the expression must not contain any variable.
numberOfDraws (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.
- current_configuration()[source]
Obtain the current configuration of an expression
- Returns:
configuration
- Return type:
- dict_of_catalogs(ignore_synchronized=False)[source]
Returns a dict with all catalogs in the expression.
- Returns:
dict with all the catalogs
- 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]
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
- 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]
Obtain the name of the top class of the expression structure
- Returns:
the name of the class
- Return type:
string
- getElementaryExpression(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:
- getSignature()[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)
- getStatusIdManager()[source]
Check the elementary expressions that are associated with an ID manager.
- Returns:
two sets of elementary expressions, those with and without an ID manager.
- Return type:
tuple(set(str), set(str))
- getValueAndDerivatives(betas=None, database=None, numberOfDraws=1000, gradient=True, hessian=True, bhhh=True, aggregation=True, prepareIds=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 (biogeme.database.Database) – database. If no database is provided, the expression must not contain any variable.
numberOfDraws (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.
prepareIds (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 dsatabase. It returns a float, a vector, and a matrix, depedending 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.
- getValue_c(database=None, betas=None, numberOfDraws=1000, aggregation=False, prepareIds=False)[source]
Evaluation of the expression, without the derivatives
- Parameters:
betas (list(float)) – values of the free parameters
database (biogeme.database.Database) – database. If no database is provided, the expression must not contain any variable.
numberOfDraws (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.
prepareIds (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 dsatabase. 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.
- get_all_controllers()[source]
Provides all controllers controlling the specifications of a multiple expression
- Returns:
a set of controllers
- Return type:
- 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_id()[source]
Retrieve the id of the expression used in the signature
- Returns:
id of the object
- Return type:
int
- 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, numberOfDraws)[source]
Prepare the expression to be evaluated
- Parameters:
database (biogeme.database.Database) – Biogeme database
numberOfDraws (int) – number of draws for Monte-Carlo integration
- 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]
Checks if the expression requires draws
- Returns:
True if it requires draws.
- Return type:
bool
- 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]
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.
- setRow(row)[source]
Obsolete function. This function identifies the row of the database from which the values of the variables must be obtained.
- Parameters:
row (pandas.core.series.Serie) – row from the database
- Raises:
BiogemeError – if the function is called, because it is obsolete.
- set_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 set with the names of the elementary expressions
- Return type:
set(string.Expression)
- class biogeme.expressions.Greater(left, right)[source]
Bases:
ComparisonOperator
Logical greater
- __init__(left, right)[source]
Constructor
- Parameters:
left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression
- class biogeme.expressions.GreaterOrEqual(left, right)[source]
Bases:
ComparisonOperator
Logical greater or equal
- __init__(left, right)[source]
Constructor
- Parameters:
left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression
- class biogeme.expressions.Integrate(child, name)[source]
Bases:
UnaryOperator
Numerical integration
- __init__(child, name)[source]
Constructor
- Parameters:
child (biogeme.expressions.Expression) – first arithmetic expression
name (string) – name of the random variable for the integration.
- audit(database=None)[source]
Performs various checks on the expressions.
- Parameters:
database (biogeme.database.Database) – database object
- Returns:
tuple list_of_errors, list_of_warnings
- Return type:
list(string), list(string)
- check_rv()[source]
List of random variables defined outside of ‘Integrate’
- Returns:
List of names of variables
- Return type:
list(str)
- getSignature()[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 the child expression,
the name of the expression between < >
the id of the expression between { }, preceeded by a comma
the id of the children, preceeded by a comma
the index of the randon variable, 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)
- class biogeme.expressions.Less(left, right)[source]
Bases:
ComparisonOperator
Logical less
- __init__(left, right)[source]
Constructor
- Parameters:
left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression
- class biogeme.expressions.LessOrEqual(left, right)[source]
Bases:
ComparisonOperator
Logical less or equal
- __init__(left, right)[source]
Constructor
- Parameters:
left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression
- class biogeme.expressions.LogLogit(util, av, choice)[source]
Bases:
Expression
Expression capturing the logit formula.
It contains one formula for the target alternative, a dict of formula for the availabilities and a dict of formulas for the utilities
- __init__(util, av, choice)[source]
Constructor
- Parameters:
util (dict(int:biogeme.expressions.Expression)) – dictionary where the keys are the identifiers of the alternatives, and the elements are objects defining the utility functions.
av (dict(int:biogeme.expressions.Expression)) – dictionary where the keys are the identifiers of the alternatives, and the elements are object of type biogeme.expressions.Expression defining the availability conditions. If av is None, all the alternatives are assumed to be always available
choice (biogeme.expressions.Expression) – formula to obtain the alternative for which the logit probability must be calculated.
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- audit(database=None)[source]
Performs various checks on the expressions.
- Parameters:
database (biogeme.database.Database) – database object
- Returns:
tuple list_of_errors, list_of_warnings
- Return type:
list(string), list(string)
- av
dict of availability formulas
- choice
expression for the chosen alternative
- getSignature()[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 alternatives between ( )
the id of the expression for the chosen alternative, preceeded by a comma.
for each alternative, separated by commas:
the number of the alternative, as defined by the user,
the id of the expression for the utility,
the id of the expression for the availability condition.
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)
- getValue()[source]
Evaluates the value of the expression
- Returns:
value of the expression
- Return type:
float
- Raises:
BiogemeError – if the chosen alternative does not correspond to any of the utility functions
BiogemeError – if the chosen alternative does not correspond to any of entry in the availability condition
- util
dict of utility functions
- class biogeme.expressions.Minus(left, right)[source]
Bases:
BinaryOperator
Substraction expression
- __init__(left, right)[source]
Constructor
- Parameters:
left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression
- class biogeme.expressions.MonteCarlo(child)[source]
Bases:
UnaryOperator
Monte Carlo integration
- __init__(child)[source]
Constructor
- Parameters:
child (biogeme.expressions.Expression) – arithmetic expression
- audit(database=None)[source]
Performs various checks on the expressions.
- Parameters:
database (biogeme.database.Database) – database object
- Returns:
tuple list_of_errors, list_of_warnings
- Return type:
list(string), list(string)
- class biogeme.expressions.NotEqual(left, right)[source]
Bases:
ComparisonOperator
Logical not equal
- __init__(left, right)[source]
Constructor
- Parameters:
left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression
- class biogeme.expressions.Numeric(value)[source]
Bases:
Expression
Numerical expression for a simple number
- getSignature()[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 name of the expression between < >
the id of the expression between { }
the value, 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)
- getValue()[source]
Evaluates the value of the expression
- Returns:
value of the expression
- Return type:
float
- value
numeric value
- class biogeme.expressions.Or(left, right)[source]
Bases:
BinaryOperator
Logical or
- __init__(left, right)[source]
Constructor
- Parameters:
left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression
- class biogeme.expressions.PanelLikelihoodTrajectory(child)[source]
Bases:
UnaryOperator
Likelihood of a sequences of observations for the same individual
- __init__(child)[source]
Constructor
- Parameters:
child (biogeme.expressions.Expression) – first arithmetic expression
- audit(database=None)[source]
Performs various checks on the expressions.
- Parameters:
database (biogeme.database.Database) – database object
- Returns:
tuple list_of_errors, list_of_warnings
- Return type:
list(string), list(string)
- class biogeme.expressions.Plus(left, right)[source]
Bases:
BinaryOperator
Addition expression
- __init__(left, right)[source]
Constructor
- Parameters:
left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression
- class biogeme.expressions.Power(left, right)[source]
Bases:
BinaryOperator
Power expression
- __init__(left, right)[source]
Constructor
- Parameters:
left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression
- class biogeme.expressions.RandomVariable(name)[source]
Bases:
Elementary
Random variable for numerical integration
- __init__(name)[source]
Constructor
- Parameters:
name (string.) – name of the random variable involved in the integration.
- check_rv()[source]
List 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
- getSignature()[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 name of the expression between < >
the id of the expression between { }
the name of the random variable,
the unique ID, preceeded by a comma,
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:
biogeme.exceptions.BiogemeError – if no id has been defined for elementary expression
biogeme.exceptions.BiogemeError – if no id has been defined for random variable
- setIdManager(id_manager=None)[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.
- class biogeme.expressions.SelectedExpressionsIterator(the_expression, configurations)[source]
Bases:
object
A multiple expression is an expression that contains Catalog. This iterator loops on pre-specified configurations
- __init__(the_expression, configurations)[source]
Ctor.
- Parameters:
the_expression (Expression) – expression containing Catalogs
configurations (set(biogeme.configuration.Configuration))) – set of configurations
- class biogeme.expressions.Times(left, right)[source]
Bases:
BinaryOperator
Multiplication expression
- __init__(left, right)[source]
Constructor
- Parameters:
left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression
- class biogeme.expressions.UnaryMinus(child)[source]
Bases:
UnaryOperator
Unary minus expression
- __init__(child)[source]
Constructor
- Parameters:
child (biogeme.expressions.Expression) – first arithmetic expression
- class biogeme.expressions.UnaryOperator(child)[source]
Bases:
Expression
Base class for arithmetic expressions that are unary operators.
Such an expression is the result of the modification of another expressions, typically changing its sign.
- __init__(child)[source]
Constructor
- Parameters:
child (biogeme.expressions.Expression) – first arithmetic expression
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
- child
child
- class biogeme.expressions.Variable(name)[source]
Bases:
Elementary
Explanatory variable
This represents the explanatory variables of the choice model. Typically, they come from the data set.
- audit(database=None)[source]
Performs various checks on the expressions.
- Parameters:
database (biogeme.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]
List 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
- getSignature()[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 name of the expression between < >
the id of the expression between { }
the name of the variable,
the unique ID, preceeded by a comma.
the variabvle ID, 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)
- Raises:
biogeme.exceptions.BiogemeError – if no id has been defined for elementary expression
biogeme.exceptions.BiogemeError – if no id has been defined for variable
- getValue()[source]
- The evaluation of a Variable requires a database. Therefore, this
function triggers an exception.
- Raises:
BiogemeError – each time the function is calles
- setIdManager(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.bioDraws(name, drawType)[source]
Bases:
Elementary
Draws for Monte-Carlo integration
- __init__(name, drawType)[source]
Constructor
- Parameters:
name (string) – name of the random variable with a series of draws.
drawType (string) – type of draws.
- check_draws()[source]
List 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 dpecific type
- Parameters:
the_type (TypeOfElementaryExpression) – the type of expression
- getSignature()[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 name of the expression between < >
the id of the expression between { }, preceeded by a comma
the name of the draws
the unique ID (preceeded by a comma),
the draw ID (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)
- Raises:
biogeme.exceptions.BiogemeError – if no id has been defined for elementary expression
biogeme.exceptions.BiogemeError – if no id has been defined for draw
- setIdManager(id_manager=None)[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.
- class biogeme.expressions.bioLinearUtility(listOfTerms)[source]
Bases:
Expression
When the utility function is linear, it is expressed as a list of terms, where a parameter multiplies a variable.
- __init__(listOfTerms)[source]
Constructor
- Parameters:
listOfTerms (list(biogeme.expressions.Expression, biogeme.expressions.Expression)) – a list of tuple. Each tuple contains first a beta parameter, second the name of a variable.
- Raises:
biogeme.exceptions.BiogemeError – if the object is not a list of tuples (parameter, variable)
- betas
list of parameters
- 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)
- getSignature()[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 terms in the utility ( )
for each term:
the id of the beta parameter
the unique id of the beta parameter
the name of the parameter
the id of the variable
the unique id of the variable
the name of the 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)
- listOfTerms
List of terms
- variables
list of variables
- class biogeme.expressions.bioMax(left, right)[source]
Bases:
BinaryOperator
Maximum of two expressions
- __init__(left, right)[source]
Constructor
- Parameters:
left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression
- class biogeme.expressions.bioMin(left, right)[source]
Bases:
BinaryOperator
Minimum of two expressions
- __init__(left, right)[source]
Constructor
- Parameters:
left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression
- class biogeme.expressions.bioMultSum(listOfExpressions)[source]
Bases:
Expression
This expression returns the sum of several other expressions.
It is a generalization of ‘Plus’ for more than two terms
- __init__(listOfExpressions)[source]
Constructor
- Parameters:
listOfExpressions (list(biogeme.expressions.Expression)) – list of objects representing the terms of the sum.
- Raises:
BiogemeError – if one of the expressions is invalid, that is neither a numeric value or a biogeme.expressions.Expression object.
BiogemeError – if the list of expressions is empty
BiogemeError – if the list of expressions is neither a dict or a list
- class biogeme.expressions.bioNormalCdf(child)[source]
Bases:
UnaryOperator
Cumulative Distribution Function of a normal random variable
- __init__(child)[source]
Constructor
- Parameters:
child (biogeme.expressions.Expression) – first arithmetic expression
- class biogeme.expressions.exp(child)[source]
Bases:
UnaryOperator
exponential expression
- __init__(child)[source]
Constructor
- Parameters:
child (biogeme.expressions.Expression) – first arithmetic expression
- biogeme.expressions.isNumeric(obj)[source]
Checks if an object is numeric :param obj: obj to be checked :type obj: Object
- class biogeme.expressions.log(child)[source]
Bases:
UnaryOperator
logarithm expression
- __init__(child)[source]
Constructor
- Parameters:
child (biogeme.expressions.Expression) – first arithmetic expression
- class biogeme.expressions.logzero(child)[source]
Bases:
UnaryOperator
logarithm expression. Returns zero if the argument is zero.
- __init__(child)[source]
Constructor
- Parameters:
child (biogeme.expressions.Expression) – first arithmetic expression
- biogeme.expressions.process_numeric(expression)[source]
Transforms a numeric value into an Expression object
- Parameters:
expression (Expression or numeric) – expression to process
- Raises:
BiogemeError – if expression is not of type expression