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, userNotes=None, numberOfThreads=None, numberOfDraws=1000, seed=None, skipAudit=False, removeUnusedVariables=True, suggestScales=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, userNotes=None, numberOfThreads=None, numberOfDraws=1000, seed=None, skipAudit=False, removeUnusedVariables=True, suggestScales=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.
userNotes (str) – these notes will be included in the report file.
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.
suggestScales (bool.) – if True, Biogeme suggests the scaling of the variables in the database. Default: True. See also
biogeme.database.Database.suggestScaling()
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, scaled, batch=None)¶ Calculates the value of the log likelihood function
- Parameters
x (list(float)) – vector of values for the parameters.
scaled (bool) – if True, the value is diviced by the number of observations used to calculate it. In this case, the values with different sample sizes are comparable. Default: True
batch (float) – if not None, calculates the likelihood on a random sample of the data. The value of the parameter must be strictly between 0 and 1, and represents the share of the data that will be used. Default: None
- Returns
the calculated value of the log likelihood
- Return type
float.
- Raises
ValueError – if the length of the list x is incorrect.
-
calculateLikelihoodAndDerivatives
(x, scaled, hessian=False, bhhh=False, batch=None)¶ 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.
batch (float) – if not None, calculates the likelihood on a random sample of the data. The value of the parameter must be strictly between 0 and 1, and represents the share of the data that will be used. Default: None
- 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, bounds, parameters)¶ Invokes the CFSQP algorithm for estimation
- Parameters
betas (list of float) – initial values of the parameters 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
- Returns
x, messages
x is the solution generated by the algorithm,
messages is a dictionary describing information about the lagorithm
- Return type
numpay.array, dict(str:object)
-
changeInitValues
(betas)¶ Modifies the initial values of the pameters in all formula
- Parameters
betas (dict(string:float)) – dictionary where the keys are the names of the parameters, and the values are the new value for the parameters.
-
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(str: 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
(verbosity=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
verbosity –
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 simpleBoundsNewtonAlgorithmForBiogeme>, algoParameters=None, cfsqp_default_bounds=1000.0, saveIterations=False, file_iterations='__savedIterations.txt')¶ 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 . Default: Biogeme’s Newton’s algorithm with simple bounds.
algoParameters (dict) – parameters to transfer to the optimization algorithm
cfsqp_default_bounds (float) – if the user does not provide bounds on the parameters, CFSQP assumes that the bounds are [-cfsqp_default_bounds, cfsqp_default_bounds]
saveIterations (bool) – if True, the values of the parameters corresponding to the largest value of the likelihood function are saved in a pickle file at each iteration of the algorithm. Default: False.
file_iterations (str) – name of the file where to save the values of the parameters. Default: ‘__savedIterations.txt’
- 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
-
loadSavedIteration
(filename='__savedIterations.txt')¶ Reads the values of the parameters from a text file where each line has the form name_of_beta = value_of_beta, and use these values in all formulas.
- param filename
name of the text file to read. Default: ‘__savedIterations.txt’
- type filename
str.
-
optimize
(startingValues=None)¶ Calls the optimization algorithm.
The function self.algorithm is called. If None, CFSQP is invoked.
- Parameters
startingValues – starting point for the algorithm
- Type
list(float)
- Returns
x, messages
x is the solution generated by the algorithm,
messages is a dictionary describing several information about the lagorithm
- Return type
numpay.array, dict(str:object)
-
quickEstimate
(algorithm=<function simpleBoundsNewtonAlgorithmForBiogeme>, algoParameters=None)¶ - Estimate the parameters of the model. Same as estimate, where any extra
calculation is skipped (init loglikelihood, t-statistics, etc.)
- Parameters
algorithm (function) – optimization algorithm to use for the maximum likelihood estimation. If None, cfsqp is . Default: Biogeme’s Newton’s algorithm with simple bounds.
algoParameters (dict) – parameters to transfer to the optimization algorithm
- Returns
object containing the estimation results.
- Return type
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.quickEstimate()
- Raises
biogemeError – if no expression has been provided for the likelihood
-
simulate
(theBetaValues=None)¶ Applies the formulas to each row of the database.
- Parameters
theBetaValues (dict(str, 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
-
validate
(estimationResults, slices=5)¶ Perform out-of-sample validation.
The function performs the following tasks:
it shuffles the data set,
it splits the data set into slices of (approximatively) the same size,
each slice defines a validation set (the slice itself) and an estimation set (the rest of the data),
the model is re-estimated on the estimation set,
the estimated model is applied on the validation set,
the value of the log likelihood for each observation is reported.
- Parameters
estimationResults (biogeme.results.bioResults) – results of the model estimation based on the full data.
slices (int) – number of slices.
- Returns
a list containing as many items as slices. Each item is the result of the simulation on the validation set.
- Return type
list(pandas.DataFrame)
-
-
class
biogeme.biogeme.
negLikelihood
(like, like_deriv, scaled)¶ Bases:
biogeme.optimization.functionToMinimize
Provides the value of the function to be minimized, as well as its derivatives. To be used by the opimization package.
-
__init__
(like, like_deriv, scaled)¶ Constructor
-
f
(batch=None)¶ Calculate the value of the function
- Parameters
batch (float) – for data driven functions (such as a log likelikood function), it is possible to approximate the value of the function using a sample of the data called a batch. This argument is a value between 0 and 1 representing the percentage of the data that should be used for thre random batch. If None, the full data set is used. Default: None pass
- Returns
value of the function
- Return type
float
-
f_g
(batch=None)¶ Calculate the value of the function and the gradient
- Parameters
batch (float) – for data driven functions (such as a log likelikood function), it is possible to approximate the value of the function using a sample of the data called a batch. This argument is a value between 0 and 1 representing the percentage of the data that should be used for the random batch. If None, the full data set is used. Default: None pass
- Returns
value of the function and the gradient
- Return type
tuple float, numpy.array
-
f_g_bhhh
(batch=None)¶ Calculate the value of the function, the gradient and the BHHH matrix
- Parameters
batch (float) – for data driven functions (such as a log likelikood function), it is possible to approximate the value of the function using a sample of the data called a batch. This argument is a value between 0 and 1 representing the percentage of the data that should be used for the random batch. If None, the full data set is used. Default: None pass
- Returns
value of the function, the gradient and the BHHH
- Return type
tuple float, numpy.array, numpy.array
-
f_g_h
(batch=None)¶ Calculate the value of the function, the gradient and the Hessian
- Parameters
batch (float) – for data driven functions (such as a log likelikood function), it is possible to approximate the value of the function using a sample of the data called a batch. This argument is a value between 0 and 1 representing the percentage of the data that should be used for the random batch. If None, the full data set is used. Default: None pass
- Returns
value of the function, the gradient and the Hessian
- Return type
tuple float, numpy.array, numpy.array
-
setVariables
(x)¶ Set the values of the variables for which the function has to b calculated.
- Parameters
x (numpy.array) – values
-
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.
-
buildPanelMap
()¶ Sorts the data so that the observations for each individuals are contiguous, and builds a map that identifies the range of indices of the observations of each individuals.
-
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
-
sampleWithoutReplacement
(samplingRate, columnWithSamplingWeights=None)¶ Replace the data set by a sample for stochastic algorithms
- Parameters
samplingRate (float) – the proportion of data to include in the sample.
columnWithSamplingWeights – name of the column with the sampling weights. If None, each row has equal probability.
columnWithSamplingWeights – string
- Returns
None
-
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)
-
split
(slices)¶ Prepare estimation and validation sets for validation.
- Parameters
slices (int) – number of slices
- Returns
list of estimation and validation data sets
- Return type
tuple(pandas.DataFrame, pandas.DataFrame)
-
suggestScaling
(columns=None)¶ 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\).
- Parameters
columns (list(str)) – list of columns to be considered. If None, all of them will be considered.
- 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
-
useFullSample
()¶ Re-establish the full sample for calculation of the likelihood
-
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=0.0, s=1.0)¶ Log normal pdf
Probability density function of a log normal distribution
\[f(x;\mu, \sigma) = \frac{1}{x\sigma \sqrt{2\pi}} \exp{-\frac{(\ln x-\mu)^2}{2\sigma^2}}\]- Parameters
x (float or biogeme.expression) – location parameter \(\mu\) of the lognormal distribution. Default: 0.
s (float or biogeme.expression) – scale parameter \(\sigma\) of the lognormal distribution. Default: 1.
- Note
It is assumed that \(\sigma > 0\), but it is not verified by the code.
- Returns
value of the lognormal pdf.
- Return type
float or biogeme.expression
-
biogeme.distributions.
normalpdf
(x, mu=0.0, s=1.0)¶ Normal pdf
Probability density function of a normal distribution
\[f(x;\mu, \sigma) = \frac{1}{\sigma \sqrt{2\pi}} \exp{-\frac{(x-\mu)^2}{2\sigma^2}}\]- Parameters
x (float or biogeme.expression) – location parameter \(\mu\) of the Normal distribution. Default: 0.
s (float or biogeme.expression) – scale parameter \(\sigma\) of the Normal distribution. Default: 1.
- Note
It is assumed that \(\sigma > 0\), but it is not verified by the code.
- Returns
value of the Normal pdf.
- Return type
float or biogeme.expression
-
biogeme.distributions.
triangularpdf
(x, a=-1.0, b=1.0, c=0.0)¶ Triangular pdf
Probability density function of a triangular distribution
\[\begin{split}f(x;a, b, c) = \left\{ \begin{array}{ll} 0 & \text{if } x < a \\\frac{2(x-a)}{(b-a)(c-a)} & \text{if } a \leq x < c \\\frac{2(b-x)}{(b-a)(b-c)} & \text{if } c \leq x < b \\0 & \text{if } x \geq b. \end{array} \right.\end{split}\]- Parameters
x (float or biogeme.expression) – argument of the pdf
a (float or biogeme.expression) – lower bound \(a\) of the distribution. Default: -1.
b (float or biogeme.expression) – upper bound \(b\) of the distribution. Default: 1.
c (float or biogeme.expression) – mode \(c\) of the distribution. Default: 0.
- Note
It is assumed that \(a < c < b\), but it is not verified by the code.
- Returns
value of the triangular pdf.
- Return type
float or biogeme.expression
-
biogeme.distributions.
uniformpdf
(x, a=-1, b=1.0)¶ Uniform pdf
Probability density function of a uniform distribution.
\[\begin{split}f(x;a, b) = \left\{ \begin{array}{ll} \frac{1}{b-a} & \text{for } x \in [a, b] \\ 0 & \text{otherwise}\end{array} \right.\end{split}\]- Parameters
x (float or biogeme.expression) – argument of the pdf
a (float or biogeme.expression) – lower bound \(a\) of the distribution. Default: -1.
b (float or biogeme.expression) – upper bound \(b\) of the distribution. Default: 1.
- Note
It is assumed that \(a < b\), but it is not verified by the code.
- Returns
value of the uniform pdf.
- Return type
float or biogeme.expression
biogeme.draws module¶
Generation of various types of draws.
- author
Michel Bierlaire
- date
Tue Jun 18 19:05:13 2019
-
biogeme.draws.
getAntithetic
(unif, sampleSize, numberOfDraws)¶ Returns antithetic uniform draws
- Parameters
unif (function) – function taking two arguments (sampleSize, numberOfDraws) and returning U[0, 1] draws
sampleSize (int) – number of observations for which draws must be generated. If None, a one dimensional array will be generated. If it has a values k, then k series of draws will be generated
numberOfDraws (int) – number of draws to generate.
- Returns
numpy array with the antithetic draws
- Return type
numpy.array
Example:
draws = dr.getAntithetic(dr.getUniform, sampleSize=3, numberOfDraws=10) array([[0.48592363, 0.13648133, 0.35925946, 0.32431338, 0.32997936, 0.51407637, 0.86351867, 0.64074054, 0.67568662, 0.67002064], [0.89261997, 0.0331808 , 0.30767182, 0.93433648, 0.17196124, 0.10738003, 0.9668192 , 0.69232818, 0.06566352, 0.82803876], [0.81095587, 0.96171364, 0.40984817, 0.72177258, 0.16481096, 0.18904413, 0.03828636, 0.59015183, 0.27822742, 0.83518904]])
-
biogeme.draws.
getHaltonDraws
(sampleSize, numberOfDraws, symmetric=False, base=2, skip=0, shuffled=False)¶ Generate Halton draws
- Parameters
sampleSize (int) – number of observations for which draws must be generated. If None, a one dimensional array will be generated. If it has a values k, then k series of draws will be generated
numberOfDraws (int) – number of draws to generate.
symmetric (bool) – if True, draws from [-1: 1] are generated. If False, draws from [0: 1] are generated. Default: False
base (int) – generate Halton draws for a given basis. Ideally, it should be a prime number. Default: 2.
skip (int) – the number of elements of the sequence to be discarded.
shuffled (bool) – if True, each series is shuffled
- Returns
numpy array with the draws
- Return type
numpy.array
Example:
halton = dr.getHaltonDraws(sampleSize=2, numberOfDraws=10, base=3) array([[0.33333333, 0.66666667, 0.11111111, 0.44444444, 0.77777778, 0.22222222, 0.55555556, 0.88888889, 0.03703704, 0.37037037], [0.7037037 , 0.14814815, 0.48148148, 0.81481481, 0.25925926, 0.59259259, 0.92592593, 0.07407407, 0.40740741, 0.74074074]])
-
biogeme.draws.
getLatinHypercubeDraws
(sampleSize, numberOfDraws, symmetric=False, uniformNumbers=None)¶ - Implementation of the Modified Latin Hypercube Sampling proposed
by Hess et al, 2006.
- Parameters
sampleSize (int) – number of observations for which draws must be generated. If None, a one dimensional array will be generated. If it has a values k, then k series of draws will be generated
numberOfDraws (int) – number of draws to generate.
symmetric (bool) – if True, draws from [-1: 1] are generated. If False, draws from [0: 1] are generated. Default: False
uniformNumbers (numpy.array) – numpy with uniformly distributed numbers. If None, the numpy uniform number generator is used.
- Returns
numpy array with the draws
- Return type
numpy.array
Example:
latinHypercube = dr.getLatinHypercubeDraws(sampleSize=3, numberOfDraws=10) array([[0.43362897, 0.5275741 , 0.09215663, 0.94056236, 0.34376868, 0.87195551, 0.41495219, 0.71736691, 0.23198736, 0.145561 ], [0.30520544, 0.78082964, 0.83591146, 0.2733167 , 0.53890906, 0.61607469, 0.00699715, 0.17179441, 0.7557228 , 0.39733102], [0.49676864, 0.67073483, 0.9788854 , 0.5726069 , 0.11894558, 0.05515471, 0.2640275 , 0.82093696, 0.92034628, 0.64866597]])
-
biogeme.draws.
getNormalWichuraDraws
(sampleSize, numberOfDraws, uniformNumbers=None, antithetic=False)¶ Generate pseudo-random numbers from a normal distribution N(0, 1)
It uses the Algorithm AS241 Appl. Statist. (1988) Vol. 37, No. 3, which produces the normal deviate z corresponding to a given lower tail area of p; z is accurate to about 1 part in \(10^{16}\).
- Parameters
sampleSize (int) – number of observations for which draws must be generated. If None, a one dimensional array will be generated. If it has a values k, then k series of draws will be generated
numberOfDraws (int) – number of draws to generate.
uniformNumbers (numpy.array) – numpy with uniformly distributed numbers. If None, the numpy uniform number generator is used.
antithetic (bool) – if True, only half of the draws are actually generated, and the series are completed with their antithetic version.
- Returns
numpy array with the draws
- Return type
numpy.array
Example:
draws = dr.getNormalWichuraDraws(sampleSize=3, numberOfDraws=10) array([[ 0.52418458, -1.04344204, -2.11642482, 0.48257162, -2.67188279, -1.89993283, 0.28251041, -0.38424425, 1.53182226, 0.30651874], [-0.7937038 , -0.07884121, -0.91005616, -0.98855175, 1.09405753, -0.5997651 , -1.70785113, 1.57571384, -0.33208723, -1.03510102], [-0.13853654, 0.92595498, -0.80136586, 1.68454196, 0.9955927 , -0.28615154, 2.10635541, 0.0436191 , -0.25417774, 0.01026933]])
-
biogeme.draws.
getUniform
(sampleSize, numberOfDraws, symmetric=False)¶ Uniform [0, 1] or [-1, 1] numbers
- Parameters
sampleSize (int) – number of observations for which draws must be generated. If None, a one dimensional array will be generated. If it has a values k, then k series of draws will be generated
numberOfDraws (int) – number of draws to generate.
symmetric (bool) – if True, draws from [-1: 1] are generated. If False, draws from [0: 1] are generated. Default: False
- Returns
numpy array with the draws
- Return type
numpy.array
Example:
draws = dr.getUniform(sampleSize=3, numberOfDraws=10, symmetric=False) array([[0.13053817, 0.63892308, 0.55031567, 0.26347854, 0.16730932, 0.77745367, 0.48283887, 0.84247501, 0.20550219, 0.02373537], [0.68935846, 0.03363595, 0.36006669, 0.26709364, 0.54907706, 0.22492104, 0.2494399 , 0.17323209, 0.52370401, 0.54091257], [0.40310204, 0.89916711, 0.86065005, 0.94277699, 0.09077065, 0.40107731, 0.22554722, 0.47693135, 0.14058265, 0.17397031]]) draws = dr.getUniform(sampleSize=3, numberOfDraws=10, symmetric=True) array([[ 0.74403237, -0.27995692, 0.33997421, -0.89405035, -0.129761 , 0.86593325, 0.30657422, 0.82435619, 0.498482 , 0.24561616], [-0.48239607, -0.29257815, -0.98342034, 0.68392813, -0.25379429, 0.49359859, -0.26459883, 0.14569724, -0.68860467, -0.40903446], [ 0.93251627, -0.85166912, 0.58096917, 0.39289882, -0.65088635, 0.40114744, -0.61327161, 0.08900539, -0.20985417, 0.67542226]])
biogeme.exceptions module¶
Defines a generic exception for Biogeme
- author
Michel Bierlaire
- date
Tue Mar 26 16:47:11 2019
-
exception
biogeme.exceptions.
biogemeError
¶ Bases:
Exception
Defines a generic exception for Biogeme.
biogeme.expressions module¶
Defines the various arithmetic expressions accepted by Biogeme.
- author
Michel Bierlaire
- date
Tue Mar 26 16:47:49 2019
-
class
biogeme.expressions.
And
(left, right)¶ Bases:
biogeme.expressions.BinaryOperator
Logical and
-
__init__
(left, right)¶ Constructor
- Parameters
left (biogeme.expressions.Expression) – first arithmetic expression
right (biogeme.expressions.Expression) – second arithmetic expression
-
getValue
()¶ Evaluates the value of the expression
- Returns
value of the expression
- Return type
float
-
-
class
biogeme.expressions.
Beta
(name, value, lowerbound, upperbound, status)¶ Bases:
biogeme.expressions.Elementary
Unknown parameters to be estimated from data.
-
__init__
(name, value, lowerbound, upperbound, status)¶ Constructor
- Parameters
name (string) – name of the parameter.
value (float) – default value.
lowerbound (float) – if different from None, imposes a lower bound on the value of the parameter during the optimization.
upperbound (float) – if different from None, imposes an upper bound on the value of the parameter during the optimization.
status (int) – if different from 0, the parameter is fixed to its default value, and not modified by the optimization algorithm.
-
changeInitValues
(betas)¶ Modifies the initial values of the Beta parameters.
The fact that the parameters are fixed or free is irrelevant here.
- Parameters
betas (dict(string:float)) – dictionary where the keys are the names of the parameters, and the values are the new value for the parameters.
-
dictOfBetas
(free=True, fixed=False)¶ Extract the set of parameters from the expression. Overload the generic function.
- Parameters
free (bool) – if True, the free parameters are included. Default: True.
fixed (bool) – if True, the fixed parameters are included. Default: False.
- Returns
a dict with the beta parameters appearing in the expression, the keys being the names of the parameters.
- Return type
dict(string:biogeme.expressions.Expression)
-
getSignature
()¶ The signature of a string characterizing an expression.
This is designed to be communicated to C++, so that the expression can be reconstructed in this environment.
The list contains the following elements:
the name of the expression between < >
the id of the expression between { }
the name of the parameter,
the status between [ ]
the unique ID, preceeded by a comma
the beta ID, preceeded by a comma
Consider the following expression:
\[2 \beta_1 V_1 - \frac{\exp(-\beta_2 V_2) }{ \beta_3 (\beta_2 \geq \beta_1)}.\]It is defined as:
2 * beta1 * Variable1 - expressions.exp(-beta2*Variable2) / (beta3 * (beta2 >= beta1))
And its signature is:
[b'<Numeric>{4780527008},2', b'<Beta>{4780277152}"beta1"[0],0,0', b'<Times>{4780526952}(2),4780527008,4780277152', b'<Variable>{4511837152}"Variable1",5,2', b'<Times>{4780527064}(2),4780526952,4511837152', b'<Beta>{4780277656}"beta2"[0],1,1', b'<UnaryMinus>{4780527120}(1),4780277656', b'<Variable>{4511837712}"Variable2",6,3', b'<Times>{4780527176}(2),4780527120,4511837712', b'<exp>{4780527232}(1),4780527176', b'<Beta>{4780277264}"beta3"[1],2,0', b'<Beta>{4780277656}"beta2"[0],1,1', b'<Beta>{4780277152}"beta1"[0],0,0', b'<GreaterOrEqual>{4780527288}(2),4780277656,4780277152', b'<Times>{4780527344}(2),4780277264,4780527288', b'<Divide>{4780527400}(2),4780527232,4780527344', b'<Minus>{4780527456}(2),4780527064,4780527400']
- Returns
list of the signatures of an expression and its children.
- Return type
list(string)
- Raises
biogeme.exceptions.biogemeError – if no id has been defined for elementary expression
biogeme.exceptions.biogemeError – if no id has been defined for parameter
-
getValue
()¶ Evaluates the value of the expression
- Returns
value of the expression
- Return type
float
-
setOfBetas
(free=True, fixed=False)¶ Extract the set of parameters from the expression. Overload the generic function.
- Parameters
free (bool) – if True, the free parameters are included. Default: True.
fixed (bool) – if True, the fixed parameters are included. Default: False.
- Returns
returns a set with the beta parameters appearing in the expression.
- Return type
-
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)
-
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)
-
changeInitValues
(betas)¶ Modifies the initial values of the Beta parameters.
The fact that the parameters are fixed or free is irrelevant here.
- Parameters
betas (dict(string:float)) – dictionary where the keys are the names of the parameters, and the values are the new value for the parameters.
-
countPanelTrajectoryExpressions
()¶ Count the number of times the PanelLikelihoodTrajectory is used in the formula. It should trigger an error if it is used more than once.
-
dictOfBetas
(free=True, fixed=False)¶ Extract the set of parameters from the expression.
- Parameters
free (bool) – if True, the free parameters are included. Default: True.
fixed (bool) – if True, the fixed parameters are included. Default: False.
- Returns
a dict with the beta parameters appearing in the expression, the keys being the names of the parameters.
- Return type
dict(string:biogeme.expressions.Expression)
-
dictOfDraws
()¶ Recursively extract the random variables (draws for Monte-Carlo) appearing in the expression, and store them in a dictionary.
- Returns
dict where the keys are the random variables and the elements the type of draws
- Return type
dict(string:string)
-
dictOfRandomVariables
()¶ - Recursively extract the random variables appearing in the
expression, and store them in a dictionary.
- Returns
returns a dict with the random variables appearing in the expression the keys being their names.
- Return type
dict(string:biogeme.expressions.Expression)
-
dictOfVariables
()¶ Recursively extract the variables appearing in the expression, and store them in a dictionary.
- Returns
returns a dict with the variables appearing in the expression the keys being their names.
- Return type
dict(string:biogeme.expressions.Expression)
-
embedExpression
(t)¶ Check if the expression contains an expression of type t. Typically, this would be used to check that a MonteCarlo expression contains a bioDraws expression.
- Return:
bool.
See: Expression.isContainedIn
-
getClassName
()¶ Obtain the name of the top class of the expression structure
- Returns
the name of the class
- Return type
string
-
getElementaryExpression
(name)¶ Return: an elementary expression from its name if it appears in the expression.
- Parameters
name (string) – name of the elementary expression.
- Returns
the expression if it exists. None otherwise.
- Return type
-
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)
-
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=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 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) – 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)
-
-
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.
-
-
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=None)¶ 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, drawType)¶ Bases:
biogeme.expressions.Elementary
Draws for Monte-Carlo integration
-
__init__
(name, drawType)¶ Constructor
- Parameters
name (string) – name of the random variable with a series of draws.
drawType (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
-
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.
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
-
-
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 (object) – 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
\[ \begin{align}\begin{aligned}\frac{1}{\sigma} \phi\left( \frac{y-m}{\sigma} \right)\\Where :math:`\phi(\cdot)` is the pdf of the normal distribution.\end{aligned}\end{align} \]- 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.
-
allMessages
(screenLevel=None)¶ Report all the messages up to a given level.
- 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
If None (default), all messages are reported.
- Returns
all messages.
- Return type
str.
-
createLog
(fileLevel=None, 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
If None (default), all messages are reported.
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.
-
resetMessages
()¶
-
resume
()¶ Resume the regular operations of the logger after the use of temporarySilence
-
setDebug
()¶ Set both screen and file levels to 4
-
setDetailed
()¶ Set both screen and file levels to 3
-
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
-
temporarySilence
()¶ Temporarily turns off the message, remembering the current screen level.
-
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.
boxcox
(x, ell)¶ 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.
checkValidityNestedLogit
(V, nests)¶ - Verifies if the nested logit model is indeed based on a partition
of the choice set.
- Parameters
V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
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 tuple ok, message, where the message explains the problem is the nested structure is not OK.
- Return type
tuple(bool, str)
-
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. If an alternative is missing in the dictionaray, the corresponding alpha is set to zero.
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. If an alternative is missing in the dictionary, the corresponding alpha is set to zero.
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, mu)¶ - 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. If an alternative is missing in the dictionary, the corresponding alpha is set to zero.
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.
mu (biogeme.expressions.Expression) – Homogeneity parameter \(\mu\).
- Returns
choice probability for the cross-nested logit model.
- Return type
-
biogeme.models.
getMevForCrossNested
(V, availability, nests)¶ - Implements the MEV generating function for 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. If an alternative is missing in the dictionary, the corresponding alpha is set to zero.
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.
getMevForCrossNestedMu
(V, availability, nests, mu)¶ - Implements the MEV generating function for 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. If an alternative is missing in the dictionary, the corresponding alpha is set to zero.
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.
mu (biogeme.expressions.Expression) – Homogeneity parameter \(\mu\).
- Returns
log of the 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.
getMevForNestedMu
(V, availability, nests, mu)¶ Implements the MEV generating function for the nested logit model, including the scale parameter
- param V
dict of objects representing the utility functions of each alternative, indexed by numerical ids.
- type V
dict(int:biogeme.expressions.Expression)
- param 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.
- type availability
dict(int:biogeme.expressions.Expression)
- param nests
- 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
- type nests
tuple
- param mu
scale parameter
- type mu
biogeme.expressions.Expression
- return
a dictionary mapping each alternative id with the 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.
- rtype
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. If an alternative is missing in the dictionaray, the corresponding alpha is set to zero.
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. If an alternative is missing in the dictionary, the corresponding alpha is set to zero.
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, mu)¶ - 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. If an alternative is missing in the dictionary, the corresponding alpha is set to zero.
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.
mu (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.
loglogit
(V, av, i)¶ The logarithm of 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_endogenousSampling
(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_endogenousSampling
(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, 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)¶ Obsolete function. Present for compatibility only
-
biogeme.models.
piecewiseFormula
(variable, thresholds, initialBetas=None)¶ Generate the formula for a piecewise linear specification.
If there are K thresholds, K-1 variables are generated. The first and last thresholds can be defined as None, corresponding to \(-\infty\) and \(+\infty\), respectively. 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}\]New variables and new parameters are automatically created.
- Parameters
variable – variable for which we need the piecewise linear transform.
thresholds (list(float)) – list of thresholds
initialBetas (list(float)) – list of values to initialize the beta parameters. The number of entries should be the number of thresholds, plus one. If None, the value of zero is used. Default: none.
- Returns
expression of the piecewise linear specification.
- Return type
-
biogeme.models.
piecewiseFunction
(x, thresholds, betas)¶ Plot a piecewise linear specification.
If there are K thresholds, K-1 variables are generated. The first and last thresholds can be defined as None, corresponding to \(-\infty\) and \(+\infty\), respectively. 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
x (float) – value at which the piecewise specification must be avaluated
thresholds (list(float)) – list of thresholds
betas (list(float)) – list of the beta parameters. The number of entries should be the number of thresholds, plus one.
- Returns
value of the numpy function
- Return type
float
-
biogeme.models.
piecewiseVariables
(variable, thresholds)¶ Generate the variables to include in a piecewise linear specification.
If there are K thresholds, K-1 variables are generated. The first and last thresholds can be defined as None, corresponding to \(-\infty\) and \(+\infty\),respectively. 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 or str) – variable for which we need the piecewise linear transform. The expression itself or the name of the variable can be given.
thresholds (list(float)) – list of thresholds
- Returns
list of variables to for the piecewise linear specification.
- Return type
See also
piecewiseFormula
biogeme.optimization module¶
Interface for the optimization algorithms.
- author
Michel Bierlaire
- date
Sun Apr 5 16:48:54 2020
-
biogeme.optimization.
bfgs
(H, d, y)¶ - Update the BFGS matrix. Formula (13.12) of Bierlaire (2015)
where the method proposed by Powell (1977) is applied
- Parameters
H (numpy.array (2D)) – current approximation of the inverse of the Hessian
d (numpy.array (1D)) – difference between two consecutive iterates.
y (numpy.array (1D)) – difference between two consecutive gradients.
- Returns
updated approximation of the inverse of the Hessian.
- Return type
numpy.array (2D)
-
biogeme.optimization.
bfgsLineSearch
(fct, x0, initBfgs=None, eps=6.06273418136464e-06, maxiter=1000)¶ BFGS method with inexact line search (Wolfe conditions)
- Parameters
fct (optimization.functionToMinimize) – object to calculate the objective function and its derivatives.
x0 (numpy.array) – starting point
initBfgs (numpy.array) – matrix used to initialize BFGS. If None, the identity matrix is used. Default: None.
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. Default: 1000
- Returns
tuple x, messages, where
x is the solution found,
- messages is a dictionary reporting various aspects related to the run of the
algorithm.
- Return type
numpy.array, dict(str:object)
- Raises
biogeme.exceptions.biogemeError – if the dimensions of the matrix initBfgs do not match the length of x0.
-
biogeme.optimization.
bfgsLineSearchForBiogeme
(fct, initBetas, bounds, parameters=None)¶ Optimization interface for Biogeme, based on BFGS quasi-Newton method with LS.
- Parameters
fct (optimization.functionToMinimize) – object to calculate the objective function and its derivatives.
initBetas (numpy.array) – initial value of the parameters.
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 relative gradient is below that threshold, the algorithm has
reached convergence (default: \(\varepsilon^{\frac{1}{3}}\));
maxiter: the maximum number of iterations (default: 100).
- initBfgs: the positive definite matrix that initalizes the BFGS updates. If None,
the identity matrix is used. Default: None.
- Returns
tuple x, messages, where
x is the solution found,
messages is a dictionary reporting various aspects related to the run of the algorithm.
- Return type
numpy.array, dict(str:object)
- Raises
biogeme.exceptions.biogemeError – if bounds are imposed on the variables.
-
biogeme.optimization.
bfgsTrustRegion
(fct, x0, initBfgs=None, delta0=1.0, eps=6.06273418136464e-06, dl=False, maxiter=1000, eta1=0.01, eta2=0.9)¶ BFGS method with trust region
- Parameters
fct (optimization.functionToMinimize) – object to calculate the objective function and its derivatives.
x0 (numpy.array) – starting point
initBfgs (numpy.array) – matrix used to initialize BFGS. If None, the identity matrix is used. Default: None.
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, messages, where
x is the solution found,
messages is a dictionary reporting various aspects related to the run of the algorithm.
- Return type
numpy.array, dict(str:object)
- Raises
biogeme.exceptions.biogemeError – if the dimensions of the matrix initBfgs do not match the length of x0.
-
biogeme.optimization.
bfgsTrustRegionForBiogeme
(fct, initBetas, bounds, parameters=None)¶ Optimization interface for Biogeme, based on Newton method with TR.
- Parameters
fct (optimization.functionToMinimize) – object to calculate the objective function and its derivatives.
initBetas (numpy.array) – initial value of the parameters.
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 relative gradient is below that threshold, the algorithm has
reached convergence (default: \(\varepsilon^{\frac{1}{3}}\));
maxiter: the maximum number of iterations (default: 100).
- dogleg: if True, the trust region subproblem is solved using
the Dogleg method. If False, it is solved using the truncated conjugate gradient method (default: False).
radius: the initial radius of the truat region (default: 1.0).
- initBfgs: the positive definite matrix that initalizes the BFGS updates. If None,
the identity matrix is used. Default: None.
- Returns
tuple x, messages, where
x is the solution found,
- messages is a dictionary reporting various aspects
related to the run of the algorithm.
- Return type
numpy.array, dict(str:object)
- Raises
biogeme.exceptions.biogemeError – if bounds are imposed on the variables.
-
biogeme.optimization.
bioBfgs
(fct, initBetas, bounds, parameters=None)¶ - Optimization interface for Biogeme, based on BFGS quasi-Newton method with simple
bounds.
- Parameters
fct (optimization.functionToMinimize) – object to calculate the objective function and its derivatives.
initBetas (numpy.array) – initial value of the parameters.
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 relative gradient is below that threshold,
the algorithm has reached convergence (default: \(\varepsilon^{\frac{1}{3}}\));
cgtolerance: when the norm of the residual is below that threshold, the conjugate gradient algorithm has reached convergence (default: \(\varepsilon^{\frac{1}{3}}\));
infeasibleConjugateGradient: if True, the conjugate gradient algorithm may generate until termination. The result will then be projected on the feasible domain. If False, the algorithm stops as soon as an infeasible iterate is generated (default: False).
maxiter: the maximum number of iterations (default: 1000).
radius: the initial radius of the truat region (default: 1.0).
eta1: threshold for failed iterations (default: 0.01).
eta2: threshold for very successful iteration (default 0.9).
- enlargingFactor: factor used to enlarge the trust region
during very successful iterations (default 10).
hamabs: if True, a starting point is calculated using sotchastic Newton (default: False).
- Returns
x, messages
x is the solution generated by the algorithm,
messages is a dictionary describing information about the lagorithm
- Return type
numpay.array, dict(str:object)
-
class
biogeme.optimization.
bioBounds
(b)¶ Bases:
object
This class is designed for the management of simple bound constraints
-
__init__
(b)¶ - Parameters
b (list(tuple)) – list of tuples (ell,u) containing the lower and upper bounds for each free parameter.
- Raises
biogeme.exceptions.biogemeError – if the bounds are incompatible
-
activity
(x, epsilon=2.220446049250313e-16)¶ Determines the activity status of each variable.
- Parameters
x (numpy.array) – point for which the activity must be determined.
epsilon (float) – a bound is considered active if the distance to it is less rhan epsilon.
- Returns
- a vector, same length as x, where each entry reports the activity of the
corresponding variable:
0 if no bound is active
-1 if the lower bound is active
1 if the upper bound is active
- Raises
biogeme.exceptions.biogemeError – if the vector x is not feasible
biogeme.exceptions.biogemeError – if the dimensions of x and bounds do not match.
-
breakpoints
(x, d)¶ Projects the direction d, starting from x, on the intersection of the bound constraints
- Parameters
x (numpy.array) – current point
d (numpy.array) – search direction
- Returns
list of tuple (index, value), where index is the index of the variable, and value the value of the corresponding breakpoint.
- Return type
list(tuple(int,float))
- Raises
biogeme.exceptions.biogemeError – if the dimensions are inconsistent
biogeme.exceptions.biogemeError – if x is infeasible
-
feasible
(x)¶ Check if point verifies the bound constraints
- Parameters
x (numpy.array) – point to project
- Returns
True if x is feasible, False otherwise.
- Return type
bool
- Raises
biogeme.exceptions.biogemeError – if the dimensions are inconsistent
-
generalizedCauchyPoint
(xk, gk, H, direction)¶ Implementation of Step 2 of the Specific Algorithm by Conn et al. (1988).
The quadratic model is defined as
\[m(x) = f(x_k) + (x - x_k)^T g_k + \frac{1}{2} (x-x_k)^T H (x-x_k).\]- Parameters
xk (numpy.array. Dimension n.) – current point
gk (numpy.array. Dimension n.) – vector g involved in the quadratic model definition.
H (numpy.array. Dimension n x n.) – matrix H involved in the quadratic model definition.
- Returns
generalized Cauchy point based on inexact line search.
- Return type
numpy.array. Dimension n.
- Raises
biogeme.exceptions.biogemeError – if the dimensions are inconsistent
biogeme.exceptions.biogemeError – if xk is infeasible
-
intersect
(otherBounds)¶ Create a bounds object representing the intersection of two regions.
- Parameters
otherBounds (class bioBounds) – other bound object that must be intersected.
- Returns
bound object, intersection of the two.
- Return type
class bioBounds
- Raises
biogeme.exceptions.biogemeError – if the dimensions are inconsistent
-
intersectionWithTrustRegion
(x, delta)¶ - Create a bioBounds object representing the intersection between the feasible domain
and the trust region.
- Parameters
x (numpy.array) – center of the trust region
delta (float) – radius of the tust region (infinity norm)
- Raises
biogeme.exceptions.biogemeError – if the dimensions are inconsistent
-
maximumStep
(x, d)¶ Calculates the maximum step thatcan be performed along a direction while staying feasible.
- Parameters
x (numpy.array) – reference point
d (numpy.array) – direction
- Returns
the largest alpha such that x + alpha * d is feasible and the list of indices achieving this value.
- Return type
float, int
- Raises
biogeme.exceptions.biogemeError – if the point is infeasible
-
project
(x)¶ Project a point onto the feasible domain defined by the bounds.
- Parameters
x (numpy.array) – point to project
- Returns
projected point
- Return type
numpy.array
- Raises
biogeme.exceptions.biogemeError – if the dimensions are inconsistent
-
subspace
(selectedVariables)¶ Generate a bioBounds object for selected variables
- Parameters
selectedVariables (numpy.array(bool)) – boolean vector. If an entry is True, the corresponding variables is considered.
x – center of the trust region
delta (float) – radius of the trust region (in infinity norm)
- Type
numpy.array
- Returns
bound object
- Return type
class bioBounds
- Raises
biogeme.exceptions.biogemeError – if the dimensions are inconsistent
-
-
biogeme.optimization.
bioNewton
(fct, initBetas, bounds, parameters=None)¶ - Optimization interface for Biogeme, based on Newton’s method with simple
bounds.
- Parameters
fct (optimization.functionToMinimize) – object to calculate the objective function and its derivatives.
initBetas (numpy.array) – initial value of the parameters.
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 relative gradient is below that threshold,
the algorithm has reached convergence (default: \(\varepsilon^{\frac{1}{3}}\));
cgtolerance: when the norm of the residual is below that threshold, the conjugate gradient algorithm has reached convergence (default: \(\varepsilon^{\frac{1}{3}}\));
infeasibleConjugateGradient: if True, the conjugate gradient algorithm may generate until termination. The result will then be projected on the feasible domain. If False, the algorithm stops as soon as an infeasible iterate is generated (default: False).
maxiter: the maximum number of iterations (default: 1000).
radius: the initial radius of the truat region (default: 1.0).
eta1: threshold for failed iterations (default: 0.01).
eta2: threshold for very successful iteration (default 0.9).
- enlargingFactor: factor used to enlarge the trust region
during very successful iterations (default 10).
hamabs: if True, a starting point is calculated using sotchastic Newton (default: False).
- Returns
x, messages
x is the solution generated by the algorithm,
messages is a dictionary describing information about the lagorithm
- Return type
numpay.array, dict(str:object)
-
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 equation:
\[H_s d_n = - \nabla f(x)\]- where \(H_s\) is a positive definite matrix generated with the method by
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
- Raises
biogeme.exceptions.biogemeError – if the quadratic model is not convex.
-
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 direction
-1 if negative curvature along Cauchy 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
-
class
biogeme.optimization.
functionToMinimize
¶ Bases:
object
This is an abstract class. The actual function to minimize must be implemented in a concrete class deriving from this one.
-
abstract
f
(batch=None)¶ Calculate the value of the function
- Parameters
batch (float) – for data driven functions (such as a log likelikood function), it is possible to approximate the value of the function using a sample of the data called a batch. This argument is a value between 0 and 1 representing the percentage of the data that should be used for thre random batch. If None, the full data set is used. Default: None pass
- Returns
value of the function
- Return type
float
-
abstract
f_g
(batch=None)¶ Calculate the value of the function and the gradient
- Parameters
batch (float) – for data driven functions (such as a log likelikood function), it is possible to approximate the value of the function using a sample of the data called a batch. This argument is a value between 0 and 1 representing the percentage of the data that should be used for the random batch. If None, the full data set is used. Default: None pass
- Returns
value of the function and the gradient
- Return type
tuple float, numpy.array
-
abstract
f_g_bhhh
(batch=None)¶ Calculate the value of the function, the gradient and the BHHH matrix
- Parameters
batch (float) – for data driven functions (such as a log likelikood function), it is possible to approximate the value of the function using a sample of the data called a batch. This argument is a value between 0 and 1 representing the percentage of the data that should be used for the random batch. If None, the full data set is used. Default: None pass
- Returns
value of the function, the gradient and the BHHH
- Return type
tuple float, numpy.array, numpy.array
-
abstract
f_g_h
(batch=None)¶ Calculate the value of the function, the gradient and the Hessian
- Parameters
batch (float) – for data driven functions (such as a log likelikood function), it is possible to approximate the value of the function using a sample of the data called a batch. This argument is a value between 0 and 1 representing the percentage of the data that should be used for the random batch. If None, the full data set is used. Default: None pass
- Returns
value of the function, the gradient and the Hessian
- Return type
tuple float, numpy.array, numpy.array
-
abstract
setVariables
(x)¶ Set the values of the variables for which the function has to b calculated.
- Parameters
x (numpy.array) – values
-
abstract
-
biogeme.optimization.
inverseBfgs
(Hinv, d, y)¶ Update the inverse BFGS matrix. Formula (13.13) of Bierlaire (2015)
- Parameters
Hinv (numpy.array (2D)) – current approximation of the inverse of the Hessian
d (numpy.array (1D)) – difference between two consecutive iterates.
y (numpy.array (1D)) – difference between two consecutive gradients.
- Returns
updated approximation of the inverse of the Hessian.
- Return type
numpy.array (2D)
-
biogeme.optimization.
lineSearch
(fct, x, f, g, 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
fct (optimization.functionToMinimize) – object to calculate the objective function and its derivatives.
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.exceptions.biogemeError – if lbd \(\leq\) 1
biogeme.exceptions.biogemeError – if alpha0 \(\leq\) 0
biogeme.exceptions.biogemeError – if beta1 \(\geq\) beta2
biogeme.exceptions.biogemeError – if d is not a descent direction
-
biogeme.optimization.
newtonLineSearch
(fct, x0, eps=6.06273418136464e-06, maxiter=100)¶ Newton method with inexact line search (Wolfe conditions)
- Parameters
fct (optimization.functionToMinimize) – object to calculate the objective function and its derivatives.
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, messages
x is the solution generated by the algorithm,
messages is a dictionary describing information about the lagorithm
- Return type
numpay.array, dict(str:object)
-
biogeme.optimization.
newtonLineSearchForBiogeme
(fct, initBetas, bounds, parameters=None)¶ Optimization interface for Biogeme, based on Newton method.
- Parameters
fct (optimization.functionToMinimize) – object to calculate the objective function and its derivatives.
initBetas (numpy.array) – initial value of the parameters.
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 relative gradient is below that threshold, the algorithm has
reached convergence (default: \(\varepsilon^{\frac{1}{3}}\));
maxiter: the maximum number of iterations (default: 100).
- Returns
tuple x, nit, nfev, message, where
x is the solution found,
- messages is a dictionary reporting various aspects related to the run of the
algorithm.
- Return type
numpy.array, dict(str:object)
- Raises
biogeme.exceptions.biogemeError – if bounds are imposed on the variables.
-
biogeme.optimization.
newtonTrustRegion
(fct, x0, delta0=1.0, eps=6.06273418136464e-06, dl=False, maxiter=1000, eta1=0.01, eta2=0.9)¶ Newton method with trust region
- Parameters
fct (optimization.functionToMinimize) – object to calculate the objective function and its derivatives.
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, messages, where
x is the solution found,
messages is a dictionary reporting various aspects related to the run of the algorithm.
- Return type
numpy.array, dict(str:object)
-
biogeme.optimization.
newtonTrustRegionForBiogeme
(fct, initBetas, bounds, parameters=None)¶ Optimization interface for Biogeme, based on Newton method with TR.
- Parameters
fct (optimization.functionToMinimize) – object to calculate the objective function and its derivatives.
initBetas (numpy.array) – initial value of the parameters.
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 relative gradient is below that threshold, the algorithm has reached convergence (default: \(\varepsilon^{\frac{1}{3}}\));
maxiter: the maximum number of iterations (default: 100).
- dogleg: if True, the trust region subproblem is solved using
the Dogleg method. If False, it is solved using the truncated conjugate gradient method (default: False).
radius: the initial radius of the truat region (default: 1.0).
- Returns
tuple x, messages, where
x is the solution found,
messages is a dictionary reporting various aspects related to the run of the algorithm.
- Return type
numpy.array, dict(str:object)
- Raises
biogeme.exceptions.biogemeError – if bounds are imposed on the variables.
-
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
- Raises
biogeme.exceptions.biogemeError – if the matrix A is not square.
biogeme.exceptions.biogemeError – if the matrix A is not symmetric.
-
biogeme.optimization.
scipy
(fct, initBetas, bounds, parameters=None)¶ Optimization interface for Biogeme, based on the scipy minimize function.
- Parameters
fct (optimization.functionToMinimize) – object to calculate the objective function and its derivatives.
initBetas (numpy.array) – initial value of the beta parameters
bounds (list(tuple)) – list of tuples (ell,u) containing the lower and upper bounds for each free parameter
parameters – dict of parameters to be transmitted to the optimization routine. See the scipy documentation.
- Returns
x, messages
x is the solution generated by the algorithm,
messages is a dictionary describing several information about the lagorithm
- Return type
numpay.array, dict(str:object)
-
biogeme.optimization.
simpleBoundsNewtonAlgorithm
(fct, bounds, x0, proportionTrueHessian=1.0, infeasibleConjugateGradient=False, delta0=1.0, tol=6.06273418136464e-06, cgtol=6.06273418136464e-06, maxiter=1000, eta1=0.01, eta2=0.9, enlargingFactor=10, hamabs=False)¶ Trust region algorithm for problems with simple bounds
- Parameters
fct (optimization.functionToMinimize) – object to calculate the objective function and its derivatives.
bounds (class bounds) – bounds on the variables
x0 (numpy.array) – starting point
proportionTrueHessian (float) – proportion of the iterations where the true hessian is calculated. When not, the BFGS update is used. If 1.0, it is used for all iterations. If 0.0, it is not used at all.
infeasibleConjugateGradient (bool) – if True, the conjugate gradient algorithm may generate until termination. The result will then be projected on the feasible domain. If False, the algorithm stops as soon as an infeasible iterate is generated. Default: False.
delta0 (float) – initial radius of the trust region. Default: 100.
tol (float) – the algorithm stops when this precision is reached. Default: \(\varepsilon^{\frac{1}{3}}\)
cgtol (float) – the conjugate gradient algorithm stops when this precision is reached. Default: \(\varepsilon^{\frac{1}{3}}\)
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.
enlargingFactor (float) – if an iteration is very successful, the radius of the trust region is multiplied by this factor. Default 10.
hamabs – if True, a stochastic Newton algorithm is applied to find a starting point for the estimation process. This is particularly designed for estimation with large data sets. It is experimental, and inspired by the algorithm proposed by `Lederrey et al. (2019)`_.
- Returns
x, messages
x is the solution generated by the algorithm,
messages is a dictionary describing information about the lagorithm
- Return type
numpay.array, dict(str:object)
- Raises
biogeme.exceptions.biogemeError – if the dimensions of the matrix initBfgs do not match the length of x0.
-
biogeme.optimization.
simpleBoundsNewtonAlgorithmForBiogeme
(fct, initBetas, bounds, parameters=None)¶ - Optimization interface for Biogeme, based on variants of Newton method with simple
bounds.
- Parameters
fct (optimization.functionToMinimize) – object to calculate the objective function and its derivatives.
initBetas (numpy.array) – initial value of the parameters.
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 relative gradient is below that threshold,
the algorithm has reached convergence (default: \(\varepsilon^{\frac{1}{3}}\));
cgtolerance: when the norm of the residual is below that threshold, the conjugate gradient algorithm has reached convergence (default: \(\varepsilon^{\frac{1}{3}}\));
proportionAnalyticalHessian: proportion of iterations when the analytical Hessian is calculated (default: 0).
infeasibleConjugateGradient: if True, the conjugate gradient algorithm may generate until termination. The result will then be projected on the feasible domain. If False, the algorithm stops as soon as an infeasible iterate is generated (default: False).
maxiter: the maximum number of iterations (default: 1000).
radius: the initial radius of the truat region (default: 1.0).
eta1: threshold for failed iterations (default: 0.01).
eta2: threshold for very successful iteration (default 0.9).
- enlargingFactor: factor used to enlarge the trust region
during very successful iterations (default 10).
hamabs: if True, a starting point is calculated using sotchastic Newton (default: False).
- Returns
x, messages
x is the solution generated by the algorithm,
messages is a dictionary describing information about the lagorithm
- Return type
numpay.array, dict(str:object)
-
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.
4 if a numerical problem has been encountered
- Return type
numpy.array, int
-
biogeme.optimization.
truncatedConjugateGradientSubspace
(xk, gk, Hk, delta, bounds, infeasibleIterate=False, tol=6.06273418136464e-06)¶ - Find an approximation of the solution of the trust region subproblem using the truncated
conjugate gradient method within the subspace of free variables. Free variables are those corresponding to inactive constraints at the generalized Cauchy point.
- Parameters
g (numpy.array) – gradient of the quadratic model.
H (numpy.array) – hessian of the quadrartic model.
delta (float) – radius of the trust region.
bounds (class bioBounds) – bounds on the variables.
infeasibleIterate (bool) – if True, the algorithm may generate until termination. The result will then be projected on the feasible domain. If False, the algorithm stops as soon as an infeasible iterate is generated. Default: False.
- 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.
4 if a numerical problem has been encountered
- Return type
numpy.array, int
- Raises
biogeme.exceptions.biogemeError – if the dimensions are inconsistent
-
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
… todo:: rawResults should be a dict and not a class.
-
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
(theRawResults=None, pickleFile=None)¶ Bases:
object
Class managing the estimation results
-
__init__
(theRawResults=None, pickleFile=None)¶ Constructor
- Parameters
theRawResults (biogeme.results.rawResults) – object with the results of the estimation. Default: None.
pickleFile (string) – name of the file containing the raw results in pickle format. Default: None.
- Raises
biogeme.exceptions.biogemeError – if no data is provided.
-
getBetaValues
(myBetas=None)¶ Retrieve the values of the estimated parameters, by names.
- Parameters
myBetas (list(string)) – names of the requested parameters. If None, all available parameters will be reported. Default: None.
- Returns
dict containing the values, where the keys are the names.
- Return type
dict(string:float)
- Raises
biogeme.exceptions.biogemeError – if some requested parameters are not available.
-
getBetasForSensitivityAnalysis
(myBetas, size=100, useBootstrap=False)¶ Generate draws from the distribution of the estimates, for sensitivity analysis.
- Parameters
myBetas (list(string)) – names of the parameters for which draws are requested.
size (int) – number of draws. Default: 100.
useBootstrap (bool) – if True, the variance-covariance matrix generated by the bootstrapping is used for simulation. If False, the robust variance-covariance matrix is used. Default: False.
- Raises
biogeme.exceptions.biogemeError – if useBootstrap is True and the bootstrap matrix is not available.
- Returns
numpy table with as many rows as draws, and as many columns as parameters.
- Return type
numpy.array
-
getBootstrapVarCovar
()¶ Obtain the bootstrap variance covariance matrix as a Pandas data frame.
- Returns
bootstrap variance covariance matrix, or None if not available
- Return type
pandas.DataFrame
-
getCorrelationResults
()¶ Get the statistics about pairs of coefficients as a Pandas dataframe
- Returns
Pandas data frame with the correlation results
- Rtpye
pandas.DataFrame
-
getEstimatedParameters
()¶ Gather the estimated parameters and the corresponding statistics in a Pandas dataframe.
- return
Pandas dataframe with the results
- rtype
pandas.DataFrame
-
getGeneralStatistics
()¶ Format the results in a dict
- Returns
dict with the results. The keys describe each content. Each element is a tuple, with the value and its preferred formatting.
Example:
'Init log likelihood': (-115.30029248549191, '.7g')
- Return type
dict(string:float,string)
-
getHtml
()¶ Get the results coded in HTML
- Returns
HTML code
- Rtpye
string
-
getLaTeX
()¶ Get the results coded in LaTeX
- Returns
LaTeX code
- Return type
string
-
getRobustVarCovar
()¶ Obtain the robust variance covariance matrix as a Pandas data frame.
- Returns
robust variance covariance matrix
- Return type
pandas.DataFrame
-
getVarCovar
()¶ Obtain the Rao-Cramer variance covariance matrix as a Pandas data frame.
- Returns
Rao-Cramer variance covariance matrix
- Return type
pandas.DataFrame
-
writeHtml
()¶ Write the results in an HTML file.
-
writeLaTeX
()¶ Write the results in a LaTeX file.
-
writePickle
()¶ Dump the data in a file in pickle format.
- Returns
name of the file.
- Return type
string
-
-
biogeme.results.
calcPValue
(t)¶ Calculates the p value of a parameter from its t-statistic.
The formula is
\[2(1-\Phi(|t|)\]where \(\Phi(\cdot)\) is the CDF of a normal distribution.
- Parameters
t – t-statistics
- Type
float
- Returns
p-value
- Return type
float
-
class
biogeme.results.
rawResults
(theModel, betaValues, fgHb, bootstrap=None)¶ Bases:
object
Class containing the raw results from the estimation
-
__init__
(theModel, betaValues, fgHb, bootstrap=None)¶ Constructor
- Parameters
theModel (biogeme.BIOGEME) – object with the model
betaValues (list(float)) – list containing the estimated values of the parameters
fgHb (float,numpy.array, numpy.array, numpy.array) –
tuple f,g,H,bhhh containing
f: the value of the function,
g: the gradient,
H: the second derivative matrix,
bhhh: the BHHH matrix.
bootstrap (numpy.array) –
output of the bootstrapping. numpy array, of size B x K, where
B is the number of bootstrap iterations
K is the number of parameters to estimate
Default: None.
-
biogeme.tools module¶
Implements some useful functions
- author
Michel Bierlaire
- date
Sun Apr 14 10:46:10 2019
-
biogeme.tools.
calculatePrimeNumbers
(upperBound)¶ Calculate prime numbers
- Parameters
upperBound (int) – prime numbers up to this value will be computed
- Returns
array with prime numbers
- Return type
list(int)
-
biogeme.tools.
checkDerivatives
(theFunction, x, names=None, logg=False)¶ - Verifies the analytical derivatives of a function by comparing them with finite
difference approximations.
- Parameters
theFunction (function) –
- A function object that takes a vector as an argument, and
returns a tuple.
The first element of the tuple is the value of the function \(f\),
the second is the gradient of the function,
the third is the hessian.
x (numpy.array) – arguments of the function
names (list(string)) – the names of the entries of x (for reporting).
logg (bool) – if True, messages will be displayed.
- Returns
tuple f, g, h, gdiff, hdiff where
f is the value of the function at x,
g is the analytical gradient,
h is the analytical hessian,
- gdiff is the difference between the analytical gradient and the finite
difference approximation
- hdiff is the difference between the analytical hessian and the finite
difference approximation
- Return type
float, numpy.array,numpy.array, numpy.array,numpy.array
-
biogeme.tools.
countNumberOfGroups
(df, column)¶ This function counts the number of groups of same value in a column. For instance: 1,2,2,3,3,3,4,1,1 would give 5
-
biogeme.tools.
findiff_H
(theFunction, x)¶ Calculates the hessian of a function \(f\) using finite differences
- Parameters
theFunction (function) – A function object that takes a vector as an argument, and returns a tuple. The first element of the tuple is the value of the function \(f\), and the second is the gradient of the function. The other elements are not used.
x (numpy.array) – argument of the function
- Returns
numpy matrix containing the hessian calculated by finite differences.
- Return type
numpy.array
-
biogeme.tools.
findiff_g
(theFunction, x)¶ Calculates the gradient of a function :math`f` using finite differences
- Parameters
theFunction (function) – A function object that takes a vector as an argument, and returns a tuple. The first element of the tuple is the value of the function \(f\). The other elements are not used.
x (numpy.array) – argument of the function
- Returns
numpy vector, same dimension as x, containing the gradient calculated by finite differences.
- Return type
numpy.array
-
biogeme.tools.
getPrimeNumbers
(n)¶ Get a given number of prime numbers
- Parameters
n (int) – number of primes that are requested
- Returns
array with prime numbers
- Return type
list(int)
biogeme.version module¶
Information about the version of Biogeme
- author
Michel Bierlaire
- date
Tue Mar 26 16:45:15 2019
-
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