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

biogeme.results.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.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
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

  1. number of individuals

  2. number of draws

  3. 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
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:

  1. the name of the expression between < >

  2. the id of the expression between { }

  3. the name of the parameter,

  4. the status between [ ]

  5. the unique ID, preceeded by a comma

  6. 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
getValue()

Evaluates the value of the expression

Returns

value of the expression

Return type

float

setOfBetas(free=True, fixed=False)

Extract the set of parameters from the expression. Overload the generic function.

Parameters

  • free (bool) – if True, the free parameters are included. Default: True.

  • fixed (bool) – if True, the fixed parameters are included. Default: False.

Returns

returns a set with the beta parameters appearing in the expression.

Return type

set(biogeme.expressions.Expression)

setSpecificIndices(indicesOfFreeBetas, indicesOfFixedBetas, indicesOfRandomVariables, indicesOfDraws)

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

Parameters

  • indicesOfFreeBetas (dict(string:int)) – dictionary mapping the name of the free betas with their index

  • indicesOfFixedBetas (dict(string:int)) – dictionary mapping the name of the fixed betas with their index

  • indicesOfRandomVariables (dict(string:int)) – dictionary mapping the name of the random variables with their index

  • indicesOfDraws (dict(string:int)) – dictionary mapping the name of the draws with their index

class biogeme.expressions.BinaryOperator(left, right)

Bases: biogeme.expressions.Expression

Base class for arithmetic expressions that are binary operators. This expression is the result of the combination of two expressions, typically addition, substraction, multiplication or division.

__init__(left, right)

Constructor

Parameters
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:

  1. the signatures of the child expression,

  2. the name of the expression between < >

  3. the id of the expression between { }

  4. 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
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:

  1. the signature of the expression defining the key

  2. the signatures of all the children expressions,

  3. the name of the expression between < >

  4. the id of the expression between { }

  5. the number of elements between ( )

  6. the id of the expression defining the key

  7. 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
getValue()

Evaluates the value of the expression

Returns

value of the expression

Return type

float

class biogeme.expressions.Expression

Bases: object

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

__add__(other)

Operator overloading. Generate an expression for addition.

Parameters

other (biogeme.expressions.Expression) – expression to be added

Returns

self + other

Return type

biogeme.expressions.Expression

__and__(other)

Operator overloading. Generate an expression for logical and.

Parameters

other (biogeme.expressions.Expression) – expression for logical and

Returns

self and other

Return type

biogeme.expressions.Expression

__div__(other)

Operator overloading. Generate an expression for division.

Parameters

other (biogeme.expressions.Expression) – expression for division

Returns

self / other

Return type

biogeme.expressions.Expression

__eq__(other)

Operator overloading. Generate an expression for comparison.

Parameters

other (biogeme.expressions.Expression) – expression for equality

Returns

self == other

Return type

biogeme.expressions.Expression

__ge__(other)

Operator overloading. Generate an expression for comparison.

Parameters

other (biogeme.expressions.Expression) – expression for greater or equal

Returns

self >= other

Return type

biogeme.expressions.Expression

__gt__(other)

Operator overloading. Generate an expression for comparison.

Parameters

other (biogeme.expressions.Expression) – expression for greater than

Returns

self > other

Return type

biogeme.expressions.Expression

__init__()

Constructor

__le__(other)

Operator overloading. Generate an expression for comparison.

Parameters

other (biogeme.expressions.Expression) – expression for less or equal

Returns

self <= other

Return type

biogeme.expressions.Expression

__lt__(other)

Operator overloading. Generate an expression for comparison.

Parameters

other (biogeme.expressions.Expression) – expression for less than

Returns

self < other

Return type

biogeme.expressions.Expression

__mul__(other)

Operator overloading. Generate an expression for multiplication.

Parameters

other (biogeme.expressions.Expression) – expression to be multiplied

Returns

self * other

Return type

biogeme.expressions.Expression

__ne__(other)

Operator overloading. Generate an expression for comparison.

Parameters

other (biogeme.expressions.Expression) – expression for difference

Returns

self != other

Return type

biogeme.expressions.Expression

__neg__()

Operator overloading. Generate an expression for unary minus.

Returns

-self

Return type

biogeme.expressions.Expression

__or__(other)

Operator overloading. Generate an expression for logical or.

Parameters

other (biogeme.expressions.Expression) – expression for logical or

Returns

self or other

Return type

biogeme.expressions.Expression

__pow__(other)

Operator overloading. Generate an expression for power.

Parameters

other (biogeme.expressions.Expression) – expression for power

Returns

self ^ other

Return type

biogeme.expressions.Expression

__radd__(other)

Operator overloading. Generate an expression for addition.

Parameters

other (biogeme.expressions.Expression) – expression to be added

Returns

other + self

Return type

biogeme.expressions.Expression

__rdiv__(other)

Operator overloading. Generate an expression for division.

Parameters

other (biogeme.expressions.Expression) – expression for division

Returns

other / self

Return type

biogeme.expressions.Expression

__rmul__(other)

Operator overloading. Generate an expression for multiplication.

Parameters

other (biogeme.expressions.Expression) – expression to be multiplied

Returns

other * self

Return type

biogeme.expressions.Expression

__rpow__(other)

Operator overloading. Generate an expression for power.

Parameters

other (biogeme.expressions.Expression) – expression for power

Returns

other ^ self

Return type

biogeme.expressions.Expression

__rsub__(other)

Operator overloading. Generate an expression for substraction.

Parameters

other (biogeme.expressions.Expression) – expression to be substracted

Returns

other - self

Return type

biogeme.expressions.Expression

__rtruediv__(other)

Operator overloading. Generate an expression for division.

Parameters

other (biogeme.expressions.Expression) – expression for division

Returns

other / self

Return type

biogeme.expressions.Expression

__sub__(other)

Operator overloading. Generate an expression for substraction.

Parameters

other (biogeme.expressions.Expression) – expression to substract

Returns

self - other

Return type

biogeme.expressions.Expression

__truediv__(other)

Operator overloading. Generate an expression for division.

Parameters

other (biogeme.expressions.Expression) – expression for division

Returns

self / other

Return type

biogeme.expressions.Expression

audit(database=None)

Performs various checks on the expressions.

Parameters

database (biogeme.database.Database) – database object

Returns

tuple listOfErrors, listOfWarnings

Return type

list(string), list(string)

changeInitValues(betas)

Modifies the initial values of the Beta parameters.

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

Parameters

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

countPanelTrajectoryExpressions()

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

dictOfBetas(free=True, fixed=False)

Extract the set of parameters from the expression.

Parameters

  • free (bool) – if True, the free parameters are included. Default: True.

  • fixed (bool) – if True, the fixed parameters are included. Default: False.

Returns

a dict with the beta parameters appearing in the expression, the keys being the names of the parameters.

Return type

dict(string:biogeme.expressions.Expression)

dictOfDraws()

Recursively extract the random variables (draws for Monte-Carlo) appearing in the expression, and store them in a dictionary.

Returns

dict where the keys are the random variables and the elements the type of draws

Return type

dict(string:string)

dictOfRandomVariables()
Recursively extract the random variables appearing in the

expression, and store them in a dictionary.

Returns

returns a dict with the random variables appearing in the expression the keys being their names.

Return type

dict(string:biogeme.expressions.Expression)

dictOfVariables()

Recursively extract the variables appearing in the expression, and store them in a dictionary.

Returns

returns a dict with the variables appearing in the expression the keys being their names.

Return type

dict(string:biogeme.expressions.Expression)

embedExpression(t)

Check if the expression contains an expression of type t. Typically, this would be used to check that a MonteCarlo expression contains a bioDraws expression.

Return:

bool.

See: Expression.isContainedIn

getClassName()

Obtain the name of the top class of the expression structure

Returns

the name of the class

Return type

string

getElementaryExpression(name)

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

Parameters

name (string) – name of the elementary expression.

Returns

the expression if it exists. None otherwise.

Return type

biogeme.expressions.Expression

getSignature()

The signature of a string characterizing an expression.

This is designed to be communicated to C++, so that the expression can be reconstructed in this environment.

The list contains the following elements:

  1. the signatures of all the children expressions,

  2. the name of the expression between < >

  3. the id of the expression between { }

  4. the number of children between ( )

  5. the ids of each children, preceeded by a comma.

Consider the following expression:

\[2 \beta_1 V_1 - \frac{\exp(-\beta_2 V_2) }{ \beta_3 (\beta_2 \geq \beta_1)}.\]

It is defined as:

2 * beta1 * Variable1 - expressions.exp(-beta2*Variable2) / (beta3 * (beta2 >= beta1))

And its signature is:

[b'<Numeric>{4780527008},2',
 b'<Beta>{4780277152}"beta1"[0],0,0',
 b'<Times>{4780526952}(2),4780527008,4780277152',
 b'<Variable>{4511837152}"Variable1",5,2',
 b'<Times>{4780527064}(2),4780526952,4511837152',
 b'<Beta>{4780277656}"beta2"[0],1,1',
 b'<UnaryMinus>{4780527120}(1),4780277656',
 b'<Variable>{4511837712}"Variable2",6,3',
 b'<Times>{4780527176}(2),4780527120,4511837712',
 b'<exp>{4780527232}(1),4780527176',
 b'<Beta>{4780277264}"beta3"[1],2,0',
 b'<Beta>{4780277656}"beta2"[0],1,1',
 b'<Beta>{4780277152}"beta1"[0],0,0',
 b'<GreaterOrEqual>{4780527288}(2),4780277656,4780277152',
 b'<Times>{4780527344}(2),4780277264,4780527288',
 b'<Divide>{4780527400}(2),4780527232,4780527344',
 b'<Minus>{4780527456}(2),4780527064,4780527400']
Returns

list of the signatures of an expression and its children.

Return type

list(string)

getValue_c(database, numberOfDraws=1000)

Evaluation of the expression

In Biogeme the complexity of some expressions requires a specific implementation, in C++. This function invokes the C++ code to evaluate the value of the expression for a series of entries in a database. Note that this function will generate draws if needed.

Parameters

  • database (biogeme.database.Database) – database

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

Returns

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

Return type

numpy.array

isContainedIn(t)

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

Return:

bool.

See: Expression.embedExpression

setOfBetas(free=True, fixed=False)

Extract the set of parameters from the expression.

Parameters

  • free (bool) – if True, the free parameters are included. Default: True.

  • fixed (bool) – if True, the fixed parameters are included. Default: False.

Returns

returns a set with the beta parameters appearing in the expression.

Return type

set(biogeme.expressions.Expression)

setOfVariables()

Extract the set of variables used in the expression.

Returns

returns a set with the variables appearing in the expression.

Return type

set(biogeme.expressions.Expression)

setRow(row)
This function identifies the row of the database from which

the values of the variables must be obtained.

Parameters

row (int) – id of the row.

setSpecificIndices(indicesOfFreeBetas, indicesOfFixedBetas, indicesOfRandomVariables, indicesOfDraws)

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

Parameters

  • indicesOfFreeBetas (dict(string:int)) – dictionary mapping the name of the free betas with their index

  • indicesOfFixedBetas (dict(string:int)) – dictionary mapping the name of the fixed betas with their index

  • indicesOfRandomVariables (dict(string:int)) – dictionary mapping the name of the random variables with their index

  • indicesOfDraws (dict(string:int)) – dictionary mapping the name of the draws with their index

setUniqueId(idsOfElementaryExpressions)

Provides a unique id to the elementary expressions.

Parameters

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

setVariableIndices(indicesOfVariables)

Provide an index to all variables

Parameters

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

class biogeme.expressions.Greater(left, right)

Bases: biogeme.expressions.BinaryOperator

Logical greater

__init__(left, right)

Constructor

Parameters
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
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
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:

  1. the signatures of the child expression,

  2. the name of the expression between < >

  3. the id of the expression between { }, preceeded by a comma

  4. the id of the children, preceeded by a comma

  5. 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
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
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:

  1. the signatures of all the children expressions,

  2. the name of the expression between < >

  3. the id of the expression between { }

  4. the number of alternatives between ( )

  5. the id of the expression for the chosen alternative, preceeded by a comma.

  6. for each alternative, separated by commas:

    1. the number of the alternative, as defined by the user,

    2. the id of the expression for the utility,

    3. 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
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
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:

  1. the name of the expression between < >

  2. the id of the expression between { }

  3. 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
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
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
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:

  1. the name of the expression between < >

  2. the id of the expression between { }

  3. the name of the random variable,

  4. the unique ID, preceeded by a comma,

  5. 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
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
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:

  1. the name of the expression between < >

  2. the id of the expression between { }

  3. the name of the variable,

  4. the unique ID, preceeded by a comma.

  5. 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
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:

  1. the name of the expression between < >

  2. the id of the expression between { }, preceeded by a comma

  3. the name of the draws

  4. the unique ID (preceeded by a comma),

  5. 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
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:

  1. the signatures of all the children expressions,

  2. the name of the expression between < >

  3. the id of the expression between { }

  4. the number of terms in the utility ( )

  5. for each term:

    1. the id of the beta parameter

    2. the unique id of the beta parameter

    3. the name of the parameter

    4. the id of the variable

    5. the unique id of the variable

    6. the name of the variable

Consider the following expression:

\[2 \beta_1 V_1 - \frac{\exp(-\beta_2 V_2) }{ \beta_3 (\beta_2 \geq \beta_1)}.\]

It is defined as:

2 * beta1 * Variable1 - expressions.exp(-beta2*Variable2) / (beta3 * (beta2 >= beta1))

And its signature is:

[b'<Numeric>{4780527008},2',
 b'<Beta>{4780277152}"beta1"[0],0,0',
 b'<Times>{4780526952}(2),4780527008,4780277152',
 b'<Variable>{4511837152}"Variable1",5,2',
 b'<Times>{4780527064}(2),4780526952,4511837152',
 b'<Beta>{4780277656}"beta2"[0],1,1',
 b'<UnaryMinus>{4780527120}(1),4780277656',
 b'<Variable>{4511837712}"Variable2",6,3',
 b'<Times>{4780527176}(2),4780527120,4511837712',
 b'<exp>{4780527232}(1),4780527176',
 b'<Beta>{4780277264}"beta3"[1],2,0',
 b'<Beta>{4780277656}"beta2"[0],1,1',
 b'<Beta>{4780277152}"beta1"[0],0,0',
 b'<GreaterOrEqual>{4780527288}(2),4780277656,4780277152',
 b'<Times>{4780527344}(2),4780277264,4780527288',
 b'<Divide>{4780527400}(2),4780527232,4780527344',
 b'<Minus>{4780527456}(2),4780527064,4780527400']
Returns

list of the signatures of an expression and its children.

Return type

list(string)

setOfBetas(free=True, fixed=False)

Extract the set of parameters from the expression.

Parameters

  • free (bool) – if True, the free parameters are included. Default: True.

  • fixed (bool) – if True, the fixed parameters are included. Default: False.

Returns

returns a set with the beta parameters appearing in the expression.

Return type

set(biogeme.expressions.Expression)

class biogeme.expressions.bioMax(left, right)

Bases: biogeme.expressions.BinaryOperator

Maximum of two expressions

__init__(left, right)

Constructor

Parameters
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
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:

  1. free betas,

  2. fixed betas,

  3. random variables for numrerical integration,

  4. random variables for Monte-Carlo integration,

  5. 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
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.expressions.Expression

biogeme.loglikelihood.loglikelihood(prob)

Simply computes the log of the probability

Parameters

prob (biogeme.expressions.Expression) – An expression providing the value of the probability.

Returns

the logarithm of the probability.

Return type

biogeme.expressions.Expression

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

Computes log likelihood function of a regression model.

Parameters
Returns

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

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

biogeme.expressions.Expression

biogeme.loglikelihood.mixedloglikelihood(prob)

Compute a simulated loglikelihood function

Parameters

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

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

the simulated loglikelihood, given by

\[\ln\left(\sum_{r=1}^R P(i|\xi^r_1,\ldots,\xi^r_L) \right)\]
where \(R\) is the number of draws, and \(\xi_j^r\)

is the rth draw of the random variable \(\xi_j\).

Return type

biogeme.expressions.Expression

biogeme.messaging module

Singleton managing the various levels of messages

author

Michel Bierlaire

date

Mon Jul 22 16:12:00 2019

class biogeme.messaging.Singleton

Bases: type

A singleton is a class with only one instance

class biogeme.messaging.bioMessage(screenLevel=0)

Bases: object

Manages the Biogeme messages

__init__(screenLevel=0)

Constructor

Parameters

screenLevel –

level of message that must be displayed on the screen:

  • 0: no output (default)

  • 1: warnings only

  • 2: only warnings and general information

  • 3: more verbose

  • 4: debug messages

addMessage(text, level)

Add a message

Parameters

  • text (string) – text of the message.

  • level –

    level of the message

    • 1: warning

    • 2: general information

    • 3: detailed information

    • 4: debug message

Note

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

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
Returns

the Box-Cox transform

Return type

biogeme.expressions.Expression

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.expressions.Expression

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

Same as cnl. Maintained for backward compatibility

Parameters

  • V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • availability (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.

  • nests (tuple) –

    a tuple containing as many items as nests.

    Each item is also a tuple containing two items

    • an object of type biogeme.expressions.Expression representing the nest parameter,

    • a dictionary mapping the alternative ids with the cross-nested parameters for the corresponding nest. 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.expressions.Expression

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.expressions.Expression

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.expressions.Expression

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.expressions.Expression

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

Implements the MEV generating function for the nested logit model

Parameters

  • V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • availability (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.

  • nests (tuple) –

    A tuple containing as many items as nests.

    Each item is also a tuple containing two items:

    • an object of type biogeme.expressions.Expression representing the nest parameter,

    • a list containing the list of identifiers of the alternatives belonging to the nest.

    Example:

    nesta = MUA ,[1, 2, 3]
nestb = MUB ,[4, 5, 6]
nests = nesta, nestb

Returns

a dictionary mapping each alternative id with the function

\[\ln \frac{\partial G}{\partial y_i}(e^{V_1}, \ldots,e^{V_J}) = e^{(\mu_m-1)V_i} \left(\sum_{i=1}^{J_m} e^{\mu_m V_i}\right)^ {\frac{1}{\mu_m}-1}\]
where \(m\) is the (only) nest containing alternative \(i\),

and \(G\) is the MEV generating function.

Return type

dict(int:biogeme.expressions.Expression)

biogeme.models.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.expressions.Expression

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

Same as logcnl. Maintained for backward compatibility

Parameters

  • V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • availability (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.

  • nests (tuple) –

    a tuple containing as many items as nests.

    Each item is also a tuple containing two items:

    • an object of type biogeme.expressions. Expression representing the nest parameter,

    • a dictionary mapping the alternative ids with the cross-nested parameters for the corresponding nest. 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.expressions.Expression

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.expressions.Expression

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

The logit model

The model is defined as

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

  • V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

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

  • i (int) – id of the alternative for which the probability must be calculated.

Returns

choice probability of alternative number i.

Return type

biogeme.expressions.Expression

biogeme.models.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.expressions.Expression

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

Log of the choice probability for a MEV model.

Parameters

  • V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • logGi – a dictionary mapping each alternative id with the function

\[\ln \frac{\partial G}{\partial y_i}(e^{V_1},\ldots,e^{V_J})\]
where \(G\) is the MEV generating function. If an alternative

\(i\) is not available, then \(G_i = 0\).

Parameters

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

  • choice (biogeme.expressions.Expression) – id of the alternative for which the probability must be calculated.

Returns

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

\[V_i + \ln G_i(e^{V_1},\ldots,e^{V_J}) - \ln\left(\sum_j e^{V_j + \ln G_j(e^{V_1}, \ldots,e^{V_J})}\right)\]
biogeme.models.logmev_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.expressions.Expression

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

Choice probability for a MEV model.

Parameters

  • V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • logGi – a dictionary mapping each alternative id with the function

\[\ln \frac{\partial G}{\partial y_i}(e^{V_1}, \ldots, e^{V_J})\]
where \(G\) is the MEV generating function. If an alternative

\(i\) is not available, then \(G_i = 0\).

Parameters

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

  • choice (biogeme.expressions.Expression) – id of the alternative for which the probability must be calculated.

Returns

Choice probability of the MEV model, given by

\[\frac{e^{V_i + \ln G_i(e^{V_1}, \ldots,e^{V_J})}}{\sum_j e^{V_j + \ln G_j(e^{V_1},\ldots,e^{V_J})}}\]
biogeme.models.mev_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.expressions.Expression

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.expressions.Expression

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

list(biogeme.expressions.Expression)

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

Schnabel and Eskow (1999).

The Dogleg point is

\[d_d = \eta d_n\]

where

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

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

Parameters

  • g (numpy.array) – gradient \(\nabla f(x)\)

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

Returns

tuple with Cauchy point, Newton point, Dogleg point

Return type

numpy.array, numpy.array, numpy.array

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

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.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
Returns

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

Return type

numpy.array, numpy.array, numpy.array

Raises
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