biogeme.models.cnl module

Implements the cross-nested logit model.

author:

Michel Bierlaire

date:

Wed Oct 25 11:08:59 2023

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

Implements the cross-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 (NestsForCrossNestedLogit | tuple[tuple[Expression | float | int | bool, dict[int, Expression]], ...]) – 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:

choice probability for the cross-nested logit model.

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

Warning

This function is deprecated. Use cnl() instead.

Same as cnl. Maintained for backward compatibility

Return type:

Expression

Parameters:
biogeme.models.cnl.cnlmu(util, availability, nests, choice, mu)[source]

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

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 (NestsForCrossNestedLogit) – 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) – Homogeneity parameter \(\mu\).

Return type:

Expression

Returns:

choice probability for the cross-nested logit model.

biogeme.models.cnl.getMevForCrossNested(util, availability, nests)[source]

Warning

This function is deprecated. Use get_mev_for_cross_nested() instead.

Return type:

Expression

Parameters:
biogeme.models.cnl.getMevForCrossNestedMu(util, availability, nests, mu)[source]

Warning

This function is deprecated. Use get_mev_for_cross_nested_mu() instead.

Return type:

dict[int, Expression]

Parameters:
biogeme.models.cnl.get_mev_for_cross_nested(util, availability, nests)[source]

Implements the MEV generating function for the cross 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 (NestsForCrossNestedLogit | tuple[tuple[Expression | float | int | bool, dict[int, Expression]], ...]) – object describing the nesting structure

Return type:

dict[int, Expression]

Returns:

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

biogeme.models.cnl.get_mev_for_cross_nested_mu(util, 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:

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

  • mu (Expression | float | int | bool) – Homogeneity parameter \(\mu\).

Return type:

dict[int, Expression]

Returns:

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

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

Implements the log of the cross-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 (NestsForCrossNestedLogit | tuple[tuple[Expression | float | int | bool, dict[int, Expression]], ...]) – 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 the choice probability for the cross-nested logit model.

Raises:

BiogemeError – if the definition of the nests is invalid.

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

Warning

This function is deprecated. Use cnl() instead.

Same as logcnl. Maintained for backward compatibility

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 (NestsForCrossNestedLogit | tuple[tuple[Expression | float | int | bool, dict[int, Expression]], ...]) – 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 cross-nested logit model.

biogeme.models.cnl.logcnlmu(util, 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:

  • 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 (NestsForCrossNestedLogit) – 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) – Homogeneity parameter \(\mu\).

Return type:

Expression

Returns:

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

Raises:

BiogemeError – if the definition of the nests is invalid.