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.
- changeInitValues(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.
- dictOfBetas(free=True, fixed=False)[source]
Extract the set of parameters from the expression. Overload the generic function.
- Parameters
free (bool) – if True, the free parameters are included. Default: True.
fixed (bool) – if True, the fixed parameters are included. Default: False.
- Returns
a dict with the beta parameters appearing in the expression, the keys being the names of the parameters.
- 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 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.
- setOfBetas(free=True, fixed=False)[source]
Extract the set of parameters from the expression. Overload the generic function.
- Parameters
free (bool) – if True, the free parameters are included. Default: True.
fixed (bool) – if True, the fixed parameters are included. Default: False.
- Returns
returns a set with the beta parameters appearing in the expression.
- Return type
- 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 – formula that defines the variable
type – biogeme.expressions.Expression
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.
- __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
- 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 listOfErrors, listOfWarnings
- Return type
list(string), list(string)
- changeInitValues(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
- 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.
- dictOfBetas(free=True, fixed=False)[source]
Extract the set of parameters from the expression.
- Parameters
free (bool) – if True, the free parameters are included. Default: True.
fixed (bool) – if True, the fixed parameters are included. Default: False.
- Returns
a dict with the beta parameters appearing in the expression, the keys being the names of the parameters.
- Return type
dict(string:biogeme.expressions.Expression)
- dictOfDraws()[source]
Recursively extract the random variables (draws for Monte-Carlo) appearing in the expression, and store them in a dictionary.
- Returns
dict where the keys are the random variables and the elements the type of draws
- Return type
dict(string:string)
- dictOfRandomVariables()[source]
Recursively extract the random variables appearing in the expression, and store them in a dictionary.
- Returns
returns a dict with the random variables appearing in the expression the keys being their names.
- Return type
dict(string:biogeme.expressions.Expression)
- dictOfVariables()[source]
Recursively extract the variables appearing in the expression, and store them in a dictionary.
- 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.
- 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
- prepare(database, numberOfDraws=1000)[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
- 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.
- setOfBetas(free=True, fixed=False)[source]
Extract the set of parameters from the expression.
- Parameters
free (bool) – if True, the free parameters are included. Default: True.
fixed (bool) – if True, the fixed parameters are included. Default: False.
- Returns
returns a set with the beta parameters appearing in the expression.
- Return type
- setOfVariables()[source]
Extract the set of variables used in the expression.
- Returns
returns a set with the variables appearing in the expression.
- Return type
- 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.
- 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 listOfErrors, listOfWarnings
- 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 listOfErrors, listOfWarnings
- 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 listOfErrors, listOfWarnings
- 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 listOfErrors, listOfWarnings
- 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)
- dictOfRandomVariables()[source]
Recursively extract the random variables appearing in the expression, and store them in a dictionary.
Overloads the generic function.
- Returns
returns a dict with the random 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 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.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 listOfErrors, listOfWarnings
- 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)
- dictOfVariables()[source]
Recursively extract the variables appearing in the expression, and store them in a dictionary.
Overload the generic function.
- Returns
returns a dict with the variables appearing in the expression the keys being their names. Here, it contains only one element.
- 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 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)
- dictOfDraws()[source]
Recursively extract the random variables (draws for Monte-Carlo). Overloads the generic function. appearing in the expression, and store them in a dictionary.
- Returns
dict where the keys are the random variables and the elements the type of draws. Here, contains only one element.
- Return type
dict(string:string)
- 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
- dictOfBetas(free=True, fixed=False)[source]
Extract the set of parameters from the expression.
- Parameters
free (bool) – if True, the free parameters are included. Default: True.
fixed (bool) – if True, the fixed parameters are included. Default: False.
- Returns
a dict with the beta parameters appearing in the expression, the keys being the names of the parameters.
- Return type
dict(string:biogeme.expressions.Expression)
- dictOfDraws()[source]
Recursively extract the random variables (draws for Monte-Carlo). Overloads the generic function. appearing in the expression, and store them in a dictionary.
- Returns
dict where the keys are the random variables and the elements the type of draws. Here, returns an empty dict.
- Return type
dict(string:string)
- dictOfRandomVariables()[source]
Recursively extract the random variables appearing in the expression, and store them in a dictionary.
- Returns
returns a dict with the random variables appearing in the expression the keys being their names.
- Return type
dict(string:biogeme.expressions.Expression)
- dictOfVariables()[source]
Recursively extract the variables appearing in the expression, and store them in a dictionary.
Overloads the generic function.
- 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
- setOfBetas(free=True, fixed=False)[source]
Extract the set of parameters from the expression.
- Parameters
free (bool) – if True, the free parameters are included. Default: True.
fixed (bool) – if True, the fixed parameters are included. Default: False.
- Returns
returns a set with the beta parameters appearing in the expression.
- Return type
- 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.
- 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]
Identifies if an object is numeric, that is int, float or bool.
- Parameters
obj (object) – any object
- Returns
True if the object is int, float or bool.
- Return type
bool
- class biogeme.expressions.log(child)[source]
Bases:
UnaryOperator
logarithm expression
- __init__(child)[source]
Constructor
- Parameters
child (biogeme.expressions.Expression) – first arithmetic expression