biogeme.models.nested module

Implements various models.

author:

Michel Bierlaire

date:

Fri Mar 29 17:13:14 2019

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

Warning

This function is deprecated. Use get_mev_for_nested() instead.

Return type:

dict[int, Expression]

Parameters:
biogeme.models.nested.getMevForNestedMu(util, availability, nests, mu)[source]

Warning

This function is deprecated. Use get_mev_for_nested_mu() instead.

Return type:

dict[int, Expression]

Parameters:
biogeme.models.nested.getMevGeneratingForNested(util, availability, nests)[source]

Warning

This function is deprecated. Use get_mev_generating_for_nested() instead.

Return type:

Expression

Parameters:
biogeme.models.nested.get_mev_for_nested(util, availability, nests)[source]

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

Parameters:

  • util (dict[int, Expression | float | int | bool]) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • availability (dict[int, Expression | float | int | bool] | 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 | tuple[tuple[Expression | float | int | bool, list[int]], ...]) – object containing the description of the nests.

Return type:

dict[int, Expression]

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.nested.get_mev_for_nested_mu(util, availability, nests, mu)[source]

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

Parameters:

  • util (dict[int, Expression | float | int | bool]) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • availability (dict[int, Expression | float | int | bool] | 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 | tuple[tuple[Expression | float | int | bool, list[int]], ...]) – object describing the nesting structure

  • mu (Expression | float | int | bool) – scale parameter

Return type:

dict[int, Expression]

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.nested.get_mev_generating_for_nested(util, availability, nests)[source]

Implements the MEV generating function for the nested logit model

Parameters:

  • util (dict[int, Expression | float | int | bool]) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • availability (dict[int, Expression | float | int | bool] | 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 | tuple[tuple[Expression | float | int | bool, list[int]], ...]) – 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.nested.lognested(util, availability, nests, choice)[source]

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

Parameters:

  • util (dict[int, Expression | float | int | bool]) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • availability (dict[int, Expression | float | int | bool] | None) – 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 (NestsForNestedLogit | tuple[tuple[Expression | float | int | bool, list[int]], ...]) – object describing the nesting structure

  • choice (Expression | float | int | bool) – id of the alternative for which the probability must be calculated.

Return type:

Expression

Returns:

log of 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.nested.lognestedMevMu(util, availability, nests, choice, mu)[source]

Warning

This function is deprecated. Use lognested_mev_mu() instead.

Return type:

Expression

Parameters:
biogeme.models.nested.lognested_mev_mu(util, 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:

  • util (dict[int, Expression | float | int | bool]) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • availability (dict[int, Expression | float | int | bool] | None) – 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 (NestsForNestedLogit | tuple[tuple[Expression | float | int | bool, list[int]], ...]) – object describing the nesting structure

  • choice (Expression | float | int | bool) – id of the alternative for which the probability must be calculated.

  • mu (Expression | float | int | bool) – expression producing the value of the top-level scale parameter.

Return type:

Expression

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.

biogeme.models.nested.nested(util, availability, nests, choice)[source]

Implements the nested logit model as a MEV model.

Parameters:

  • util (dict[int, Expression | float | int | bool]) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • availability (dict[int, Expression | float | int | bool] | 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 | tuple[tuple[Expression | float | int | bool, list[int]], ...]) – object containing the description of the nests.

  • choice (Expression | float | int | bool) – 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.nested.nestedMevMu(util, availability, nests, choice, mu)[source]

Warning

This function is deprecated. Use nested_mev_mu() instead.

Return type:

Expression

Parameters:
biogeme.models.nested.nested_mev_mu(util, 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:

  • util (dict[int, Expression | float | int | bool]) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • availability (dict[int, Expression | float | int | bool] | None) – 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 (NestsForNestedLogit | tuple[tuple[Expression | float | int | bool, list[int]], ...]) – object describing the nesting structure

  • choice (Expression | float | int | bool) – id of the alternative for which the probability must be calculated.

  • mu (Expression | float | int | bool) – expression producing the value of the top-level scale parameter.

Return type:

Expression

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.