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
See also: getSampleSize()
-
getSampleSize
()¶ Reports the size of the sample.
If the data is cross-sectional, it is the number of observations in the database. If the data is panel, it is the number of individuals.
- Returns
Sample size.
- Return type
int
See also: getNumberOfObservations()
-
isPanel
()¶ Tells if the data is panel or not.
- Returns
True if the data is panel.
- Return type
bool
-
panel
(columnName)¶ Defines the data as panel data
- Parameters
columnName (string) – name of the columns that identifies individuals.
-
remove
(expression)¶ Removes from the database all entries such that the value of the expression is not 0.
- Parameters
expression (biogeme.expressions.Expression) – expression to evaluate
-
sampleIndividualMapWithReplacement
(size=None)¶ Extract a random sample of the individual map from a panel data database, with replacement.
Useful for bootstrapping.
- Parameters
size (int) – size of the sample. If None, a sample of the same size as the database will be generated. Default: None.
- Returns
pandas dataframe with the sample.
- Return type
pandas.DataFrame
-
sampleWithReplacement
(size=None)¶ Extract a random sample from the database, with replacement.
Useful for bootstrapping.
- Parameters
size (int) – size of the sample. If None, a sample of the same size as the database will be generated. Default: None.
- Returns
pandas dataframe with the sample.
- Return type
pandas.DataFrame
-
scaleColumn
(column, scale)¶ Multiply an entire column by a scale value
- Parameters
column (string) – name of the column
scale (float) – value of the scale. All values of the column will be multiplied by that scale.
-
setRandomNumberGenerators
(rng)¶ Defines user-defined random numbers generators.
- Parameters
rng (dict) – a dictionary of generators. The keys of the dictionary characterize the name of the generators, and must be different from the pre-defined generators in Biogeme: NORMAL, UNIFORM and UNIFORMSYM. The elements of the dictionary are functions that take two arguments: the number of series to generate (typically, the size of the database), and the number of draws per series.
Example:
def logNormalDraws(sampleSize,numberOfDraws): return np.exp(np.random.randn(sampleSize,numberOfDraws)) def exponentialDraws(sampleSize,numberOfDraws): return -1.0 * np.log(np.random.rand(sampleSize,numberOfDraws)) # We associate these functions with a name dict = {'LOGNORMAL':(logNormalDraws,'Draws from lognormal distribution'),'EXP':(exponentialDraws,'Draws from exponential distributions')} myData.setRandomNumberGenerators(dict)
-
suggestScaling
()¶ Suggest a scaling of the variables in the database.
For each column, \(\delta\) is the difference between the largest and the smallest value, or one if the difference is smaller than one. The level of magnitude is evaluated as a power of 10. The suggested scale is the inverse of this value.
\[s = \frac{1}{10^{|\log_{10} \delta|}}\]where \(|x|\) is the integer closest to \(x\).
- Returns
A Pandas dataframe where each row contains the name of the variable and the suggested scale s. Ideally, the column should be multiplied by s.
- Return type
pandas.DataFrame
-
sumFromDatabase
(expression)¶ Calculates the value of an expression for each entry in the database, and returns the sum.
- Parameters
expression (biogeme.expressions.Expression) – expression to evaluate
- Returns
sum of the expressions over the database.
- Return type
float
-
valuesFromDatabase
(expression)¶ Evaluates an expression for each entry of the database.
- Parameters
expression (biogeme.expressions.Expression.) – expression to evaluate
- Returns
numpy series, long as the number of entries in the database, containing the calculated quantities.
- Return type
numpy.Series
-
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.
-
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
-
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
-
__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
-
__div__
(other)¶ Operator overloading. Generate an expression for division.
- Parameters
other (biogeme.expressions.Expression) – expression for division
- Returns
self / other
- Return type
-
__eq__
(other)¶ Operator overloading. Generate an expression for comparison.
- Parameters
other (biogeme.expressions.Expression) – expression for equality
- Returns
self == other
- Return type
-
__ge__
(other)¶ Operator overloading. Generate an expression for comparison.
- Parameters
other (biogeme.expressions.Expression) – expression for greater or equal
- Returns
self >= other
- Return type
-
__gt__
(other)¶ Operator overloading. Generate an expression for comparison.
- Parameters
other (biogeme.expressions.Expression) – expression for greater than
- Returns
self > other
- Return type
-
__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
-
__lt__
(other)¶ Operator overloading. Generate an expression for comparison.
- Parameters
other (biogeme.expressions.Expression) – expression for less than
- Returns
self < other
- Return type
-
__mul__
(other)¶ Operator overloading. Generate an expression for multiplication.
- Parameters
other (biogeme.expressions.Expression) – expression to be multiplied
- Returns
self * other
- Return type
-
__ne__
(other)¶ Operator overloading. Generate an expression for comparison.
- Parameters
other (biogeme.expressions.Expression) – expression for difference
- Returns
self != other
- Return type
-
__neg__
()¶ Operator overloading. Generate an expression for unary minus.
- Returns
-self
- Return type
-
__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
-
__pow__
(other)¶ Operator overloading. Generate an expression for power.
- Parameters
other (biogeme.expressions.Expression) – expression for power
- Returns
self ^ other
- Return type
-
__radd__
(other)¶ Operator overloading. Generate an expression for addition.
- Parameters
other (biogeme.expressions.Expression) – expression to be added
- Returns
other + self
- Return type
-
__rdiv__
(other)¶ Operator overloading. Generate an expression for division.
- Parameters
other (biogeme.expressions.Expression) – expression for division
- Returns
other / self
- Return type
-
__rmul__
(other)¶ Operator overloading. Generate an expression for multiplication.
- Parameters
other (biogeme.expressions.Expression) – expression to be multiplied
- Returns
other * self
- Return type
-
__rpow__
(other)¶ Operator overloading. Generate an expression for power.
- Parameters
other (biogeme.expressions.Expression) – expression for power
- Returns
other ^ self
- Return type
-
__rsub__
(other)¶ Operator overloading. Generate an expression for substraction.
- Parameters
other (biogeme.expressions.Expression) – expression to be substracted
- Returns
other - self
- Return type
-
__rtruediv__
(other)¶ Operator overloading. Generate an expression for division.
- Parameters
other (biogeme.expressions.Expression) – expression for division
- Returns
other / self
- Return type
-
__sub__
(other)¶ Operator overloading. Generate an expression for substraction.
- Parameters
other (biogeme.expressions.Expression) – expression to substract
- Returns
self - other
- Return type
-
__truediv__
(other)¶ Operator overloading. Generate an expression for division.
- Parameters
other (biogeme.expressions.Expression) – expression for division
- Returns
self / other
- Return type
-
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. 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
-
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
-
setOfVariables
()¶ Extract the set of variables used in the expression.
- Returns
returns a set with the variables appearing in the expression.
- Return type
-
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
-
-
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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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
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.
- 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.
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