Package description¶

Biogeme is a open source Python package designed for the maximum likelihood estimation of parametric models in general, with a special emphasis on discrete choice models.

biogeme.biogeme module¶

Implementation of the main Biogeme class that combines the database and the model specification.

author: Michel Bierlaire
date: Tue Mar 26 16:45:15 2019

class biogeme.biogeme.BIOGEME(database, formulas, numberOfThreads=None, numberOfDraws=1000, seed=None, skipAudit=False, removeUnusedVariables=True, missingData=99999)¶

Bases: object

Main class that combines the database and the model specification.

It works in two modes: estimation and simulation.

__init__(database, formulas, numberOfThreads=None, numberOfDraws=1000, seed=None, skipAudit=False, removeUnusedVariables=True, missingData=99999)¶

Constructor

Parameters

database (biogeme.database) – choice data.
formulas (biogeme.expressions.Expression, or dict(biogeme.expressions.Expression)) – expression or dictionary of expressions that define the model specification. The concept is that each expression is applied to each entry of the database. The keys of the dictionary allow to provide a name to each formula. In the estimation mode, two formulas are needed, with the keys ‘loglike’ and ‘weight’. If only one formula is provided, it is associated with the label ‘loglike’. If no formula is labeled ‘weight’, the weight of each piece of data is supposed to be 1.0. In the simulation mode, the labels of each formula are used as labels of the resulting database.
numberOfThreads (int) – multi-threading can be used for estimation. This parameter defines the number of threads to be used. If the parameter is set to None, the number of available threads is calculated using cpu_count(). Ignored in simulation mode. Defaults: None.
numberOfDraws (int) – number of draws used for Monte-Carlo integration. Default: 1000.
seed (int) – seed used for the pseudo-random number generation. It is useful only when each run should generate the exact same result. If None, a new seed is used at each run. Default: None.
skipAudit (bool) – if True, does not check the validity of the formulas. It may save significant amount of time for large models and large data sets. Default: False.
removeUnusedVariables (bool) – if True, all variables not used in the expression are removed from the database. Default: True.
missingData (float) – if one variable has this value, it is assumed that a data is missing and an exception will be triggered. Default: 99999.

calculateInitLikelihood()¶

Calculate the value of the log likelihood function

The default values of the parameters are used.

Returns: value of the log likelihood.
Return type: float.

calculateLikelihood(x)¶

Calculates the value of the log likelihood function

Parameters: x (list(float)) – vector of values for the parameters.
Returns: the calculated value of the log likelihood
Return type: float.
Raises: ValueError – if the length of the list x is incorrect.

calculateLikelihoodAndDerivatives(x, hessian=False, bhhh=False)¶

Calculate the value of the log likelihood function and its derivatives.

Parameters

x (list(float)) – vector of values for the parameters.
hessian (bool) – if True, the hessian is calculated. Default: False.
bhhh (bool) – if True, the BHHH matrix is calculated. Default: False.

Returns

f, g, h, bh where

f is the value of the function (float)
g is the gradient (numpy.array)
h is the hessian (numpy.array)
bh is the BHHH matrix (numpy.array)

Return type

tuple float, numpy.array, numpy.array, numpy.array

Raises

ValueError – if the length of the list x is incorrect

cfsqp(betas, fixedBetas, betaIds, bounds, parameters)¶

Invokes the CFSQP algorithm for estimation

Parameters

betas (list of float) – initial values of the parameters to be estimated.
fixedBetas (list of float) – values of the parameters that are not estimated.
betaIds (list of int) – list of IDs of the beta to be estimated.
bounds (list of tuple) – lower and upper bounds on each parameter.
parameters (dict) –
user defined parameters for CFSQP
- mode=CBA: specifies job options as described below
  - A = 0: ordinary minimax problems
  - A = 1: ordinary minimax problems with each individual function replaced by its absolute value, ie, an L_infty problem
  - B = 0: monotone decrease of objective function after each iteration
  - B = 1: monotone decrease of objective function after at most four iterations
  - C = 1: default operation.
  - C= 2: requires that constraints always be evaluated before objectives during the line search.
- iprint: print level indicator with the following options
  - iprint=0: no normal output, only error information (this option is imposed during phase 1)
  - iprint=1: a final printout at a local solution
  - iprint=2: a brief printout at the end of each iteration
  - iprint=3: detailed infomation is printed out at the end of each iteration (for debugging purposes)
- miter: maximum number of iterations allowed by the user to solve the problem

checkDerivatives(verbose=False)¶

Verifies the implementation of the derivatives.

It compares the analytical version with the finite differences approximation.

Parameters

verbose (bool) – if True, the comparisons are reported. Default: False.

Return type

tuple.

Returns

f, g, h, gdiff, hdiff where

f is the value of the function,
g is the analytical gradient,
h is the analytical hessian,
gdiff is the difference between the analytical and the finite differences gradient,
hdiff is the difference between the analytical and the finite differences hessian,

confidenceIntervals(betaValues, intervalSize=0.9)¶

Calculate confidence intervals on the simulated quantities

Parameters

betaValues (list(dict(float))) – array of parameters values to be used in the calculations. Typically, it is a sample drawn from a distribution.
intervalSize (float) – size of the reported confidence interval, in percentage. If it is denoted by s, the interval is calculated for the quantiles (1-s)/2 and (1+s)/2. The default (0.9) corresponds to quantiles for the confidence interval [0.05,0.95].

Returns

two pandas data frames ‘left’ and ‘right’ with the same dimensions. Each row corresponds to a row in the database, and each column to a formula. ‘left’ contains the left value of the confidence interval, and ‘right’ the right value

Example:

# Read the estimation results from a file
results = res.bioResults(pickleFile='myModel.pickle')
# Retrieve the names of the betas parameters that have been estimated
betas = biogeme.freeBetaNames
# Draw 100 realization of the distribution of the estimators
b = results.getBetasForSensitivityAnalysis(betas, size=100)
# Simulate the formulas using the nominal values
simulatedValues = biogeme.simulate(betaValues)
# Calculate the confidence intervals for each formula
left, right = biogeme.confidenceIntervals(b, 0.9)

Return type

tuple of two Pandas dataframes.

createLogFile(level=3)¶

Creates a log file with the messages produced by Biogeme.

The name of the file is the name of the model with an extension .log

Parameters

level (int) –

types of messages to be captured

0: no output
1: warnings
2: only general information
3: more verbose
4: debug messages

Default: 3.

estimate(bootstrap=0, algorithm=<function scipy>, algoParameters=None, cfsqpDefaultBounds=1000.0)¶

Estimate the parameters of the model.

Parameters

bootstrap (int) – number of bootstrap resampling used to calculate the variance-covariance matrix using bootstrapping. If the number is 0, bootstrapping is not applied. Default: 0.
algorithm (function) – optimization algorithm to use for the maximum likelihood estimation. If None, cfsqp is used. Default: the optimization algorithm available with scipy.
algoParameters (dict) – parameters to transfer to the optimization algorithm
cfsqpDefaultBounds (float) – if the user does not provide bounds on the parameters, CFSQP assumes that the bounds are [-cfsqpDefaultBounds,cfsqpDefaultBounds]

Returns

object containing the estimation results.

Return type

biogeme.bioResults

Example:

# Create an instance of biogeme
biogeme  = bio.BIOGEME(database, logprob)
# Gives a name to the model
biogeme.modelName = "mymodel"
# Estimate the parameters
results = biogeme.estimate()

Raises: biogemeError – if no expression has been provided for the likelihood

getBoundsOnBeta(betaName)¶

Returns the bounds on the parameter as defined by the user.

Parameters: betaName (string) – name of the parameter
Returns: lower bound, upper bound
Return type: tuple
Raises: biogemeError – if the name of the parameter is not found.

likelihoodFiniteDifferenceHessian(x)¶

Calculate the hessian of the log likelihood function using finite differences.

May be useful when the analytical hessian has numerical issues.

Parameters: x (list(float)) – vector of values for the parameters.
Returns: finite differences approximation of the hessian.
Return type: numpy.array
Raises: ValueError – if the length of the list x is incorrect

optimize(startingValues)¶

Calls the optimization algorithm.

The function self.algorithm is called. If None, CFSQP is invoked.

Parameters

startingValues (list of floats) – initial values of the parameters.

Returns

x, nit, nfev, message, where

x is the solution found,
nit is the number of iterations performed,
nfev is the number of time that the objective function has been evaluated, and
message is the diagnostic provided by the algorithm.

Return type

tuple

simulate(theBetaValues=None)¶

Applies the formulas to each row of the database.

Parameters: theBetaValues (dict(str, float) or list(float)) – values of the parameters to be used in the calculations. If None, the default values are used. Default: None.
Returns: a pandas data frame with the simulated value. Each row corresponds to a row in the database, and each column to a formula.
Return type: Pandas data frame

Example:

# Read the estimation results from a file
results = res.bioResults(pickleFile='myModel.pickle')
# Simulate the formulas using the nominal values
simulatedValues = biogeme.simulate(betaValues)

Raises: biogemeError – if the number of parameters is incorrect

biogeme.database module¶

Implementation of the class Database, wrapping a pandas dataframe for specific services to Biogeme

author: Michel Bierlaire
date: Tue Mar 26 16:42:54 2019

class biogeme.database.Database(name, pandasDatabase)¶

Bases: object

Class that contains and prepare the database.

__init__(name, pandasDatabase)¶

Constructor

Parameters

name (string) – name of the database.
pandasDatabase (pandas.DataFrame) – data stored in a pandas data frame.

addColumn(expression, column)¶

Add a new column in the database, calculated from an expression.

Parameters

expression (biogeme.expressions.Expression) – expression to evaluate
column (string) – name of the column to add

Returns

the added column

Return type

numpy.Series

Raises

ValueError – if the column name already exists.

checkAvailabilityOfChosenAlt(avail, choice)¶

Check if the chosen alternative is available for each entry in the database.

Parameters

avail (list of biogeme.expressions.Expression) – list of expressions to evaluate the availability conditions for each alternative.
choice (biogeme.expressions.Expression) – expression for the chosen alternative.

Returns

numpy series of bool, long as the number of entries in the database, containing True is the chosen alternative is available, False otherwise.

Return type

numpy.Series

count(columnName, value)¶

Counts the number of observations that have a specific value in a given column.

Parameters

columnName (string) – name of the column.
value (float) – value that is seeked.

Returns

Number of times that the value appears in the column.

Return type

int

descriptionOfNativeDraws()¶

Describe the draws available draws with Biogeme

Returns: dict, where the keys are the names of the draws, and the value their description

Example of output:

['UNIFORM: Uniform U[0,1]','UNIFORM_ANTI: Antithetic uniform U[0,1]'],'NORMAL: Normal N(0,1) draws']         

Return type: dict

dumpOnFile()¶

Dumps the database in a CSV formatted file.

Returns: name of the file
Return type: string

generateDraws(types, names, numberOfDraws)¶

Generate draws for each variable.

Parameters

types (dict) – A dict indexed by the names of the variables, describing the types of draws. Each of them can be a native type or any type defined by the function database.setRandomNumberGenerators
names (list of strings) – the list of names of the variables that require draws to be generated.
numberOfDraws (int) – number of draws to generate.

Returns

a 3-dimensional table with draws. The 3 dimensions are

number of individuals
number of draws
number of variables

Return type

numpy.array

Example:

types = {'randomDraws1': 'NORMAL_MLHS_ANTI', 'randomDraws2': 'UNIFORM_MLHS_ANTI', 'randomDraws3': 'UNIFORMSYM_MLHS_ANTI'}
theDrawsTable = myData.generateDraws(types,['randomDraws1','randomDraws2','randomDraws3'],10)        

getNumberOfObservations()¶

Reports the number of observations in the database.

Note that it returns the same value, irrespectively if the database contains panel data or not.

Returns: Number of observations.
Return type: int

biogeme.distributions module¶

Implementation of the pdf and CDF of common distributions

:author:Michel Bierlaire

data: Thu Apr 23 12:01:49 2015

biogeme.distributions.logisticcdf(x, mu=0.0, s=1.0)¶

Logistic CDF

Cumulative distribution function of a logistic distribution

\[f(x;\mu,\sigma) = \frac{1}{1+\exp\left(-\frac{x-\mu}{\sigma} \right)} \]

Parameters

x (float or biogeme.expression) – location parameter \(\mu\) of the logistic distribution. Default: 0.
x – scale parameter \(\sigma\) of the logistic distribution. Default: 1.

Note

It is assumed that \(\sigma > 0\), but it is not verified by the code.

Returns

value of the logistic CDF.

Return type

float or biogeme.expression

biogeme.distributions.lognormalpdf(x, mu, s)¶

Log normal pdf

Probability density function of a log normal distribution

\[f(x;\mu,\sigma) = \frac{1}{x\sigma \sqrt{2\pi}} \exp{-\frac{(\ln x-\mu)^2}{2\sigma^2}}\]

Parameters

x (float or biogeme.expression) – location parameter \(\mu\) of the lognormal distribution. Default: 0.
s (float or biogeme.expression) – scale parameter \(\sigma\) of the lognormal distribution. Default: 1.

Note

It is assumed that \(\sigma > 0\), but it is not verified by the code.

Returns

value of the lognormal pdf.

Return type

float or biogeme.expression

biogeme.distributions.normalpdf(x, mu=0.0, s=1.0)¶

Normal pdf

Probability density function of a normal distribution

\[f(x;\mu,\sigma) = \frac{1}{\sigma \sqrt{2\pi}} \exp{-\frac{(x-\mu)^2}{2\sigma^2}}\]

Parameters

x (float or biogeme.expression) – location parameter \(\mu\) of the Normal distribution. Default: 0.
s (float or biogeme.expression) – scale parameter \(\sigma\) of the Normal distribution. Default: 1.

Note

It is assumed that \(\sigma > 0\), but it is not verified by the code.

Returns

value of the Normal pdf.

Return type

float or biogeme.expression

biogeme.distributions.triangularpdf(x, a=-1.0, b=1.0, c=0.0)¶

Triangular pdf

Probability density function of a triangular distribution

\[\begin{split}f(x;a,b,c) = \left\{ \begin{array}{ll} 0 & \text{if } x < a \\\frac{2(x-a)}{(b-a)(c-a)} & \text{if } a \leq x < c \\\frac{2(b-x)}{(b-a)(b-c)} & \text{if } c \leq x < b \\0 & \text{if } x \geq b.\end{array} \right.\end{split}\]

Parameters

x (float or biogeme.expression) – argument of the pdf
a (float or biogeme.expression) – lower bound \(a\) of the distribution. Default: -1.
b (float or biogeme.expression) – upper bound \(b\) of the distribution. Default: 1.
c (float or biogeme.expression) – mode \(c\) of the distribution. Default: 0.

Note

It is assumed that \(a < c < b\), but it is not verified by the code.

Returns

value of the triangular pdf.

Return type

float or biogeme.expression

biogeme.distributions.uniformpdf(x, a=-1, b=1.0)¶

Uniform pdf

Probability density function of a uniform distribution.

\[\begin{split}f(x;a,b) = \left\{ \begin{array}{ll} \frac{1}{b-a} & \text{for } x \in [a,b] \\ 0 & \text{otherwise}\end{array} \right.\end{split}\]

Parameters

x (float or biogeme.expression) – argument of the pdf
a (float or biogeme.expression) – lower bound \(a\) of the distribution. Default: -1.
b (float or biogeme.expression) – upper bound \(b\) of the distribution. Default: 1.

Note

It is assumed that \(a < b\), but it is not verified by the code.

Returns

value of the uniform pdf.

Return type

float or biogeme.expression

biogeme.draws module¶

Generation of various types of draws.

author: Michel Bierlaire
date: Tue Jun 18 19:05:13 2019

biogeme.draws.getAntithetic(unif, sampleSize, numberOfDraws)¶

Returns antithetic uniform draws

Parameters

unif (function) – function taking two arguments (sampleSize,numberOfDraws) and returning U[0,1] draws
sampleSize (int) – number of observations for which draws must be generated. If None, a one dimensional array will be generated. If it has a values k, then k series of draws will be generated
numberOfDraws (int) – number of draws to generate.

Returns

numpy array with the antithetic draws

Return type

numpy.array

Example:

draws = dr.getAntithetic(dr.getUniform,sampleSize=3,numberOfDraws=10)

array([[0.48592363, 0.13648133, 0.35925946, 0.32431338, 0.32997936,
        0.51407637, 0.86351867, 0.64074054, 0.67568662, 0.67002064],
       [0.89261997, 0.0331808 , 0.30767182, 0.93433648, 0.17196124,
        0.10738003, 0.9668192 , 0.69232818, 0.06566352, 0.82803876],
       [0.81095587, 0.96171364, 0.40984817, 0.72177258, 0.16481096,
        0.18904413, 0.03828636, 0.59015183, 0.27822742, 0.83518904]])

biogeme.draws.getHaltonDraws(sampleSize, numberOfDraws, symmetric=False, base=2, skip=0, shuffled=False)¶

Generate Halton draws

Parameters

sampleSize (int) – number of observations for which draws must be generated. If None, a one dimensional array will be generated. If it has a values k, then k series of draws will be generated
numberOfDraws (int) – number of draws to generate.
symmetric (bool) – if True, draws from [-1:1] are generated. If False, draws from [0:1] are generated. Default: False
base (int) – generate Halton draws for a given basis. Ideally, it should be a prime number. Default: 2.
skip (int) – the number of elements of the sequence to be discarded.
shuffled (bool) – if True, each series is shuffled

Returns

numpy array with the draws

Return type

numpy.array

Example:

halton = dr.getHaltonDraws(sampleSize=2,numberOfDraws=10,base=3)
array([[0.33333333, 0.66666667, 0.11111111, 0.44444444, 0.77777778,
        0.22222222, 0.55555556, 0.88888889, 0.03703704, 0.37037037],
       [0.7037037 , 0.14814815, 0.48148148, 0.81481481, 0.25925926,
        0.59259259, 0.92592593, 0.07407407, 0.40740741, 0.74074074]])

biogeme.draws.getLatinHypercubeDraws(sampleSize, numberOfDraws, symmetric=False, uniformNumbers=None)¶

Implementation of the Modified Latin Hypercube Sampling proposed: by Hess et al, 2006.

Parameters

sampleSize (int) – number of observations for which draws must be generated. If None, a one dimensional array will be generated. If it has a values k, then k series of draws will be generated
numberOfDraws (int) – number of draws to generate.
symmetric (bool) – if True, draws from [-1:1] are generated. If False, draws from [0:1] are generated. Default: False
uniformNumbers (numpy.array) – numpy with uniformly distributed numbers. If None, the numpy uniform number generator is used.

Returns

numpy array with the draws

Return type

numpy.array

Example:

latinHypercube = dr.getLatinHypercubeDraws(sampleSize=3,numberOfDraws=10)
array([[0.43362897, 0.5275741 , 0.09215663, 0.94056236, 0.34376868,
        0.87195551, 0.41495219, 0.71736691, 0.23198736, 0.145561  ],
       [0.30520544, 0.78082964, 0.83591146, 0.2733167 , 0.53890906,
        0.61607469, 0.00699715, 0.17179441, 0.7557228 , 0.39733102],
       [0.49676864, 0.67073483, 0.9788854 , 0.5726069 , 0.11894558,
        0.05515471, 0.2640275 , 0.82093696, 0.92034628, 0.64866597]])    

biogeme.draws.getNormalWichuraDraws(sampleSize, numberOfDraws, uniformNumbers=None, antithetic=False)¶

Generate pseudo-random numbers from a normal distribution N(0,1)

It uses the Algorithm AS241 Appl. Statist. (1988) Vol. 37, No. 3, which produces the normal deviate z corresponding to a given lower tail area of p; z is accurate to about 1 part in \(10^{16}\).

Parameters

sampleSize (int) – number of observations for which draws must be generated. If None, a one dimensional array will be generated. If it has a values k, then k series of draws will be generated
numberOfDraws (int) – number of draws to generate.
uniformNumbers (numpy.array) – numpy with uniformly distributed numbers. If None, the numpy uniform number generator is used.
antithetic (bool) – if True, only half of the draws are actually generated, and the series are completed with their antithetic version.

Returns

numpy array with the draws

Return type

numpy.array

Example:

draws = dr.getNormalWichuraDraws(sampleSize=3,numberOfDraws=10)
array([[ 0.52418458, -1.04344204, -2.11642482,  0.48257162, -2.67188279,
        -1.89993283,  0.28251041, -0.38424425,  1.53182226,  0.30651874],
       [-0.7937038 , -0.07884121, -0.91005616, -0.98855175,  1.09405753,
        -0.5997651 , -1.70785113,  1.57571384, -0.33208723, -1.03510102],
       [-0.13853654,  0.92595498, -0.80136586,  1.68454196,  0.9955927 ,
        -0.28615154,  2.10635541,  0.0436191 , -0.25417774,  0.01026933]])

biogeme.draws.getUniform(sampleSize, numberOfDraws, symmetric=False)¶

Uniform [0,1] or [-1,1] numbers

Parameters

sampleSize (int) – number of observations for which draws must be generated. If None, a one dimensional array will be generated. If it has a values k, then k series of draws will be generated
numberOfDraws (int) – number of draws to generate.
symmetric (bool) – if True, draws from [-1:1] are generated. If False, draws from [0:1] are generated. Default: False

Returns

numpy array with the draws

Return type

numpy.array

Example:

draws = dr.getUniform(sampleSize=3,numberOfDraws=10,symmetric=False)
array([[0.13053817, 0.63892308, 0.55031567, 0.26347854, 0.16730932,
        0.77745367, 0.48283887, 0.84247501, 0.20550219, 0.02373537],
       [0.68935846, 0.03363595, 0.36006669, 0.26709364, 0.54907706,
        0.22492104, 0.2494399 , 0.17323209, 0.52370401, 0.54091257],
       [0.40310204, 0.89916711, 0.86065005, 0.94277699, 0.09077065,
        0.40107731, 0.22554722, 0.47693135, 0.14058265, 0.17397031]])

draws = dr.getUniform(sampleSize=3,numberOfDraws=10,symmetric=True)
array([[ 0.74403237, -0.27995692,  0.33997421, -0.89405035, -0.129761  ,
         0.86593325,  0.30657422,  0.82435619,  0.498482  ,  0.24561616],
       [-0.48239607, -0.29257815, -0.98342034,  0.68392813, -0.25379429,
         0.49359859, -0.26459883,  0.14569724, -0.68860467, -0.40903446],
       [ 0.93251627, -0.85166912,  0.58096917,  0.39289882, -0.65088635,
         0.40114744, -0.61327161,  0.08900539, -0.20985417,  0.67542226]])

biogeme.exceptions module¶

Defines a generic exception for Biogeme

author: Michel Bierlaire
date: Tue Mar 26 16:47:11 2019

exception biogeme.exceptions.biogemeError¶

Bases: Exception

Defines a generic exception for Biogeme.

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)¶

Bases: biogeme.expressions.BinaryOperator

Logical and

__init__(left, right)¶

Constructor

Parameters

left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.Beta(name, value, lowerbound, upperbound, status)¶

Bases: biogeme.expressions.Elementary

Unknown parameters to be estimated from data.

__init__(name, value, lowerbound, upperbound, status)¶

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.

changeInitValues(betas)¶

Modifies the initial values of the Beta parameters.

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

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

dictOfBetas(free=True, fixed=False)¶

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)

getSignature()¶

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()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

setOfBetas(free=True, fixed=False)¶

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

set(biogeme.expressions.Expression)

setSpecificIndices(indicesOfFreeBetas, indicesOfFixedBetas, indicesOfRandomVariables, indicesOfDraws)¶

Provide an index to all elementary expressions, specific to their type

Parameters

indicesOfFreeBetas (dict(string:int)) – dictionary mapping the name of the free betas with their index
indicesOfFixedBetas (dict(string:int)) – dictionary mapping the name of the fixed betas with their index
indicesOfRandomVariables (dict(string:int)) – dictionary mapping the name of the random variables with their index
indicesOfDraws (dict(string:int)) – dictionary mapping the name of the draws with their index

class biogeme.expressions.BinaryOperator(left, right)¶

Bases: biogeme.expressions.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)¶

Constructor

Parameters

left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression

class biogeme.expressions.DefineVariable(name, expression, database)¶

Bases: biogeme.expressions.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)¶

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.

class biogeme.expressions.Derive(child, name)¶

Bases: biogeme.expressions.UnaryOperator

Derivative with respect to an elementary expression

__init__(child, name)¶

Constructor

Parameters: child (biogeme.expressions.Expression) – first arithmetic expression

getSignature()¶

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)

getValue()¶

Not implemented in Python. The C++ implementation must be used insteald

Raises: biogeme.exceptions.biogemeError

setUniqueId(idsOfElementaryExpressions)¶

Provides a unique id to the elementary expressions.

Parameters: idsOfElementaryExpressions (dict(string:int)) – dictionary mapping the name of the elementary expression with their id.

class biogeme.expressions.Divide(left, right)¶

Bases: biogeme.expressions.BinaryOperator

Division expression

__init__(left, right)¶

Constructor

Parameters

left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.Elem(dictOfExpressions, keyExpression)¶

Bases: biogeme.expressions.Expression

This returns the element of a dictionary. The key is evaluated from an expression.

__init__(dictOfExpressions, keyExpression)¶

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.

getSignature()¶

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()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.Elementary(name)¶

Bases: biogeme.expressions.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.

__init__(name)¶

Constructor

Parameters: name (string) – name of the elementary experession.

getElementaryExpression(name)¶: Return: an elementary expression from its name if it appears in the expression. None otherwise.

setUniqueId(idsOfElementaryExpressions)¶

Provides a unique id to the elementary expressions. Overloads the generic function

Parameters: idsOfElementaryExpressions (dict(string:int)) – dictionary mapping the name of the elementary expression with their id.

class biogeme.expressions.Equal(left, right)¶

Bases: biogeme.expressions.BinaryOperator

Logical equal

__init__(left, right)¶

Constructor

Parameters

left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.Expression¶

Bases: object

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

__add__(other)¶

Operator overloading. Generate an expression for addition.

Parameters: other (biogeme.expressions.Expression) – expression to be added
Returns: self + other
Return type: biogeme.expressions.Expression

__and__(other)¶

Operator overloading. Generate an expression for logical and.

Parameters: other (biogeme.expressions.Expression) – expression for logical and
Returns: self and other
Return type: biogeme.expressions.Expression

__div__(other)¶

Operator overloading. Generate an expression for division.

Parameters: other (biogeme.expressions.Expression) – expression for division
Returns: self / other
Return type: biogeme.expressions.Expression

__eq__(other)¶

Operator overloading. Generate an expression for comparison.

Parameters: other (biogeme.expressions.Expression) – expression for equality
Returns: self == other
Return type: biogeme.expressions.Expression

__ge__(other)¶

Operator overloading. Generate an expression for comparison.

Parameters: other (biogeme.expressions.Expression) – expression for greater or equal
Returns: self >= other
Return type: biogeme.expressions.Expression

__gt__(other)¶

Operator overloading. Generate an expression for comparison.

Parameters: other (biogeme.expressions.Expression) – expression for greater than
Returns: self > other
Return type: biogeme.expressions.Expression

__init__()¶: Constructor

__le__(other)¶

Operator overloading. Generate an expression for comparison.

Parameters: other (biogeme.expressions.Expression) – expression for less or equal
Returns: self <= other
Return type: biogeme.expressions.Expression

__lt__(other)¶

Operator overloading. Generate an expression for comparison.

Parameters: other (biogeme.expressions.Expression) – expression for less than
Returns: self < other
Return type: biogeme.expressions.Expression

__mul__(other)¶

Operator overloading. Generate an expression for multiplication.

Parameters: other (biogeme.expressions.Expression) – expression to be multiplied
Returns: self * other
Return type: biogeme.expressions.Expression

__ne__(other)¶

Operator overloading. Generate an expression for comparison.

Parameters: other (biogeme.expressions.Expression) – expression for difference
Returns: self != other
Return type: biogeme.expressions.Expression

__neg__()¶

Operator overloading. Generate an expression for unary minus.

Returns: -self
Return type: biogeme.expressions.Expression

__or__(other)¶

Operator overloading. Generate an expression for logical or.

Parameters: other (biogeme.expressions.Expression) – expression for logical or
Returns: self or other
Return type: biogeme.expressions.Expression

__pow__(other)¶

Operator overloading. Generate an expression for power.

Parameters: other (biogeme.expressions.Expression) – expression for power
Returns: self ^ other
Return type: biogeme.expressions.Expression

__radd__(other)¶

Operator overloading. Generate an expression for addition.

Parameters: other (biogeme.expressions.Expression) – expression to be added
Returns: other + self
Return type: biogeme.expressions.Expression

__rdiv__(other)¶

Operator overloading. Generate an expression for division.

Parameters: other (biogeme.expressions.Expression) – expression for division
Returns: other / self
Return type: biogeme.expressions.Expression

__rmul__(other)¶

Operator overloading. Generate an expression for multiplication.

Parameters: other (biogeme.expressions.Expression) – expression to be multiplied
Returns: other * self
Return type: biogeme.expressions.Expression

__rpow__(other)¶

Operator overloading. Generate an expression for power.

Parameters: other (biogeme.expressions.Expression) – expression for power
Returns: other ^ self
Return type: biogeme.expressions.Expression

__rsub__(other)¶

Operator overloading. Generate an expression for substraction.

Parameters: other (biogeme.expressions.Expression) – expression to be substracted
Returns: other - self
Return type: biogeme.expressions.Expression

__rtruediv__(other)¶

Operator overloading. Generate an expression for division.

Parameters: other (biogeme.expressions.Expression) – expression for division
Returns: other / self
Return type: biogeme.expressions.Expression

__sub__(other)¶

Operator overloading. Generate an expression for substraction.

Parameters: other (biogeme.expressions.Expression) – expression to substract
Returns: self - other
Return type: biogeme.expressions.Expression

__truediv__(other)¶

Operator overloading. Generate an expression for division.

Parameters: other (biogeme.expressions.Expression) – expression for division
Returns: self / other
Return type: biogeme.expressions.Expression

audit(database=None)¶

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)¶

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.

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

dictOfBetas(free=True, fixed=False)¶

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()¶

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()¶

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()¶

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)¶

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.

Return:: bool.

See: Expression.isContainedIn

getClassName()¶

Obtain the name of the top class of the expression structure

Returns: the name of the class
Return type: string

getElementaryExpression(name)¶

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

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

getSignature()¶

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)

getValue_c(database, numberOfDraws=1000)¶

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

database (biogeme.database.Database) – database
numberOfDraws (int) – number of draws if needed by Monte-Carlo integration.

Returns

a list where each entry is the result of applying the expression on one entry of the dsatabase.

Return type

numpy.array

isContainedIn(t)¶

Check if the expression is contained in an expression of type t. Typically, this would be used to check that a bioDraws expression is contained in a MonteCarlo expression. If not, it cannot be evaluated.

Return:: bool.

See: Expression.embedExpression

setOfBetas(free=True, fixed=False)¶

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

set(biogeme.expressions.Expression)

setOfVariables()¶

Extract the set of variables used in the expression.

Returns: returns a set with the variables appearing in the expression.
Return type: set(biogeme.expressions.Expression)

setRow(row)¶

This function identifies the row of the database from which the values of the variables must be obtained.

Parameters: row (int) – id of the row.

setSpecificIndices(indicesOfFreeBetas, indicesOfFixedBetas, indicesOfRandomVariables, indicesOfDraws)¶

Provides an index to all elementary expressions, specific to their type

Parameters

indicesOfFreeBetas (dict(string:int)) – dictionary mapping the name of the free betas with their index
indicesOfFixedBetas (dict(string:int)) – dictionary mapping the name of the fixed betas with their index
indicesOfRandomVariables (dict(string:int)) – dictionary mapping the name of the random variables with their index
indicesOfDraws (dict(string:int)) – dictionary mapping the name of the draws with their index

setUniqueId(idsOfElementaryExpressions)¶

Provides a unique id to the elementary expressions.

Parameters: idsOfElementaryExpressions (dict(string:int)) – dictionary mapping the name of the elementary expression with their id.

setVariableIndices(indicesOfVariables)¶

Provide an index to all variables

Parameters: indicesOfVariables (dict(string:int)) – dictionary mapping the name of the variables with their index

class biogeme.expressions.Greater(left, right)¶

Bases: biogeme.expressions.BinaryOperator

Logical greater

__init__(left, right)¶

Constructor

Parameters

left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.GreaterOrEqual(left, right)¶

Bases: biogeme.expressions.BinaryOperator

Logical greater or equal

__init__(left, right)¶

Constructor

Parameters

left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.Integrate(child, name)¶

Bases: biogeme.expressions.UnaryOperator

Numerical integration

__init__(child, name)¶

Constructor

Parameters

child (biogeme.expressions.Expression) – first arithmetic expression
name (string) – name of the random variable for the integration.

audit(database=None)¶

Performs various checks on the expressions.

Parameters: database (biogeme.database.Database) – database object
Returns: tuple listOfErrors,listOfWarnings
Return type: list(string),list(string)

getSignature()¶

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)

getValue()¶

Not implementedin Python. The C++ implementation must be used insteald

Raises: biogeme.exceptions.biogemeError

setSpecificIndices(indicesOfFreeBetas, indicesOfFixedBetas, indicesOfRandomVariables, indicesOfDraws)¶

Provide an index to all elementary expressions, specific to their type Overloads the generic function.

Parameters

indicesOfFreeBetas (dict(string:int)) – dictionary mapping the name of the free betas with their index
indicesOfFixedBetas (dict(string:int)) – dictionary mapping the name of the fixed betas with their index
indicesOfRandomVariables (dict(string:int)) – dictionary mapping the name of the random variables with their index
indicesOfDraws (dict(string:int)) – dictionary mapping the name of the draws with their index

setUniqueId(idsOfElementaryExpressions)¶

Provides a unique id to the elementary expressions. Overloads the generic function

Parameters: idsOfElementaryExpressions (dict(string:int)) – dictionary mapping the name of the elementary expression with their id.

class biogeme.expressions.Less(left, right)¶

Bases: biogeme.expressions.BinaryOperator

Logical less

__init__(left, right)¶

Constructor

Parameters

left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.LessOrEqual(left, right)¶

Bases: biogeme.expressions.BinaryOperator

Logical less or equal

__init__(left, right)¶

Constructor

Parameters

left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.LogLogit(util, av, choice)¶

Bases: biogeme.expressions.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)¶

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.

audit(database)¶

Performs various checks on the expressions.

Parameters: database (biogeme.database.Database) – database object
Returns: tuple listOfErrors,listOfWarnings
Return type: list(string),list(string)

getSignature()¶

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()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.Minus(left, right)¶

Bases: biogeme.expressions.BinaryOperator

Substraction expression

__init__(left, right)¶

Constructor

Parameters

left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.MonteCarlo(child)¶

Bases: biogeme.expressions.UnaryOperator

Monte Carlo integration

__init__(child)¶

Constructor

Parameters: child (biogeme.expressions.Expression) – first arithmetic expression

audit(database=None)¶

Performs various checks on the expressions.

Parameters: database (biogeme.database.Database) – database object
Returns: tuple listOfErrors,listOfWarnings
Return type: list(string),list(string)

getValue()¶

Not implementedin Python. The C++ implementation must be used insteald

Raises: biogeme.exceptions.biogemeError

class biogeme.expressions.NotEqual(left, right)¶

Bases: biogeme.expressions.BinaryOperator

Logical not equal

__init__(left, right)¶

Constructor

Parameters

left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.Numeric(value)¶

Bases: biogeme.expressions.Expression

Numerical expression for a simple number

__init__(value)¶

Constructor

Parameters: value (float) – numerical value

getSignature()¶

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()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.Or(left, right)¶

Bases: biogeme.expressions.BinaryOperator

Logical or

__init__(left, right)¶

Constructor

Parameters

left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.PanelLikelihoodTrajectory(child)¶

Bases: biogeme.expressions.UnaryOperator

Likelihood of a sequences of observations for the same individual

__init__(child)¶

Constructor

Parameters: child (biogeme.expressions.Expression) – first arithmetic expression

audit(database=None)¶

Performs various checks on the expressions.

Parameters: database (biogeme.database.Database) – database object
Returns: tuple listOfErrors,listOfWarnings
Return type: list(string),list(string)

countPanelTrajectoryExpressions()¶: Count the number of times the PanelLikelihoodTrajectory is used in the formula.

getValue()¶

Not implementedin Python. The C++ implementation must be used insteald

Raises: biogeme.exceptions.biogemeError

class biogeme.expressions.Plus(left, right)¶

Bases: biogeme.expressions.BinaryOperator

Addition expression

__init__(left, right)¶

Constructor

Parameters

left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.Power(left, right)¶

Bases: biogeme.expressions.BinaryOperator

Power expression

__init__(left, right)¶

Constructor

Parameters

left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.RandomVariable(name)¶

Bases: biogeme.expressions.Elementary

Random variable for numerical integration

__init__(name)¶

Constructor

Parameters: name (string.) – name of the random variable involved in the integration.

audit(database=None)¶

Performs various checks on the expressions.

Parameters: database (biogeme.database.Database) – database object
Returns: tuple listOfErrors,listOfWarnings
Return type: list(string),list(string)

dictOfRandomVariables()¶

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()¶

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

setSpecificIndices(indicesOfFreeBetas, indicesOfFixedBetas, indicesOfRandomVariables, indicesOfDraws)¶

Provide an index to all elementary expressions, specific to their type Overloads the generic function.

Parameters

indicesOfFreeBetas (dict(string:int)) – dictionary mapping the name of the free betas with their index
indicesOfFixedBetas (dict(string:int)) – dictionary mapping the name of the fixed betas with their index
indicesOfRandomVariables (dict(string:int)) – dictionary mapping the name of the random variables with their index
indicesOfDraws (dict(string:int)) – dictionary mapping the name of the draws with their index

class biogeme.expressions.Times(left, right)¶

Bases: biogeme.expressions.BinaryOperator

Multiplication expression

__init__(left, right)¶

Constructor

Parameters

left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.UnaryMinus(child)¶

Bases: biogeme.expressions.UnaryOperator

Unary minus expression

__init__(child)¶

Constructor

Parameters: child (biogeme.expressions.Expression) – first arithmetic expression

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.UnaryOperator(child)¶

Bases: biogeme.expressions.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)¶

Constructor

Parameters: child (biogeme.expressions.Expression) – first arithmetic expression

class biogeme.expressions.Variable(name)¶

Bases: biogeme.expressions.Elementary

Explanatory variable

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

__init__(name)¶

Constructor

Parameters: name (string) – name of the variable.

audit(database)¶

Performs various checks on the expressions.

Parameters: database (biogeme.database.Database) – database object
Returns: tuple listOfErrors,listOfWarnings
Return type: list(string),list(string)

dictOfVariables()¶

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()¶

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()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

setVariableIndices(indicesOfVariables)¶

Provide an index to all variables

Parameters: indicesOfVariables (dict(string:int)) – dictionary mapping the name of the variables with their index

class biogeme.expressions.bioDraws(name, type)¶

Bases: biogeme.expressions.Elementary

Draws for Monte-Carlo integration

__init__(name, type)¶

Constructor

Parameters

name (string) – name of the random variable with a series of draws.
type (string) – type of draws.

audit(database=None)¶

Performs various checks on the expressions.

Parameters: database (biogeme.database.Database) – database object
Returns: tuple listOfErrors,listOfWarnings
Return type: list(string),list(string)

dictOfDraws()¶

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()¶

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

getValue()¶

Not implementedin Python. The C++ implementation must be used insteald

Raises: biogeme.exceptions.biogemeError

setDrawIndex(idsOfDraws)¶

Provide an index to a series of draw for a random variable. Overload the generic function.

Parameters: idsOfDraws (dict(string:int)) – dictionary mapping the name of the draws with their id.

setSpecificIndices(indicesOfFreeBetas, indicesOfFixedBetas, indicesOfRandomVariables, indicesOfDraws)¶

Provide an index to all elementary expressions, specific to their type Overloads the generic function.

Parameters

indicesOfFreeBetas (dict(string:int)) – dictionary mapping the name of the free betas with their index
indicesOfFixedBetas (dict(string:int)) – dictionary mapping the name of the fixed betas with their index
indicesOfRandomVariables (dict(string:int)) – dictionary mapping the name of the random variables with their index
indicesOfDraws (dict(string:int)) – dictionary mapping the name of the draws with their index

class biogeme.expressions.bioLinearUtility(listOfTerms)¶

Bases: biogeme.expressions.Expression

When the utility function is linear, it is expressed as a list of terms, where a parameter multiplies a variable.

__init__(listOfTerms)¶

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)

dictOfBetas(free=True, fixed=False)¶

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()¶

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()¶

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()¶

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()¶

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)

setOfBetas(free=True, fixed=False)¶

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

set(biogeme.expressions.Expression)

class biogeme.expressions.bioLogLogit(util, av, choice)¶

Bases: biogeme.expressions.LogLogit

log of logit formula

This expression captures the logarithm of 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 It uses only the C++ implementation.

class biogeme.expressions.bioLogLogitFullChoiceSet(util, av, choice)¶

Bases: biogeme.expressions.LogLogit

This expression captures the logarithm of the logit formula, where all alternatives are supposed to be always available.

It contains one formula for the target alternative and a dict of formulas for the utilities. It uses only the C++ implementation.

class biogeme.expressions.bioMax(left, right)¶

Bases: biogeme.expressions.BinaryOperator

Maximum of two expressions

__init__(left, right)¶

Constructor

Parameters

left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.bioMin(left, right)¶

Bases: biogeme.expressions.BinaryOperator

Minimum of two expressions

__init__(left, right)¶

Constructor

Parameters

left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.bioMultSum(listOfExpressions)¶

Bases: biogeme.expressions.Expression

This expression returns the sum of several other expressions.

It is a generalization of ‘Plus’ for more than two terms

__init__(listOfExpressions)¶

Constructor

Parameters: listOfExpressions (list(biogeme.expressions.Expression)) – list of objects representing the terms of the sum.

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

class biogeme.expressions.bioNormalCdf(child)¶

Bases: biogeme.expressions.UnaryOperator

Cumulative Distribution Function of a normal random variable

__init__(child)¶

Constructor

Parameters: child (biogeme.expressions.Expression) – first arithmetic expression

getValue()¶

Not implementedin Python. The C++ implementation must be used insteald

Raises: biogeme.exceptions.biogemeError

class biogeme.expressions.bioNormalPdf(child)¶

Bases: biogeme.expressions.UnaryOperator

Probability density function of a normal random variable

__init__(child)¶

Constructor

Parameters: child (biogeme.expressions.Expression) – first arithmetic expression

getValue()¶

Not implementedin Python. The C++ implementation must be used insteald

Raises: biogeme.exceptions.biogemeError

biogeme.expressions.defineNumberingOfElementaryExpressions(collectionOfFormulas, variableNames)¶

Provides indices for elementary expressions

The numbering is done in the following order:

free betas,

fixed betas,

random variables for numrerical integration,

random variables for Monte-Carlo integration,

variables

The numbering convention will be performed for all expressions together, so that the same elementary expressions in several expressions will have the same index.

Parameters

collectionOfFormula (list(biogeme.expressions.Expression)) – collection of Biogeme expressions.
variableNames (list(string)) – list of the names of the variables

Returns

dict,free,freeNames,fixed,fixedNames,rv,rvNames,draws,drawsNames where

dict is a dictionary mapping the names of the elementary expressions with their index,
free is a dict with the free betas,
freeNames is a list of the names of the free betas,
fixed is a dict with the fixed betas,
fixedNames is the list of the names of the fixed betas,
rv is a dict with the random variables for numerical integration,
rvNames is a list with their names,
draws is a dict of the draws, and
drawsNames is a list with their names.

class biogeme.expressions.exp(child)¶

Bases: biogeme.expressions.UnaryOperator

exponential expression

__init__(child)¶

Constructor

Parameters: child (biogeme.expressions.Expression) – first arithmetic expression

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

biogeme.expressions.isNumeric(obj)¶

Identifies if an object is numeric, that is int, float or bool.

Parameters: obj – any object

class biogeme.expressions.log(child)¶

Bases: biogeme.expressions.UnaryOperator

logarithm expression

__init__(child)¶

Constructor

Parameters: child (biogeme.expressions.Expression) – first arithmetic expression

getValue()¶

Evaluates the value of the expression

Returns: value of the expression
Return type: float

biogeme.filenames module¶

Implements the function providing names for the output files.

author: Michel Bierlaire
date: Tue Mar 26 16:48:40 2019

biogeme.filenames.getNewFileName(name, ext)¶

Generate a file name that does not exist.

Parameters

name (string) – name of the file.
ext (string) – file extension.

Returns

name.ext if the file does not exists. If it does, returns name~xx.ext, where xx is the smallest integer such that the corresponding file does not exist. It is designed to avoid erasing output files inadvertently.

Return type

string

biogeme.loglikelihood module¶

Functions to calculate the log likelihood

author: Michel Bierlaire
date: Fri Mar 29 17:11:44 2019

biogeme.loglikelihood.likelihoodregression(meas, model, sigma)¶

Computes likelihood function of a regression model.

Parameters

meas (biogeme.expressions.Expression) – An expression providing the value \(y\) of the measure for the current observation.
model (biogeme.expressions.Expression) – An expression providing the output \(m\) of the model for the current observation.
sigma (biogeme.expressions.Expression) – An expression (typically, a parameter) providing the standard error \(\sigma\) of the error term.

Returns

The likelihood of the regression, assuming a normal distribution, that is

\[\frac{1}{\sigma} \phi\left( \frac{y-m}{\sigma} \right) \]

where \(\phi(\cdot)\) is the pdf of the normal distribution.

Return type: biogeme.expressions.Expression

biogeme.loglikelihood.loglikelihood(prob)¶

Simply computes the log of the probability

Parameters: prob (biogeme.expressions.Expression) – An expression providing the value of the probability.
Returns: the logarithm of the probability.
Return type: biogeme.expressions.Expression

biogeme.loglikelihood.loglikelihoodregression(meas, model, sigma)¶

Computes log likelihood function of a regression model.

Parameters

meas (biogeme.expressions.Expression) – An expression providing the value \(y\) of the measure for the current observation.
model (biogeme.expressions.Expression) – An expression providing the output \(m\) of the model for the current observation.
sigma (biogeme.expressions.Expression) – An expression (typically, a parameter) providing the standard error \(\sigma\) of the error term.

Returns

the likelihood of the regression, assuming a normal distribution, that is

\[-\left( \frac{(y-m)^2}{2\sigma^2} \right) - \log(\sigma) - \frac{1}{2}\log(2\pi)\]

Return type: biogeme.expressions.Expression

biogeme.loglikelihood.mixedloglikelihood(prob)¶

Compute a simulated loglikelihood function

Parameters: prob – An expression providing the value of the probability. Although it is not formally necessary, the expression should contain one or more random variables of a given distribution, and therefore is defined as

\[P(i|\xi_1,\ldots,\xi_L)\]

Returns: the simulated loglikelihood, given by

\[\ln\left(\sum_{r=1}^R P(i|\xi^r_1,\ldots,\xi^r_L) \right)\]

where \(R\) is the number of draws, and \(\xi_j^r\) is the rth draw of the random variable \(\xi_j\).

Return type: biogeme.expressions.Expression

biogeme.messaging module¶

Singleton managing the various levels of messages

author: Michel Bierlaire
date: Mon Jul 22 16:12:00 2019

class biogeme.messaging.Singleton¶

Bases: type

A singleton is a class with only one instance

class biogeme.messaging.bioMessage(screenLevel=0)¶

Bases: object

Manages the Biogeme messages

__init__(screenLevel=0)¶

Constructor

Parameters

screenLevel –

level of message that must be displayed on the screen:

0: no output (default)
1: warnings only
2: only warnings and general information
3: more verbose
4: debug messages

addMessage(text, level)¶

Add a message

Parameters

text (string) – text of the message.
level –
level of the message
- 1: warning
- 2: general information
- 3: detailed information
- 4: debug message

Note

adding a message of level 0 is meaningless, as it correspond to silentmode.

createLog(fileLevel=3, fileName='_biogeme')¶

Creates a log file

Parameters

fileLevel –
level of message that must be reported in the file:
- 0: no output
- 1: warnings only
- 2: only warnings and general information
- 3: more verbose (default)
- 4: debug messages
fileName (string) – name of the file (without extension). Default: “_biogeme”. A file called _biogeme.log will be created.

debug(text)¶

Add a debug message

Parameters: text (string) – text of the message.

detailed(text)¶

Add a detailed message

Parameters: text (string) – text of the message.

general(text)¶

Add a general message

Parameters: text (string) – text of the message.

setDebug()¶: Set both screen and file levels to 4

setDetailed()¶: Set both screen and file levels to 3

setFileLevel(level)¶

Change the level of messaging for the file

Parameters

level (int) –

level of message that must be reported in the file:

0: no output
1: warnings only
2: only warnings and general information
3: more verbose
4: debug messages

setGeneral()¶: Set both screen and file levels to 2

setScreenLevel(level)¶

Change the level of messaging for the screen

Parameters

level (int) –

level of message that must be displayed on the screen:

0: no output
1: warnings only
2: only warnings and general information
3: more verbose
4: debug messages

setSilent()¶: Set both screen and file levels to 0

setWarning()¶: Set both screen and file levels to 1

warning(text)¶

Add a warning

Parameters: text (string) – text of the message.

biogeme.models module¶

Implements various models.

author: Michel Bierlaire
date: Fri Mar 29 17:13:14 2019

biogeme.models.bioNormalPdf(x)¶

pdf of the normal distribution N(0,1)

\[\frac{1}{\sqrt{2\pi}} e^{\frac{-x^2}{2}}\]

Parameters: x (biogeme.expressions.Expression) – argument of the function
Returns: value of the pdf
Return type: biogeme.expressions.Expression

biogeme.models.boxcox(x, l)¶

Box-Cox transform

\[B(x,\ell) = \frac{x^{\ell}-1}{\ell}. \]

It has the property that

\[\lim_{\ell \to 0} B(x,\ell)=\log(x).\]

Parameters

x (biogeme.expressions.Expression) – a variable to transform.
l (biogeme.expressions.Expression) – parameter of the transformation.

Returns

the Box-Cox transform

Return type

biogeme.expressions.Expression

biogeme.models.cnl(V, availability, nests, choice)¶

Implements the cross-nested logit model as a MEV model.

Parameters

V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.
nests (tuple) –
a tuple containing as many items as nests. Each item is also a tuple containing two items
- an object of type biogeme.expressions.Expression representing the nest parameter,
- a dictionary mapping the alternative ids with the cross-nested parameters for the corresponding nest.
Example:
```
alphaA = {1: alpha1a,2: alpha2a, 3: alpha3a, 4: alpha4a,5: alpha5a, 6: alpha6a}
alphaB = {1: alpha1b,2: alpha2b, 3: alpha3b, 4: alpha4b,5: alpha5b, 6: alpha6b}
nesta = MUA , alphaA
nestb = MUB , alphaB
nests = nesta, nestb
```
choice (biogeme.expressions.Expression) – id of the alternative for which the probability must be calculated.

Returns

choice probability for the cross-nested logit model.

Return type

biogeme.expressions.Expression

biogeme.models.cnl_avail(V, availability, nests, choice)¶

Same as cnl. Maintained for backward compatibility

Parameters

V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.
nests (tuple) –
a tuple containing as many items as nests. Each item is also a tuple containing two items
- an object of type biogeme.expressions.Expression representing the nest parameter,
- a dictionary mapping the alternative ids with the cross-nested parameters for the corresponding nest.
Example:
```
alphaA = {1: alpha1a,2: alpha2a, 3: alpha3a, 4: alpha4a,5: alpha5a, 6: alpha6a}
alphaB = {1: alpha1b,2: alpha2b, 3: alpha3b, 4: alpha4b,5: alpha5b, 6: alpha6b}
nesta = MUA , alphaA
nestb = MUB , alphaB
nests = nesta, nestb
```
choice (biogeme.expressions.Expression) – id of the alternative for which the probability must be calculated.

Returns

choice probability for the cross-nested logit model.

Return type

biogeme.expressions.Expression

biogeme.models.cnlmu(V, availability, nests, choice, bmu)¶

Implements the cross-nested logit model as a MEV model with the homogeneity parameters is explicitly involved

Parameters

V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.
nests (tuple) –
a tuple containing as many items as nests. Each item is also a tuple containing two items
- an object of type biogeme.expressions.Expression representing the nest parameter,
- a dictionary mapping the alternative ids with the cross-nested parameters for the corresponding nest.
Example:
```
alphaA = {1: alpha1a,2: alpha2a, 3: alpha3a, 4: alpha4a,5: alpha5a, 6: alpha6a}
alphaB = {1: alpha1b,2: alpha2b, 3: alpha3b, 4: alpha4b,5: alpha5b, 6: alpha6b}
nesta = MUA , alphaA
nestb = MUB , alphaB
nests = nesta, nestb
```
choice (biogeme.expressions.Expression) – id of the alternative for which the probability must be calculated.
bmu (biogeme.expressions.Expression) – Homogeneity parameter \(\mu\).

Returns

choice probability for the cross-nested logit model.

Return type

biogeme.expressions.Expression

biogeme.models.getMevForNested(V, availability, nests)¶

Implements the MEV generating function for the nested logit model

Parameters

V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.
nests (tuple) –
A tuple containing as many items as nests. Each item is also a tuple containing two items
- an object of type biogeme.expressions.Expression representing the nest parameter,
- a list containing the list of identifiers of the alternatives belonging to the nest.
Example:
```
nesta = MUA , [1,2,3]
nestb = MUB , [4,5,6]
nests = nesta, nestb
```

Returns

a dictionary mapping each alternative id with the function

\[\ln \frac{\partial G}{\partial y_i}(e^{V_1},\ldots,e^{V_J}) = e^{(\mu_m-1)V_i} \left(\sum_{i=1}^{J_m} e^{\mu_m V_i}\right)^{\frac{1}{\mu_m}-1}\]

where \(m\) is the (only) nest containing alternative \(i\), and \(G\) is the MEV generating function.

Return type: dict(int:biogeme.expressions.Expression)

biogeme.models.logcnl(V, availability, nests, choice)¶

Implements the log of the cross-nested logit model as a MEV model.

Parameters

V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.
nests (tuple) –
a tuple containing as many items as nests. Each item is also a tuple containing two items
- an object of type biogeme.expressions.Expression representing the nest parameter,
- a dictionary mapping the alternative ids with the cross-nested parameters for the corresponding nest.
Example:
```
alphaA = {1: alpha1a,2: alpha2a, 3: alpha3a, 4: alpha4a,5: alpha5a, 6: alpha6a}
alphaB = {1: alpha1b,2: alpha2b, 3: alpha3b, 4: alpha4b,5: alpha5b, 6: alpha6b}
nesta = MUA , alphaA
nestb = MUB , alphaB
nests = nesta, nestb
```
choice (biogeme.expressions.Expression) – id of the alternative for which the probability must be calculated.

Returns

log of the choice probability for the cross-nested logit model.

Return type

biogeme.expressions.Expression

biogeme.models.logcnl_avail(V, availability, nests, choice)¶

Same as logcnl. Maintained for backward compatibility

Parameters

V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.
nests (tuple) –
a tuple containing as many items as nests. Each item is also a tuple containing two items
- an object of type biogeme.expressions.Expression representing the nest parameter,
- a dictionary mapping the alternative ids with the cross-nested parameters for the corresponding nest.
Example:
```
alphaA = {1: alpha1a,2: alpha2a, 3: alpha3a, 4: alpha4a,5: alpha5a, 6: alpha6a}
alphaB = {1: alpha1b,2: alpha2b, 3: alpha3b, 4: alpha4b,5: alpha5b, 6: alpha6b}
nesta = MUA , alphaA
nestb = MUB , alphaB
nests = nesta, nestb
```
choice (biogeme.expressions.Expression) – id of the alternative for which the probability must be calculated.

Returns

log of choice probability for the cross-nested logit model.

Return type

biogeme.expressions.Expression

biogeme.models.logcnlmu(V, availability, nests, choice, bmu)¶

Implements the log of the cross-nested logit model as a MEV model with the homogeneity parameters is explicitly involved.

Parameters

V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.
nests (tuple) –
a tuple containing as many items as nests. Each item is also a tuple containing two items
- an object of type biogeme.expressions.Expression representing the nest parameter,
- a dictionary mapping the alternative ids with the cross-nested parameters for the corresponding nest.
Example:
```
alphaA = {1: alpha1a,2: alpha2a, 3: alpha3a, 4: alpha4a,5: alpha5a, 6: alpha6a}
alphaB = {1: alpha1b,2: alpha2b, 3: alpha3b, 4: alpha4b,5: alpha5b, 6: alpha6b}
nesta = MUA , alphaA
nestb = MUB , alphaB
nests = nesta, nestb
```
choice (biogeme.expressions.Expression) – id of the alternative for which the probability must be calculated.
bmu (biogeme.expressions.Expression) – Homogeneity parameter \(\mu\).

Returns

log of the choice probability for the cross-nested logit model.

Return type

biogeme.expressions.Expression

biogeme.models.logit(V, av, i)¶

The logit model

The model is defined as

\[\frac{a_i e^{V_i}}{\sum_{i=1}^J a_j e^{V_j}}\]

Parameters

V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
av (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.
i (int) – id of the alternative for which the probability must be calculated.

Returns

choice probability of alternative number i.

Return type

biogeme.expressions.Expression

biogeme.models.logmev(V, logGi, av, choice)¶

Log of the choice probability for a MEV model.

Parameters

V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
logGi – a dictionary mapping each alternative id with the function

\[\ln \frac{\partial G}{\partial y_i}(e^{V_1},\ldots,e^{V_J})\]

where \(G\) is the MEV generating function. If an alternative \(i\) is not available, then \(G_i = 0\).

Parameters

av (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.
choice (biogeme.expressions.Expression) – id of the alternative for which the probability must be calculated.

Returns

log of the choice probability of the MEV model, given by

\[V_i + \ln G_i(e^{V_1},\ldots,e^{V_J}) - \ln\left(\sum_j e^{V_j + \ln G_j(e^{V_1},\ldots,e^{V_J})}\right)\]

biogeme.models.logmev_selectionBias(V, logGi, av, correction, choice)¶

Log of choice probability for a MEV model, including the correction for endogenous sampling as proposed by Bierlaire, Bolduc and McFadden (2008).

Parameters

V – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
logGi – a dictionary mapping each alternative id with the function

\[\ln \frac{\partial G}{\partial y_i}(e^{V_1},\ldots,e^{V_J})\]

where \(G\) is the MEV generating function. If an alternative \(i\) is not available, then \(G_i = 0\).

Parameters

av (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.
correction (dict(int:biogeme.expressions.Expression)) – a dict of expressions for the correstion terms of each alternative.
choice (biogeme.expressions.Expression) – id of the alternative for which the probability must be calculated.

Returns

log of the choice probability of the MEV model, given by

\[V_i + \ln G_i(e^{V_1},\ldots,e^{V_J}) + \omega_i - \ln\left(\sum_j e^{V_j + \ln G_j(e^{V_1},\ldots,e^{V_J})+ \omega_j}\right)\]

where \(\omega_i\) is the correction term for alternative \(i\).

biogeme.models.lognested(V, availability, nests, choice)¶

Implements the log of a nested logit model as a MEV model.

Parameters

V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.
nests (tuple) –
A tuple containing as many items as nests. Each item is also a tuple containing two items
- an object of type biogeme.expressions.Expression representing the nest parameter,
- a list containing the list of identifiers of the alternatives belonging to the nest.
Example:
```
nesta = MUA , [1,2,3]
nestb = MUB , [4,5,6]
nests = nesta, nestb
```
choice (biogeme.expressions.Expression) – id of the alternative for which the probability must be calculated.

Returns

log of choice probability for the nested logit model, based on the derivatives of the MEV generating function produced by the function getMevForNested

biogeme.models.lognestedMevMu(V, availability, nests, choice, mu)¶

Implements the log of the nested logit model as a MEV model, where mu is also a parameter, if the user wants to test different normalization schemes.

Parameters

V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.
nests (tuple) –
A tuple containing as many items as nests. Each item is also a tuple containing two items
- an object of type biogeme.expressions.Expression representing the nest parameter,
- a list containing the list of identifiers of the alternatives belonging to the nest.
Example:
```
nesta = MUA , [1,2,3]
nestb = MUB , [4,5,6]
nests = nesta, nestb
```
choice (biogeme.expressions.Expression) – id of the alternative for which the probability must be calculated.
mu (biogeme.expressions.Expression) – expression producing the value of the top-level scale parameter.

Returns

the log of the nested logit choice probability based on the following derivatives of the MEV generating function:

\[\frac{\partial G}{\partial y_i}(e^{V_1},\ldots,e^{V_J}) = \mu e^{(\mu_m-1)V_i} \left(\sum_{i=1}^{J_m} e^{\mu_m V_i}\right)^{\frac{\mu}{\mu_m}-1}\]

where \(m\) is the (only) nest containing alternative \(i\), and \(G\) is the MEV generating function.

Return type: biogeme.expressions.Expression

biogeme.models.mev(V, logGi, av, choice)¶

Choice probability for a MEV model.

Parameters

V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
logGi – a dictionary mapping each alternative id with the function

\[\ln \frac{\partial G}{\partial y_i}(e^{V_1},\ldots,e^{V_J})\]

where \(G\) is the MEV generating function. If an alternative \(i\) is not available, then \(G_i = 0\).

Parameters

av (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.
choice (biogeme.expressions.Expression) – id of the alternative for which the probability must be calculated.

Returns

Choice probability of the MEV model, given by

\[\frac{e^{V_i + \ln G_i(e^{V_1},\ldots,e^{V_J})}}{\sum_j e^{V_j + \ln G_j(e^{V_1},\ldots,e^{V_J})}}\]

biogeme.models.mev_selectionBias(V, logGi, av, correction, choice)¶

Choice probability for a MEV model, including the correction for endogenous sampling as proposed by Bierlaire, Bolduc and McFadden (2008).

Parameters

V – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
logGi – a dictionary mapping each alternative id with the function

\[\ln \frac{\partial G}{\partial y_i}(e^{V_1},\ldots,e^{V_J})\]

where \(G\) is the MEV generating function. If an alternative \(i\) is not available, then \(G_i = 0\).

Parameters

av (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.
correction (dict(int:biogeme.expressions.Expression)) – a dict of expressions for the correstion terms of each alternative.
choice (biogeme.expressions.Expression) – id of the alternative for which the probability must be calculated.

Returns

log of the choice probability of the MEV model, given by

\[V_i + \ln G_i(e^{V_1},\ldots,e^{V_J}) + \omega_i - \ln\left(\sum_j e^{V_j + \ln G_j(e^{V_1},\ldots,e^{V_J})+ \omega_j}\right)\]

where \(\omega_i\) is the correction term for alternative \(i\).

biogeme.models.nested(V, availability, nests, choice)¶

Implements the nested logit model as a MEV model.

Parameters

V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.
nests (tuple) –
A tuple containing as many items as nests. Each item is also a tuple containing two items
- an object of type biogeme.expressions.Expression representing the nest parameter,
- a list containing the list of identifiers of the alternatives belonging to the nest.
Example:
```
nesta = MUA , [1,2,3]
nestb = MUB , [4,5,6]
nests = nesta, nestb
```
choice (biogeme.expressions.Expression) – id of the alternative for which the probability must be calculated.

Returns

choice probability for the nested logit model, based on the derivatives of the MEV generating function produced by the function getMevForNested

biogeme.models.nestedMevMu(V, availability, nests, choice, mu)¶

Implements the nested logit model as a MEV model, where mu is also a parameter, if the user wants to test different normalization schemes.

Parameters

V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.
nests (tuple) –
A tuple containing as many items as nests. Each item is also a tuple containing two items
- an object of type biogeme.expressions.Expression representing the nest parameter,
- a list containing the list of identifiers of the alternatives belonging to the nest.
Example:
```
nesta = MUA , [1,2,3]
nestb = MUB , [4,5,6]
nests = nesta, nestb
```
choice (biogeme.expressions.Expression) – id of the alternative for which the probability must be calculated.
mu (biogeme.expressions.Expression) – expression producing the value of the top-level scale parameter.

Returns

the nested logit choice probability based on the following derivatives of the MEV generating function:

\[\frac{\partial G}{\partial y_i}(e^{V_1},\ldots,e^{V_J}) = \mu e^{(\mu_m-1)V_i} \left(\sum_{i=1}^{J_m} e^{\mu_m V_i}\right)^{\frac{\mu}{\mu_m}-1}\]

where \(m\) is the (only) nest containing alternative \(i\), and \(G\) is the MEV generating function.

Return type: biogeme.expressions.Expression

biogeme.models.piecewise(variable, thresholds)¶

Generate the variables to include in a piecewise linear specification.

If there are K thresholds, K+1 variables are generated. If \(t\) is the variable of interest, for each interval \([a:a+b[\), we define a variable defined as:

\[\begin{split}x_{Ti} =\left\{ \begin{array}{ll} 0 & \text{if } t < a \\ t-a & \text{if } a \leq t < a+b \\ b & \text{otherwise} \end{array}\right. \;\;\;x_{Ti} = \max(0,\min(t-a,b)) \end{split}\]

Parameters

variable (biogeme.expressions.Expression) – variable for which we need the piecewise linear transform.
thresholds (list(float)) – list of thresholds

Returns

list of variables to for the piecewise linear specification.

Return type

list(biogeme.expressions.Expression)

biogeme.optimization module¶

Interface for the optimization algorithms.

author

Michel Bierlaire

date

Fri Aug 16 11:31:43 2019

note

An optimization algorithm takes as input:

a function taking three arguments:
- x: the vector of parameters
- hessian: a boolean specifying if the hessian must be calculated
- bhhh: a boolean specifying if the BHHH matrix must be calculated
- batchSize: if not None, the percentage of the data that must be sampled to obtain a stochastic version of the derivatives,
and returning f,g,h,bhhh. It characterizes the function to maximize;
a vector a starting values for the betas to be estimated,
a vector of values for the fixed betas,
a list of IDs of the betas to be estimated,
lower and upper bounds,
algorithm specific parameters.

It returns:

the optimal solution,

the number of iterations,

the number of function evaluations,

a diagnostic.

biogeme.optimization.cauchyNewtonDogleg(g, H)¶

Calculate the Cauchy, the Newton and the dogleg points.

The Cauchy point is defined as

\[d_c = - \frac{\nabla f(x)^T \nabla f(x)}{\nabla f(x)^T \nabla^2 f(x)\nabla f(x)} \nabla f(x)\]

The Newton point \(d_n\) verifies Newton’s equation:

\[H_s d_n = - \nabla f(x)\]

where \(H_s\) is a positive definite matrix generated with the method by Schnabel and Eskow (1999).

The Dogleg point is

\[d_d = \eta d_n\]

where

\[\eta = 0.2 + 0.8 \frac{\alpha^2}{\beta |\nabla f(x)^T d_n|}\]

and \(\alpha= \nabla f(x)^T \nabla f(x)\), \(\beta=\nabla f(x)^T \nabla^2 f(x)\nabla f(x)\)

Parameters

g (numpy.array) – gradient \(\nabla f(x)\)
H (numpy.array) – hessian \(\nabla^2 f(x)\)

Returns

tuple with Cauchy point, Newton point, Dogleg point

Return type

numpy.array, numpy.array, numpy.array

biogeme.optimization.dogleg(g, H, delta)¶

Find an approximation of the trust region subproblem using the dogleg method

Parameters

g (numpy.array) – gradient of the quadratic model.
H (numpy.array) – hessian of the quadratic model.
delta (float) – radius of the trust region.

Returns

d,diagnostic where

d is an approximate solution of the trust region subproblem
diagnostic is the nature of the solution:
- -2 if negative curvature along Newton’s direction
- -1 if negative curvature along Cauchy’s direction (i.e. along the gradient)
- 1 if partial Cauchy step
- 2 if Newton step
- 3 if partial Newton step
- 4 if Dogleg

Return type

numpy.array, int

biogeme.optimization.lineSearch(obj, x, d, alpha0=1.0, beta1=0.0001, beta2=0.99, lbd=2.0)¶

Calculate a step along a direction that satisfies both Wolfe conditions

Parameters

obj (function) – function taking x as argument as returning a tuple f,g with the value of the objective function f and the gradient g.
x (numpy.array) – current iterate.
d (numpy.array) – descent direction.
alpha0 (float) – first step to test.
beta1 (float) – parameter of the first Wolfe condition.
beta2 (float) – parameter of the second Wolfe condition.
lbd (float) – expansion factor for a short step.

Returns

a step verifing both Wolfe conditions

Return type

float

Raises

biogeme.exceptons.biogemeError – if lbd \(\leq\) 1
biogeme.exceptons.biogemeError – if alpha0 \(\leq\) 0
biogeme.exceptons.biogemeError – if beta1 \(\geq\) beta2
biogeme.exceptons.biogemeError – if d is not a descent direction

biogeme.optimization.newtonLineSearch(obj, x0, eps=6.06273418136464e-06, maxiter=100)¶

Newton’s method with inexact line search (Wolfe conditions)

Parameters

obj (function) –
function taking two arguments:
- x, the point where the function must be evaluated, and
- hessian, a boolean indicating if the hessian must be calculated and returning the tuple f,g,H with the value of the function, the gradient and the hessian.
x0 (numpy.array) – starting point
eps (float) – the algorithm stops when this precision is reached. Default: \(\varepsilon^{\frac{1}{3}}\)
maxiter (int) – the algorithm stops if this number of iterations is reached. Defaut: 100

Returns

x,nit,nf,diagnostic where

x is the solution generated by the algorithm,
nit is the number of iterations,
nf is the number of function evaluations,
diagnostic is the diagnostic provided by the algorithm.

Return type

numpy.array, int, int, string

biogeme.optimization.newtonLineSearchForBiogeme(fct, initBetas, fixedBetas, betaIds, bounds, parameters=None)¶

Optimization interface for Biogeme, based on Newton’s method.

Parameters

fct (function) –
a function taking three arguments:
- x, the vector of parameters;
- hessian, a boolean specifying if the hessian must be calculated;
- bhhh, a boolean specifying if the BHHH matrix must be calculated (ignored by this algorithm);
- batchSize, if not None, the percentage of the data that must be sampled to obtain a stochastic version of the derivatives (ignored by this algorithm),
and returning f,g,h,bhhh. It characterizes the function to maximize.
initBetas (numpy.array) – initial value of the parameters.
fixedBetas (numpy.array) – betas that stay fixed suring the optimization.
betaIds (numpy.array) – internal identifiers of the non fixed betas.
bounds (list(tuples)) – list of tuples (ell,u) containing the lower and upper bounds for each free parameter. Note that this algorithm does not support bound constraints. Therefore, all the bounds must be None.
parameters (dict(string:float or int)) – dict of parameters to be transmitted to the optimization routine: - tolerance, when the relavite gradient is below that threshold, the algorithm has reached convergence; - maxiter, the maximum number of iterations.

Returns

tuple x,nit,nfev,message, where

x is the solution found,
nit is the number of iterations performed,
nfev is the number of time that the objective function has been evaluated, and
message is the diagnostic provided by the algorithm.

Return type

numpy.array,int,int,string

biogeme.optimization.newtonTrustRegion(obj, x0, delta0=100, eps=6.06273418136464e-06, dl=False, maxiter=1000, eta1=0.01, eta2=0.9)¶

Newton’s method with trust region

Parameters

obj (function) –
function taking two arguments:
- x, the point where the function must be evaluated, and
- hessian, a boolean indicating if the hessian must be calculated and returning the tuple f,g,H with the value of the function, the gradient and the hessian.
x0 (numpy.array) – starting point
delta0 (float) – initial radius of the trust region. Default: 100.
eps (float) – the algorithm stops when this precision is reached. Default: \(\varepsilon^{\frac{1}{3}}\)
dl (bool) – If True, the Dogleg method is used to solve the trut region subproblem. If False, the truncated conjugate gradient is used. Default: False.
maxiter (int) – the algorithm stops if this number of iterations is reached. Default: 1000.
eta1 (float) – threshold for failed iterations. Default: 0.01.
eta2 (float) – threshold for very successful iterations. Default 0.9.

Returns

tuple x,nit,nfev,message, where x is the solution found, nit is the number of iterations performed, nfev is the number of time that the objective function has been evaluated, and message is the diagnostic provided by the algorithm.

Return type

numpay.array,int,int,string

biogeme.optimization.newtonTrustRegionForBiogeme(fct, initBetas, fixedBetas, betaIds, bounds, parameters=None)¶

Optimization interface for Biogeme, based on Newton’s method with TR.

Parameters

fct (function) –
a function taking three arguments:
- x, the vector of parameters;
- hessian, a boolean specifying if the hessian must be calculated;
- bhhh, a boolean specifying if the BHHH matrix must be calculated (ignored by this algorithm);
- batchSize, if not None, the percentage of the data that must be sampled to obtain a stochastic version of the derivatives (ignored by this algorithm),
and returning f,g,h,bhhh. It characterizes the function to maximize.
initBetas (numpy.array) – initial value of the parameters.
fixedBetas (numpy.array) – betas that stay fixed suring the optimization.
betaIds (numpy.array) – internal identifiers of the non fixed betas.
bounds (list(tuples)) – list of tuples (ell,u) containing the lower and upper bounds for each free parameter. Note that this algorithm does not support bound constraints. Therefore, all the bounds must be None.
parameters (dict(string:float or int)) – dict of parameters to be transmitted to the optimization routine: - tolerance, when the relavite gradient is below that threshold, the algorithm has reached convergence; - maxiter, the maximum number of iterations. - bhhh, True is BHHH matrix is used instead of the hessian

Returns

tuple x,nit,nfev,message, where

x is the solution found,
nit is the number of iterations performed,
nfev is the number of time that the objective function has been evaluated, and
message is the diagnostic provided by the algorithm.

Return type

numpy.array,int,int,string

biogeme.optimization.relativeGradient(x, f, g, typx, typf)¶

Calculates the relative gradients.

It is typically used for stopping criteria.

Parameters

x (numpy.array) – current iterate.
f (float) – value of f(x)
g (numpy.array) – \(\nabla f(x)\), gradient of f at x
typx (numpy.array) – typical value for x.
typf (float) – typical value for f.

Returns

relative gradient

\[\max_{i=1,\ldots,n}\frac{(\nabla f(x))_i \max(x_i,\text{typx}_i)}{\max(|f(x)|, \text{typf})}\]

Return type: float

biogeme.optimization.schnabelEskow(A, tau=6.06273418136464e-06, taubar=3.6756745753887175e-11, mu=0.1)¶

Modified Cholesky factorization by Schnabel and Eskow (1999).

If the matrix is ‘safely’ positive definite, the output is the classical Cholesky factor. If not, the diagonal elements are inflated in order to make it positive definite. The factor \(L\) is such that \(A + E = PLL^TP^T\), where \(E\) is a diagonal matrix contaninig the terms added to the diagonal, \(P\) is a permutation matrix, and \(L\) is w lower triangular matrix.

Parameters

A (numpy.array) – matrix to factorize. Must be square and symmetric.
tau (float) – tolerance factor. Default: \(\varepsilon^{\frac{1}{3}}\). See Schnabel and Eskow (1999)
taubar (float) – tolerance factor. Default: \(\varepsilon^{\frac{2}{3}}\). See Schnabel and Eskow (1999)
mu (float) – tolerance factor. Default: 0.1. See Schnabel and Eskow (1999)

Returns

tuple \(L\), \(E\), \(P\), where \(A + E = PLL^TP^T\).

Return type

numpy.array, numpy.array, numpy.array

biogeme.optimization.scipy(fct, initBetas, fixedBetas, betaIds, bounds, parameters=None)¶

Optimization interface for Biogeme, based on the scipy minimize function.

Parameters

fct (function) –
a function taking four arguments:
- x, the vector of parameters;
- hessian, a boolean specifying if the hessian must be calculated;
- bhhh, a boolean specifying if the BHHH matrix must be calculated:
- batchSize, if not None, the percentage of the data that must be sampled to obtain a stochastic version of the derivatives,
and returning f,g,h,bhhh. It characterizes the function to maximize.
initBetas (numpy.array) – initial value of the parameters
fixedBetas (numpy.array) – betas that stay fixed suring the optimization
betaIds (numpy.array) – internal identifiers of the non fixed betas
bounds (list(tuple)) – list of tuples (ell,u) containing the lower and upper bounds for each free parameter
parameters (dict(string:float or string)) – dict of parameters to be transmitted to the optimization routine.

Returns

tuple x,nit,nfev,message, where x is the solution found, nit is the number of iterations performed, nfev is the number of time that the objective function has been evaluated, and message is the diagnostic provided by the algorithm.

Return type

numpay.array,int,int,string

biogeme.optimization.truncatedConjugateGradient(g, H, delta)¶

Find an approximation of the trust region subproblem using the truncated conjugate gradient method

Parameters

g (numpy.array) – gradient of the quadratic model.
H (numpy.array) – hessian of the quadrartic model.
delta (float) – radius of the trust region.

Returns

d,diagnostic, where

d is the approximate solution of the trust region subproblem,
diagnostic is the nature of the solution:
- 1 for convergence,
- 2 if out of the trust region,
- 3 if negative curvature detected.

Return type

numpy.array, int

biogeme.optimization.trustRegionIntersection(dc, d, delta)¶

Calculates the intersection with the boundary of the trust region.

Consider a trust region of radius \(\delta\), centered at \(\hat{x}\). Let \(x_c\) be in the trust region, and \(d_c = x_c - \hat{x}\), so that \(\|d_c\| \leq \delta\). Let \(x_d\) be out of the trust region, and \(d_d = x_d - \hat{x}\), so that \(\|d_d\| \geq \delta\). We calculate \(\lambda\) such that

\[\| d_c + \lambda (d_d - d_c)\| = \delta\]

Parameters

dc (numpy.array) – xc-xhat.
d (numpy.array) – dd - dc.
delta (float) – radius of the trust region.

Returns

\(\lambda\) such that \(\| d_c + \lambda (d_d - d_c)\| = \delta\)

Return type

float

biogeme.results module¶

Implementation of class contaning and processing the estimation results.

author: Michel Bierlaire
date: Tue Mar 26 16:50:01 2019

class biogeme.results.beta(name, value, bounds)¶

Bases: object

Class gathering the information related to the parameters of the model

__init__(name, value, bounds)¶

Constructor

Parameters

name (string) – name of the parameter.
value (float) – value of the parameter.
bounds (float,float) – tuple (l,b) with lower and upper bounds

isBoundActive(threshold=1e-06)¶

Check if one of the two bound is “numerically” active.

Being numerically active means that the distance between the value of the parameter and one of its bounds is below the threshold.

Parameters: threshold – distance below which the bound is considered to be active. Default: \(10^{-6}\)
Returns: True is one of the two bounds is numericall y active.
Return type: bool

setBootstrapStdErr(se)¶

Records the robust standard error calculated by bootstrap, and calculates and records the corresponding t-statistic and p-value

Parameters: se (float) – standard error calculated by bootstrap.

setRobustStdErr(se)¶

Records the robust standard error, and calculates and records: the corresponding t-statistic and p-value

Parameters: se (float) – robust standard error

setStdErr(se)¶

Records the standard error, and calculates and records: the corresponding t-statistic and p-value

Parameters: se (float) – standard error.

class biogeme.results.bioResults(rawResults=None, pickleFile=None)¶

Bases: object

Class managing the estimation results

__init__(rawResults=None, pickleFile=None)¶

Constructor

Parameters

rawResults (biogeme.results.rawResults) – object with the results of the estimation. Default: None.
pickleFile (string) – name of the file containing the raw results in pickle format. Default: None.

Raises

biogeme.exceptions.biogemeError – if no data is provided.

getBetaValues(myBetas=None)¶

Retrieve the values of the estimated parameters, by names.

Parameters: myBetas (list(string)) – names of the requested parameters. If None, all available parameters will be reported. Default: None.
Returns: dict containing the values, where the keys are the names.
Return type: dict(string:float)
Raises: biogeme.exceptions.biogemeError – if some requested parameters are not available.

getBetasForSensitivityAnalysis(myBetas, size=100, useBootstrap=False)¶

Generate draws from the distribution of the estimates, for sensitivity analysis.

Parameters

myBetas (list(string)) – names of the parameters for which draws are requested.
size (int) – number of draws. Default: 100.
useBootstrap (bool) – if True, the variance-covariance matrix generated by the bootstrapping is used for simulation. If False, the robust variance-covariance matrix is used. Default: False.

Raises

biogeme.exceptions.biogemeError – if useBootstrap is True and the bootstrap matrix is not available.

Returns

numpy table with as many rows as draws, and as many columns as parameters.

Return type

numpy.array

getBootstrapVarCovar()¶

Obtain the bootstrap variance covariance matrix as a Pandas data frame.

Returns: bootstrap variance covariance matrix, or None if not available
Return type: pandas.DataFrame

getCorrelationResults()¶

Get the statistics about pairs of coefficients as a Pandas dataframe

Returns: Pandas data frame with the correlation results
Rtpye: pandas.DataFrame

getEstimatedParameters()¶

Gather the estimated parameters and the corresponding statistics in a Pandas dataframe.

return

Pandas dataframe with the results

rtype

pandas.DataFrame

getGeneralStatistics()¶

Format the results in a dict

Returns: dict with the results. The keys describe each content. Each element is a tuple, with the value and its preferred formatting.

Example:

'Init log likelihood': (-115.30029248549191, '.7g')

Return type: dict(string:float,string)

getHtml()¶

Get the results coded in HTML

Returns: HTML code
Rtpye: string

getLaTeX()¶

Get the results coded in LaTeX

Returns: LaTeX code
Return type: string

getRobustVarCovar()¶

Obtain the robust variance covariance matrix as a Pandas data frame.

Returns: robust variance covariance matrix
Return type: pandas.DataFrame

getVarCovar()¶

Obtain the Rao-Cramer variance covariance matrix as a Pandas data frame.

Returns: Rao-Cramer variance covariance matrix
Return type: pandas.DataFrame

writeHtml()¶: Write the results in an HTML file.

writeLaTeX()¶: Write the results in a LaTeX file.

writePickle()¶

Dump the data in a file in pickle format.

Returns: name of the file.
Return type: string

biogeme.results.calcPValue(t)¶

Calculates the p value of a parameter from its t-statistic.

The formula is

\[2(1-\Phi(|t|)\]

where \(\Phi(\cdot)\) is the CDF of a normal distribution.

Parameters: t – t-statistics
Type: float
Returns: p-value
Return type: float

class biogeme.results.rawResults(theModel, betaValues, fgHb, bootstrap=None)¶

Bases: object

Class containing the raw results from the estimation

__init__(theModel, betaValues, fgHb, bootstrap=None)¶

Constructor

Parameters

theModel (biogeme.BIOGEME) – object with the model
betaValues (list(float)) – list containing the estimated values of the parameters
fgHb (float,numpy.array, numpy.array, numpy.array) –
tuple f,g,H,bhhh containing
- f: the value of the function,
- g: the gradient,
- H: the second derivative matrix,
- bhhh: the BHHH matrix.
bootstrap (numpy.array) –
output of the bootstrapping. numpy array, of size B x K, where
- B is the number of bootstrap iterations
- K is the number of parameters to estimate
  
  Default: None.

biogeme.tools module¶

Implements some useful functions

author: Michel Bierlaire
date: Sun Apr 14 10:46:10 2019

biogeme.tools.calculatePrimeNumbers(upperBound)¶

Calculate prime numbers

Parameters: upperBound (int) – prime numbers up to this value will be computed
Returns: array with prime numbers
Return type: list(int)

biogeme.tools.checkDerivatives(theFunction, x, names=None, logg=False)¶

Verifies the analytical derivatives of a function by comparing them with finite difference approximations.

Parameters

theFunction (function) –
A function object that takes a vector as an argument, and returns a tuple.
- The first element of the tuple is the value of the function \(f\),
- the second is the gradient of the function,
- the third is the hessian.
x (numpy.array) – arguments of the function
names (list(string)) – the names of the entries of x (for reporting).
logg (bool) – if True, messages will be displayed.

Returns

tuple f,g,h,gdiff,hdiff where

f is the value of the function at x,
g is the analytical gradient,
h is the analytical hessian,
gdiff is the difference between the analytical gradient and the finite difference approximation
hdiff is the difference between the analytical hessian and the finite difference approximation

Return type

float, numpy.array,numpy.array, numpy.array,numpy.array

biogeme.tools.countNumberOfGroups(df, column)¶: This function counts the number of groups of same value in a column. For instance: 1,2,2,3,3,3,4,1,1 would give 5

biogeme.tools.findiff_H(theFunction, x)¶

Calculates the hessian of a function \(f\) using finite differences

Parameters

theFunction (function) – A function object that takes a vector as an argument, and returns a tuple. The first element of the tuple is the value of the function \(f\), and the second is the gradient of the function. The other elements are not used.
x (numpy.array) – argument of the function

Returns

numpy matrix containing the hessian calculated by finite differences.

Return type

numpy.array

biogeme.tools.findiff_g(theFunction, x)¶

Calculates the gradient of a function :math`f` using finite differences

Parameters

theFunction (function) – A function object that takes a vector as an argument, and returns a tuple. The first element of the tuple is the value of the function \(f\). The other elements are not used.
x (numpy.array) – argument of the function

Returns

numpy vector, same dimension as x, containing the gradient calculated by finite differences.

Return type

numpy.array

biogeme.tools.getPrimeNumbers(n)¶

Get a given number of prime numbers

Parameters: n (int) – number of primes that are requested
Returns: array with prime numbers
Return type: list(int)

biogeme.version module¶

biogeme.version.getHtml()¶

Package information in HTML format

Returns: HTML code.
Return type: string

biogeme.version.getLaTeX()¶

Package information in LaTeX format

Returns: LaTeX comments
Return type: string

biogeme.version.getText()¶

Package information in text format

Returns: package information
Return type: string

biogeme.version.getVersion()¶

Version of the software

Returns: version number, and the release.
Return type: string