MDCEV model

The module for the Multiple Discrete-Continuous Extreme Value model (MDCEV). The code is organized into sub-modules.

Submodules

biogeme.mdcev.mdcev module

Implementation of the contribution to the log likelihood of the MDCEV model.

See the technical report for a description of the various versions.

The functions involved in this module have a similar list of arguments. We document them here once for all:

• number_of_chosen_alternatives: number of alternative with non zero

  consumption. Note that it would be possible to calculate it from the consumption_quantities, but it would be too expensive in terms of calculation. Ideally should be stored as a variable in the database. Typically of type Variable.

• consumed_quantities: a dictionary associating the id of the

  alternatives with the observed number of times they are chosen. Typically, the values are of type Variable.

• baseline_utilities: a dictionary of baseline utility functions for

  each alternative. Typically, they are linear in the parameters. In the document, it is expressed as the inner product of beta and x.

• alpha_parameters: a dictionary of expressions for the alpha

  parameters appearing the specification of some the utility functions. See the technical report for details.

• gamma_parameters: a dictionary of expressions for the gamma

  parameters appearing the specification of the utility function. See the technical report for details.

• prices: a dictionary of expressions for the prices of each

  alternative.

• scale_parameter: expression for the scale parameter. Usually a

  numeric constant or a parameter. If None, the scale parameter is assumed to be fixed to 1, and is not included in the formulation.

author:

Michel Bierlaire

date:

Wed Aug 23 16:29:10 2023

class biogeme.mdcev.mdcev.SpecificModel(utilities, log_determinant_entries, inverse_of_determinant_entries)

Bases: NamedTuple

Parameters:

• utilities (dict[int, Expression]) –

• log_determinant_entries (dict[int, Expression]) –

• inverse_of_determinant_entries (dict[int, Expression]) –

inverse_of_determinant_entries: dict[int, Expression]

Alias for field number 2

log_determinant_entries: dict[int, Expression]

Alias for field number 1

utilities: dict[int, Expression]

Alias for field number 0

biogeme.mdcev.mdcev.info_gamma_parameters(gamma_parameters)

Provides logging information about the outside good

Parameters:

gamma_parameters (dict[int, Optional[Expression]]) – see the module documentation biogeme.mdcev

Return type:

None

biogeme.mdcev.mdcev.mdcev(number_of_chosen_alternatives, consumed_quantities, specific_model, scale_parameter=None)

Generate the Biogeme formula for the log probability of the MDCEV model

Parameters:

• number_of_chosen_alternatives (biogeme.expression.Expression) – see the module documentation biogeme.mdcev

• consumed_quantities (dict[int: biogeme.expression.Expression]) – see the module documentation biogeme.mdcev

• specific_model (dict[int: biogeme.expression.Expression]) –

  a tuple containing dictionaries of expressions calculating

  • the utility functions.

  • the log of the entries of the determinant,

  • the inverse of the sames entries,

• scale_parameter (biogeme.expressions.Expression) – see the module documentation biogeme.mdcev

A detailed explanation is provided in the technical report “Estimating the MDCEV model with Biogeme”

biogeme.mdcev.translated module

Implementation of the “translated” MDCEV model. See section 2.1 in the technical report.

author:

Michel Bierlaire

date:

Sun Nov 5 15:43:18 2023

biogeme.mdcev.translated.mdcev_translated(number_of_chosen_alternatives, consumed_quantities, baseline_utilities, alpha_parameters, gamma_parameters, scale_parameter=None)

Generate the Biogeme formula for the log probability of the MDCEV model using the translated utility function.

Parameters:

• number_of_chosen_alternatives (Expression) – see the module documentation biogeme.mdcev

• consumed_quantities (dict[int, Expression]) – see the module documentation biogeme.mdcev

• baseline_utilities (dict[int, Expression]) – see the module documentation biogeme.mdcev

• alpha_parameters (dict[int, Expression]) – see the module documentation biogeme.mdcev

• gamma_parameters (dict[int, Optional[Expression]]) – see the module documentation biogeme.mdcev

• scale_parameter (Optional[Expression]) – see the module documentation biogeme.mdcev

A detailed explanation is provided in the technical report “Estimating the MDCEV model with Biogeme”

biogeme.mdcev.translated.translated(baseline_utilities, consumed_quantities, alpha_parameters, gamma_parameters)

Calculates

Parameters:

• baseline_utilities (dict[int, Expression]) – see the module documentation biogeme.mdcev

• consumed_quantities (dict[int, Expression]) – see the module documentation biogeme.mdcev

• alpha_parameters (dict[int, Expression]) – see the module documentation biogeme.mdcev

• gamma_parameters (dict[int, Optional[Expression]]) – see the module documentation biogeme.mdcev

biogeme.mdcev.generalized module

Implementation of the “generalized” MDCEV model. See section 3 in the technical report.

author:

Michel Bierlaire

date:

Sun Nov 5 15:43:18 2023

biogeme.mdcev.generalized.generalized(baseline_utilities, consumed_quantities, alpha_parameters, gamma_parameters, prices=None)

Calculates the determinant entries for the Bhat 2008 specification Eq (18)

Parameters:

• baseline_utilities (dict[int, Expression]) – see the module documentation biogeme.mdcev

• consumed_quantities (dict[int, Expression]) – see the module documentation biogeme.mdcev

• alpha_parameters (dict[int, Expression]) – see the module documentation biogeme.mdcev

• gamma_parameters (dict[int, Optional[Expression]]) – see the module documentation biogeme.mdcev

• prices (Optional[dict[int, Expression]]) – see the module documentation biogeme.mdcev. If None, assumed to be 1.

biogeme.mdcev.generalized.mdcev_generalized(number_of_chosen_alternatives, consumed_quantities, baseline_utilities, alpha_parameters, gamma_parameters, prices=None, scale_parameter=None)

Generate the Biogeme formula for the log probability of the MDCEV model using the generalized translated utility function

Parameters:

• number_of_chosen_alternatives (Expression) – see the module documentation biogeme.mdcev

• consumed_quantities (dict[int, Expression]) – see the module documentation biogeme.mdcev

• baseline_utilities (dict[int, Expression]) – see the module documentation biogeme.mdcev

• alpha_parameters (dict[int, Expression]) – see the module documentation biogeme.mdcev

• gamma_parameters (dict[int, Optional[Expression]]) – see the module documentation biogeme.mdcev

• prices (Optional[dict[int, Expression]]) – see the module documentation biogeme.mdcev

• scale_parameter (Optional[Expression]) – see the module documentation biogeme.mdcev

A detailed explanation is provided in the technical report “Estimating the MDCEV model with Biogeme”

biogeme.mdcev.gamma_profile module

Implementation of the “gamma profile” MDCEV model. See section 3.1 in the technical report.

author:

Michel Bierlaire

date:

Sun Nov 5 15:56:36 2023

biogeme.mdcev.gamma_profile.gamma_profile(baseline_utilities, consumed_quantities, gamma_parameters, prices=None)

Calculates the determinant entries for the linear expenditure system

Parameters:

• baseline_utilities (dict[int, Expression]) – see the module documentation biogeme.mdcev

• consumed_quantities (dict[int, Expression]) – see the module documentation biogeme.mdcev

• gamma_parameters (dict[int, Optional[Expression]]) – see the module documentation biogeme.mdcev

• prices (Optional[dict[int, Expression]]) – see the module documentation biogeme.mdcev. If None, assumed to be 1.

biogeme.mdcev.gamma_profile.mdcev_gamma(number_of_chosen_alternatives, consumed_quantities, baseline_utilities, gamma_parameters, prices=None, scale_parameter=None)

Generate the Biogeme formula for the log probability of the MDCEV model using the linear expenditure system.

Parameters:

• number_of_chosen_alternatives (Expression) – see the module documentation biogeme.mdcev

• consumed_quantities (dict[int, Expression]) – see the module documentation biogeme.mdcev

• baseline_utilities (dict[int, Expression]) – see the module documentation biogeme.mdcev

• gamma_parameters (dict[int, Optional[Expression]]) – see the module documentation biogeme.mdcev

• prices (Optional[dict[int, Expression]]) – see the module documentation biogeme.mdcev

• scale_parameter (Optional[Expression]) – see the module documentation biogeme.mdcev

A detailed explanation is provided in the technical report “Estimating the MDCEV model with Biogeme”

biogeme.mdcev.non_monotonic module

Implementation of the “non monotonic” MDCEV model. See section 3.2 in the technical report.

author:

Michel Bierlaire

date:

Sun Nov 5 15:58:46 2023

biogeme.mdcev.non_monotonic.mdcev_non_monotonic(number_of_chosen_alternatives, consumed_quantities, baseline_utilities, mu_utilities, alpha_parameters, gamma_parameters, prices=None)

Generate the Biogeme formula for the log probability of the MDCEV model using the linear expenditure system.

Parameters:

• number_of_chosen_alternatives (Expression) – see the module documentation biogeme.mdcev

• consumed_quantities (dict[int, Expression]) – see the module documentation biogeme.mdcev

• baseline_utilities (dict[int, Expression]) – see the module documentation biogeme.mdcev

• mu_utilities (dict[int, Expression]) – additional utility for the non-monotonic part. see the module documentation biogeme.mdcev

• alpha_parameters (dict[int, Expression]) – see the module documentation biogeme.mdcev

• gamma_parameters (dict[int, Optional[Expression]]) – see the module documentation biogeme.mdcev

• prices (Optional[dict[int, Expression]]) – see the module documentation biogeme.mdcev

A detailed explanation is provided in the technical report “Estimating the MDCEV model with Biogeme”

biogeme.mdcev.non_monotonic.non_monotonic(baseline_utilities, mu_utilities, consumed_quantities, alpha_parameters, gamma_parameters, prices=None)

Calculates the determinant entries for the linear expenditure system

Parameters:

• baseline_utilities (dict[int: biogeme.expression.Expression]) – see the module documentation biogeme.mdcev

• consumed_quantities (dict[int: biogeme.expression.Expression]) – see the module documentation biogeme.mdcev

• alpha_parameters (dict[int: biogeme.expression.Expression]) – see the module documentation biogeme.mdcev

• gamma_parameters (dict[int: biogeme.expression.Expression]) – see the module documentation biogeme.mdcev

• prices (biogeme.expressions.Expression) – see the module documentation biogeme.mdcev. If None, assumed to be 1.