Models¶
Functions for model specification.
biogeme.models module¶
Implements various models.
 author
Michel Bierlaire
 date
Fri Mar 29 17:13:14 2019

biogeme.models.
boxcox
(x, ell)[source]¶ BoxCox transform
\[B(x, \ell) = \frac{x^{\ell}1}{\ell}.\]It has the property that
\[\lim_{\ell \to 0} B(x,\ell)=\log(x).\]To avoid numerical difficulties, if \(\ell < 10^{5}\), the McLaurin approximation is used:
\[\log(x) + \ell \log(x)^2 + \frac{1}{6} \ell^2 \log(x)^3 + \frac{1}{24} \ell^3 \log(x)^4.\] Parameters
x (biogeme.expressions.Expression) – a variable to transform.
ell (biogeme.expressions.Expression) – parameter of the transformation.
 Returns
the BoxCox transform
 Return type

biogeme.models.
checkValidityCNL
(V, nests)[source]¶ Verifies if the crossnested logit specifciation is valid
 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 dictionary mapping the alternative ids with the crossnested 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
 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.
checkValidityNestedLogit
(V, nests)[source]¶ 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)[source]¶ Implements the crossnested 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 crossnested 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 crossnested logit model.
 Return type

biogeme.models.
cnl_avail
(V, availability, nests, choice)[source]¶ 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 crossnested 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 crossnested logit model.
 Return type

biogeme.models.
cnlmu
(V, availability, nests, choice, mu)[source]¶ Implements the crossnested 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 crossnested 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 crossnested logit model.
 Return type

biogeme.models.
getMevForCrossNested
(V, availability, nests)[source]¶ 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 crossnested 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
 Returns
log of the choice probability for the crossnested logit model.
 Return type

biogeme.models.
getMevForCrossNestedMu
(V, availability, nests, mu)[source]¶ Implements the MEV generating function for the crossnested 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 crossnested 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
mu (biogeme.expressions.Expression) – Homogeneity parameter \(\mu\).
 Returns
log of the choice probability for the crossnested logit model.
 Return type

biogeme.models.
getMevForNested
(V, availability, nests)[source]¶ Implements the derivatives of 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_m1)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)[source]¶ Implements the MEV generating function for the nested logit model, including the scale parameter
 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
mu (biogeme.expressions.Expression) – scale parameter
 Returns
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_m1)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
dict(int:biogeme.expressions.Expression)

biogeme.models.
getMevGeneratingForNested
(V, availability, nests)[source]¶ 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
\[G(e^{V_1}, \ldots,e^{V_J}) = \sum_m \left( \sum_{\ell \in C_m} y_\ell^{\mu_m}\right)^{\frac{\mu}{\mu_m}}\]where \(G\) is the MEV generating function.
 Return type

biogeme.models.
logcnl
(V, availability, nests, choice)[source]¶ Implements the log of the crossnested 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 crossnested 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 crossnested logit model.
 Return type
 Raises
biogemeError – if the definition of the nests is invalid.

biogeme.models.
logcnl_avail
(V, availability, nests, choice)[source]¶ 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 crossnested 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 crossnested logit model.
 Return type

biogeme.models.
logcnlmu
(V, availability, nests, choice, mu)[source]¶ Implements the log of the crossnested 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 crossnested 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 crossnested logit model.
 Return type
 Raises
biogemeError – if the definition of the nests is invalid.

biogeme.models.
logit
(V, av, i)[source]¶ The logit model
The model is defined as
\[\frac{a_i e^{V_i}}{\sum_{i=1}^J a_j e^{V_j}}\] Parameters
V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
av (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.
i (int) – id of the alternative for which the probability must be calculated.
 Returns
choice probability of alternative number i.
 Return type

biogeme.models.
loglogit
(V, av, i)[source]¶ The logarithm of the logit model
The model is defined as
\[\frac{a_i e^{V_i}}{\sum_{i=1}^J a_j e^{V_j}}\] Parameters
V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
av (dict(int:biogeme.expressions.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with V, or None. In this case, all alternatives are supposed to be always available.
i (int) – id of the alternative for which the probability must be calculated.
 Returns
choice probability of alternative number i.
 Return type

biogeme.models.
logmev
(V, logGi, av, choice)[source]¶ 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 (dict(int:biogeme.expressions.Expression)) –
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\).
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
 Return type
\[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)[source]¶ 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(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
logGi (dict(int:biogeme.expressions.Expression)) –
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\).
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\).
 Return type

biogeme.models.
lognested
(V, availability, nests, choice)[source]¶ 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
 Return type
 Raises
biogemeError – if the definition of the nests is invalid.

biogeme.models.
lognestedMevMu
(V, availability, nests, choice, mu)[source]¶ 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 toplevel 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_m1)V_i} \left(\sum_{i=1}^{J_m} e^{\mu_m V_i}\right)^{\frac{\mu}{\mu_m}1}\]where \(m\) is the (only) nest containing alternative \(i\), and \(G\) is the MEV generating function.
 Return type

biogeme.models.
mev
(V, logGi, av, choice)[source]¶ 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 (dict(int:biogeme.expressions.Expression)) –
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\).
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})}}\] Return type

biogeme.models.
mev_endogenousSampling
(V, logGi, av, correction, choice)[source]¶ Choice probability for a MEV model, including the correction for endogenous sampling as proposed by Bierlaire, Bolduc and McFadden (2008).
 Parameters
V (dict(int:biogeme.expressions.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
logGi (dict(int:biogeme.expressions.Expression)) –
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\).
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\).
 Return type

biogeme.models.
nested
(V, availability, nests, choice)[source]¶ 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
 Return type
 Raises
biogemeError – if the definition of the nests is invalid.

biogeme.models.
nestedMevMu
(V, availability, nests, choice, mu)[source]¶ 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 toplevel 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_m1)V_i} \left(\sum_{i=1}^{J_m} e^{\mu_m V_i}\right)^{\frac{\mu}{\mu_m}1}\]Where \(m\) is the (only) nest containing alternative \(i\), and \(G\) is the MEV generating function.
 Return type

biogeme.models.
piecewise
(variable, thresholds)[source]¶ Obsolete function. Present for compatibility only

biogeme.models.
piecewiseFormula
(variable, thresholds, initialBetas=None)[source]¶ Generate the formula for a piecewise linear specification.
If there are K thresholds, K1 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 \\ ta & \text{if } a \leq t < a+b \\ b & \text{otherwise} \end{array}\right. \;\;\;x_{Ti} = \max(0, \min(ta, b))\end{split}\]New variables and new parameters are automatically created.
 Parameters
variable (string) – name of the 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
 Raises
biogemeError – if the thresholds are not defined properly, which means that only the first and the last threshold can be set to None.
biogemeError – if the length of list
initialBetas
is not equal to the length ofthresholds
minus one.
See also

biogeme.models.
piecewiseFunction
(x, thresholds, betas)[source]¶ Plot a piecewise linear specification.
If there are K thresholds, K1 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 \\ ta & \text{if } a \leq t < a+b \\ b & \text{otherwise} \end{array}\right. \;\;\;x_{Ti} = \max(0, \min(ta, 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
 Raises
biogemeError – if the thresholds are not defined properly, which means that only the first and the last threshold can be set to None.

biogeme.models.
piecewiseVariables
(variable, thresholds)[source]¶ Generate the variables to include in a piecewise linear specification.
If there are K thresholds, K1 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 \\ ta & \text{if } a \leq t < a+b \\ b & \text{otherwise} \end{array}\right. \;\;\;x_{Ti} = \max(0, \min(ta, 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
 Raises
biogemeError – if the thresholds are not defined properly, as only the first and the last thresholds can be set to None.
See also