biogeme.models.models_orig module

Implements various models.

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

biogeme.models.models_orig.boxcox(x, ell)[source]

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).\]

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.expr.Expression) – a variable to transform.
ell (biogeme.expressions.expr.Expression) – parameter of the transformation.

Returns:

the Box-Cox transform

Return type:

biogeme.expressions.expr.Expression

biogeme.models.models_orig.cnl(V, availability, nests, choice, sampling_log_probability=None)[source]

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

Parameters:

V (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with util, 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. expr.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

sampling_log_probability (dict(int: biogeme.expressions.Expression)) – if not None, it means that the choice set is actually a subset that has been sampled from the full choice set. In that case, this is a dictionary mapping each alternative with the logarithm of its probability to be selected in the sample.
choice (biogeme.expressions.expr.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.expr.Expression

biogeme.models.models_orig.cnl_avail(V, availability, nests, choice, sampling_log_probability=None)[source]

Same as cnl. Maintained for backward compatibility

Parameters:

V (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with util, 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.expr.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.expr.Expression) – id of the alternative for which the probability must be calculated.
sampling_log_probability (dict(int: biogeme.expressions.Expression)) – if not None, it means that the choice set is actually a subset that has been sampled from the full choice set. In that case, this is a dictionary mapping each alternative with the logarithm of its probability to be selected in the sample.

Returns:

choice probability for the cross-nested logit model.

Return type:

biogeme.expressions.expr.Expression

biogeme.models.models_orig.cnlmu(V, availability, nests, choice, mu)[source]

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

Parameters:

V (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with util, 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. expr.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.expr.Expression) – id of the alternative for which the probability must be calculated.
mu (biogeme.expressions.expr.Expression) – Homogeneity parameter \(\mu\).

Returns:

choice probability for the cross-nested logit model.

Return type:

biogeme.expressions.expr.Expression

biogeme.models.models_orig.getMevForCrossNested(V, availability, nests, sampling_log_probability=None)[source]

Implements the MEV generating function for the cross nested logit model as a MEV model.

Parameters:

V (dict(int: biogeme.expressions.expr.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 util, 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. expr.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

sampling_log_probability (dict(int: biogeme.expressions.Expression)) – if not None, it means that the choice set is actually a subset that has been sampled from the full choice set. In that case, this is a dictionary mapping each alternative with the logarithm of its probability to be selected in the sample.

Returns:

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

Return type:

biogeme.expressions.expr.Expression

biogeme.models.models_orig.getMevForCrossNestedMu(V, availability, nests, mu)[source]

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.expr.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with util, 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. expr.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

mu (biogeme.expressions.expr.Expression) – Homogeneity parameter \(\mu\).

Returns:

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

Return type:

biogeme.expressions.expr.Expression

biogeme.models.models_orig.getMevForNested(V, availability, nests)[source]

Implements the derivatives of MEV generating function for the nested logit model

Parameters:

V (dict[slice(<class ‘int’>, <class ‘biogeme.expressions.base_expressions.Expression’>, None)]) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict[slice(<class ‘int’>, <class ‘biogeme.expressions.base_expressions.Expression’>, None)]) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with util, or None. In this case, all alternatives are supposed to be always available.
nests (NestsForNestedLogit) – object containing the description of the nests.

Return type:

dict[slice(<class ‘int’>, <class ‘biogeme.expressions.base_expressions.Expression’>, None)]

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.

biogeme.models.models_orig.getMevForNestedMu(V, availability, nests, mu)[source]

Implements the MEV generating function for the nested logit model, including the scale parameter

Parameters:

V (dict[slice(<class ‘int’>, <class ‘biogeme.expressions.base_expressions.Expression’>, None)]) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict[slice(<class ‘int’>, <class ‘biogeme.expressions.base_expressions.Expression’>, None)]) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with util, or None. In this case, all alternatives are supposed to be always available.
nests (NestsForNestedLogit) –
A tuple containing as many items as nests. Each item is also a tuple containing two items:
- an object of type biogeme.expressions. expr.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 (Expression) – scale parameter

Return type:

dict[slice(<class ‘int’>, <class ‘biogeme.expressions.base_expressions.Expression’>, None)]

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

biogeme.models.models_orig.getMevGeneratingForNested(V, availability, nests)[source]

Implements the MEV generating function for the nested logit model

Parameters:

V (dict[slice(<class ‘int’>, <class ‘biogeme.expressions.base_expressions.Expression’>, None)]) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict[slice(<class ‘int’>, <class ‘biogeme.expressions.base_expressions.Expression’>, None)]) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with util, or None. In this case, all alternatives are supposed to be always available.
nests (NestsForNestedLogit) – an object describing the nests

Return type:

Expression

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.

biogeme.models.models_orig.logcnl(V, availability, nests, choice, sampling_log_probability=None)[source]

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

Parameters:

V (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with util, 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. expr.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.expr.Expression) – id of the alternative for which the probability must be calculated.
sampling_log_probability (dict(int: biogeme.expressions.Expression)) – if not None, it means that the choice set is actually a subset that has been sampled from the full choice set. In that case, this is a dictionary mapping each alternative with the logarithm of its probability to be selected in the sample.

Returns:

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

Return type:

biogeme.expressions.expr.Expression

Raises:

BiogemeError – if the definition of the nests is invalid.

biogeme.models.models_orig.logcnl_avail(V, availability, nests, choice, sampling_log_probability=None)[source]

Same as logcnl. Maintained for backward compatibility

Parameters:

V (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with util, 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. expr.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.expr.Expression) – id of the alternative for which the probability must be calculated.
sampling_log_probability (dict(int: biogeme.expressions.Expression)) – if not None, it means that the choice set is actually a subset that has been sampled from the full choice set. In that case, this is a dictionary mapping each alternative with the logarithm of its probability to be selected in the sample.

Returns:

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

Return type:

biogeme.expressions.expr.Expression

biogeme.models.models_orig.logcnlmu(V, availability, nests, choice, mu)[source]

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.expr.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with util, 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. expr.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.expr.Expression) – id of the alternative for which the probability must be calculated.
mu (biogeme.expressions.expr.Expression) – Homogeneity parameter \(\mu\).

Returns:

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

Return type:

biogeme.expressions.expr.Expression

Raises:

BiogemeError – if the definition of the nests is invalid.

biogeme.models.models_orig.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.expr.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
av (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with util, 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.expr.Expression

biogeme.models.models_orig.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.expr.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
av (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with util, 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.expr.Expression

biogeme.models.models_orig.loglogit_sampling(V, av, correction, i)[source]

The logarithm of the logit model, with samples of alternatives

The model is defined as

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

Parameters:

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

Returns:

choice probability of alternative number i.

Return type:

biogeme.expressions.expr.Expression

biogeme.models.models_orig.logmev(V, logGi, av, choice)[source]

Log of the choice probability for a MEV model.

Parameters:

V (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
logGi (dict(int:biogeme.expressions.expr.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.expr.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with util, or None. In this case, all alternatives are supposed to be always available.
choice (biogeme.expressions.expr.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:

biogeme.expressions.expr.Expression

\[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.models_orig.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.expr.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
logGi (dict(int:biogeme.expressions.expr.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.expr.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with util, or None. In this case, all alternatives are supposed to be always available.
correction (dict(int:biogeme.expressions.expr.Expression)) – a dict of expressions for the correstion terms of each alternative.
choice (biogeme.expressions.expr.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.expressions.expr.Expression

biogeme.models.models_orig.lognested(V, availability, nests, choice)[source]

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

Parameters:

V (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with util, 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. expr.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.expr.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:

biogeme.expressions.expr.Expression

Raises:

BiogemeError – if the definition of the nests is invalid.

biogeme.models.models_orig.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.expr.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with util, 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.expr.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.expr.Expression) – id of the alternative for which the probability must be calculated.
mu (biogeme.expressions.expr.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.expr.Expression

biogeme.models.models_orig.mev(V, logGi, av, choice)[source]

Choice probability for a MEV model.

Parameters:

V (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
logGi (dict(int:biogeme.expressions.expr.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.expr.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with util, or None. In this case, all alternatives are supposed to be always available.
choice (biogeme.expressions.expr.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.expressions.expr.Expression

biogeme.models.models_orig.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.expr.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
logGi (dict(int:biogeme.expressions.expr.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.expr.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with util, or None. In this case, all alternatives are supposed to be always available.
correction (dict(int:biogeme.expressions.expr.Expression)) – a dict of expressions for the correstion terms of each alternative.
choice (biogeme.expressions.expr.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.expressions.expr.Expression

biogeme.models.models_orig.nested(V, availability, nests, choice)[source]

Implements the nested logit model as a MEV model.

Parameters:

V (dict[slice(<class ‘int’>, <class ‘biogeme.expressions.base_expressions.Expression’>, None)]) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict[slice(<class ‘int’>, <class ‘biogeme.expressions.base_expressions.Expression’>, None)]) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with util, or None. In this case, all alternatives are supposed to be always available.
nests (NestsForNestedLogit) – object containing the description of the nests.
choice (Expression) – id of the alternative for which the probability must be calculated.

Return type:

Expression

Returns:

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

Raises:

BiogemeError – if the definition of the nests is invalid.

biogeme.models.models_orig.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.expr.Expression)) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.
availability (dict(int:biogeme.expressions.expr.Expression)) – dict of objects representing the availability of each alternative (\(a_i\) in the above formula), indexed by numerical ids. Must be consistent with util, 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.expr.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.expr.Expression) – id of the alternative for which the probability must be calculated.
mu (biogeme.expressions.expr.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.expr.Expression

biogeme.models.models_orig.ordered_likelihood(continuous_value, list_of_discrete_values, tau_parameter, cdf)[source]

Ordered model that maps a continuous quantity with a list of: discrete intervals (often logit or probit)

Example: discrete values = [1, 2, 3, 4]

We define thresholds tau_1_2, tau_2_3 and tau_3_4. In order to impose that the threshold are sorted, we actually define

tau_1_2 = tau_parameter tau_2_3 = tau_1_2 + diff2 tau_3_4 = tau_2_3 + diff3

The probability that the discrete value is 2, say, is the probability that the continuous value lies between tau_1_2 and tau_2_3, where the probability distribution is logistic.

Parameters:

continuous_value (biogeme.expressions.Expression) – continuous quantity to mapping
list_of_discrete_values (list(int)) – discrete values
tau_parameter (biogeme.expressions.Beta) – parameter for the first threshold
cdf (fct(float) -> float) – function calculating the CDF of the random variable

Returns:

dict where the keys are the discrete values and the values are the corresponding probability.

Return type:

dict(int: biogeme.expressions.Expression)

biogeme.models.models_orig.ordered_logit(continuous_value, list_of_discrete_values, tau_parameter)[source]

Ordered logit model that maps a continuous quantity with a: list of discrete intervals

Example: discrete values = [1, 2, 3, 4]

We define thresholds tau_1_2, tau_2_3 and tau_3_4. In order to impose that the threshold are sorted, we actually define

tau_1_2 = tau_parameter tau_2_3 = tau_1_2 + diff2 tau_3_4 = tau_2_3 + diff3

The probability that the discrete value is 2, say, is the probability that the continuous value lies between tau_1_2 and tau_2_3, where the probability distribution is logistic.

Parameters:

continuous_value (biogeme.expressions.Expression) – continuous quantity to mapping
list_of_discrete_values (list(int)) – discrete values
tau_parameter (biogeme.expressions.Beta) – parameter for the first threshold

biogeme.models.models_orig.ordered_probit(continuous_value, list_of_discrete_values, tau_parameter)[source]

Ordered probit model that maps a continuous quantity with a: list of discrete intervals

Example: discrete values = [1, 2, 3, 4]

We define thresholds tau_1_2, tau_2_3 and tau_3_4. In order to impose that the threshold are sorted, we actually define

tau_1_2 = tau_parameter tau_2_3 = tau_1_2 + diff2 tau_3_4 = tau_2_3 + diff3

The probability that the discrete value is 2, say, is the probability that the continuous value lies between tau_1_2 and tau_2_3, where the probability distribution is normal.

Parameters:

continuous_value (biogeme.expressions.Expression) – continuous quantity to mapping
list_of_discrete_values (list(int)) – discrete values
tau_parameter (biogeme.expressions.Beta) – parameter for the first threshold

biogeme.models.models_orig.piecewiseFormula(variable, thresholds, betas=None)[source]

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 to obtain the specification

\[\sum_{i=1}^{K-1} \beta_i x_{Ti}\]

Parameters:

variable (string) – name of the variable for which we need the piecewise linear transform.
thresholds (list(float)) – list of thresholds
betas (list(biogeme.expresssions.Beta)) – list of Beta parameters to be used in the specification. The number of entries should be the number of thresholds, minus one. If None, for each interval, the parameter Beta(‘beta_VAR_interval’,0, None, None, 0) is used, where var is the name of the variable. Default: none.

Returns:

expression of the piecewise linear specification.

Return type:

biogeme.expressions.expr.Expression

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 initialexpr.Betas is not equal to the length of thresholds minus one.