biogeme.mdcev.mdcev module

Implements the MDCEV model as a generic class

Michel Bierlaire Sun Apr 7 16:52:33 2024

class biogeme.mdcev.mdcev.Mdcev(model_name, baseline_utilities, gamma_parameters, alpha_parameters=None, scale_parameter=None, weights=None)[source]

Bases: ABC

Parameters:
calculate_baseline_utility(alternative_id, one_observation)[source]

As this function may be called many times with the same input in forecasting mode, we use the lru_cache decorator.

Return type:

float

Parameters:

  • alternative_id (int)

  • one_observation (Database)

calculate_inverse_of_determinant_entries(consumption)[source]
Return type:

dict[int, Expression]

Parameters:

consumption (dict[int, Expression])

abstract calculate_inverse_of_determinant_one_alternative(the_id, consumption)[source]
Return type:

Expression

Parameters:
calculate_log_determinant_entries(consumption)[source]
Return type:

dict[int, Expression]

Parameters:

consumption (dict[int, Expression])

abstract calculate_log_determinant_one_alternative(the_id, consumption)[source]
Return type:

Expression

Parameters:
calculate_utilities(consumption)[source]
Return type:

dict[int, Expression]

Parameters:

consumption (dict[int, Expression])

abstract derivative_utility_one_alternative(the_id, the_consumption, epsilon, one_observation)[source]

Used in the optimization problem solved for forecasting tp calculate the dual variable.

Return type:

float

Parameters:

  • the_id (int)

  • the_consumption (float)

  • epsilon (float)

  • one_observation (Database)

estimate_parameters(database, number_of_chosen_alternatives, consumed_quantities, **kwargs)[source]

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

Parameters:

  • database (Database) – data needed for the estimation of the parameters, in Biogeme format.

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

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

  • **kwargs –

    additional parameters that are transmitted as such to the constructor of the Biogeme object.

Return type:

bioResults

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

property estimation_results: bioResults | None

Property for the estimation results

forecast(database, total_budget, epsilons, brute_force=False, tolerance_dual=1e-10, tolerance_budget=1e-10)[source]

Forecast the optimal expenditures given a budget and one realization of epsilon for each alternative

Parameters:

  • database (Database) – database containing the values of the explanatory variables.

  • total_budget (float) – total budget.

  • epsilons (list[ndarray]) – draws from the error terms provided by the user. Each entry of the list corresponds to an observation in the database, and consists of a data frame of size=(number_of_draws, self.number_of_alternatives).

  • brute_force (bool) – if True, the brute force algorithm is applied. It solves each optimization problem using the scipy optimization algorithm. If False, the method proposed by Pinjari and Bhat (2021) is used.

  • tolerance_dual (float) – convergence criterion for the estimate of the dual variable.

  • tolerance_budget (float) – convergence criterion for the estimate of the total budget.

Return type:

list[DataFrame]

Returns:

a list of data frames, each containing the results for each draw

[PinjBhat21]

A. R. Pinjari, C. Bhat, Computationally efficient forecasting procedures for Kuhn-Tucker consumer demand model systems: Application to residential energy consumption analysis, Journal of Choice Modelling, Volume 39, 2021, 100283.

forecast_bisection_one_draw(one_row_of_database, total_budget, epsilon, tolerance_dual=1e-13, tolerance_budget=1e-13)[source]
Return type:

dict[int, float]

Parameters:

  • one_row_of_database (Database)

  • total_budget (float)

  • epsilon (ndarray)

forecast_bruteforce_one_draw(one_row_database, total_budget, epsilon)[source]

Forecast the optimal expenditures given a budget and one realization of epsilon for each alternative. If there is an issue with the optimization algorithm, None is returned.

Return type:

dict[int, float] | None

Parameters:

  • one_row_database (Database)

  • total_budget (float)

  • epsilon (ndarray)

forecast_comparison_one_draw(one_row_of_database, total_budget, epsilon, tolerance_dual=1e-10, tolerance_budget=1e-10)[source]

Compares the results from each of the two forecasting algorithms. :type one_row_of_database: Database :param one_row_of_database: list of rows from the database containing the values of the explanatory variables. :type total_budget: float :param total_budget: total budget. :type epsilon: array :param epsilon: draws from the error terms provided by the user. Length: self.number_of_alternatives. :type tolerance_dual: float :param tolerance_dual: convergence criterion for the estimate of the dual variable. :type tolerance_budget: float :param tolerance_budget: convergence criterion for the estimate of the total budget. :rtype: dict[int, float] | None :return: None. Warning are triggered if discrepancies are observed.

Parameters:

  • one_row_of_database (Database)

  • total_budget (float)

  • epsilon (array)

  • tolerance_dual (float)

  • tolerance_budget (float)

Return type:

dict[int, float] | None

generate_epsilons(number_of_observations, number_of_draws)[source]

Generate draws for the error terms.

Parameters:

  • number_of_observations (int) – number of entries in the database.

  • number_of_draws (int) – number of draws to generate

Return type:

list[ndarray]

Returns:

a list of length “number_of_observations”. Each element is a

number_of_draws x self.number_of_alternatives array.

identification_chosen_alternatives(database, total_budget, epsilon)[source]

Algorithm identifying the chosen alternatives at the optimal solution

Parameters:

  • database (Database) – one row of the database.

  • total_budget (float) – total budget for the constraint.

  • epsilon (ndarray) – vector of draws from the error term.

Return type:

tuple[set[int], float, float]

Returns:

the set of chosen alternatives, as well as a lower and an upper bound on the dual variable.

info_gamma_parameters()[source]

Provides logging information about the outside good

Return type:

str

is_next_alternative_chosen(chosen_alternatives, candidate_alternative, derivative_zero_expenditure_candidate, database, total_budget, epsilon)[source]
Return type:

tuple[bool, float | None]

Parameters:

  • chosen_alternatives (set[int])

  • candidate_alternative (int)

  • derivative_zero_expenditure_candidate (float)

  • database (Database)

  • total_budget (float)

  • epsilon (ndarray)

loglikelihood(number_of_chosen_alternatives, consumed_quantities)[source]

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

Parameters:

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

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

Return type:

Expression

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

abstract lower_bound_dual_variable(chosen_alternatives, one_observation, epsilon)[source]

Method providing model specific bounds on the dual variable. It not overloaded, default values are used.

Parameters:

  • chosen_alternatives (set[int]) – list of alternatives that are chosen at the optimal solution

  • one_observation (Database) – data for one observation.

  • epsilon (ndarray) – draws from the error term.

Return type:

float

Returns:

a lower bound on the dual variable, such that the expenditure calculated for any larger value is

well-defined and non negative.

property number_of_alternatives: int
optimal_consumption(chosen_alternatives, dual_variable, epsilon, one_observation)[source]

Analytical calculation of the optimal consumption if the dual variable is known.

Return type:

dict[int, float]

Parameters:

  • chosen_alternatives (Iterable[int])

  • dual_variable (float)

  • epsilon (ndarray)

  • one_observation (Database)

abstract optimal_consumption_one_alternative(the_id, dual_variable, epsilon, one_observation)[source]

Analytical calculation of the optimal consumption if the dual variable is known.

Return type:

float

Parameters:

  • the_id (int)

  • dual_variable (float)

  • epsilon (float)

  • one_observation (Database)

property outside_good_index: int | None

Obtain the index of the outside good.

sum_of_utilities(consumptions, epsilon, data_row)[source]

Calculates the sum of all utilities. Used for forecasting.

Return type:

float

Parameters:

  • consumptions (ndarray)

  • epsilon (ndarray)

  • data_row (Database)

abstract transformed_utility(the_id, the_consumption)[source]

Calculates the transformed utility for one alternative. Used for estimation

Return type:

Expression

Parameters:
abstract utility_expression_one_alternative(the_id, the_consumption, unscaled_epsilon)[source]

Utility expression. Used only for code validation.

Return type:

Expression

Parameters:
abstract utility_one_alternative(the_id, the_consumption, epsilon, one_observation)[source]

Utility needed for forecasting

Return type:

float

Parameters:

  • the_id (int)

  • the_consumption (float)

  • epsilon (float)

  • one_observation (Database)

validate_forecast(database, total_budget, epsilons, tolerance_dual=1e-13, tolerance_budget=1e-13)[source]

Compare the two algorithms to forecast the optimal expenditures given a budget and one realization of epsilon for each alternative

Parameters:

  • database (Database) – database containing the values of the explanatory variables.

  • total_budget (float) – total budget.

  • epsilons (list[ndarray]) – draws from the error terms. Each entry of the list corresponds to an observation in the database, and consists of a data frame of size=(number_of_draws, self.number_of_alternatives).

  • tolerance_dual (float) – convergence criterion for the estimate of the dual variable.

  • tolerance_budget (float) – convergence criterion for the estimate of the total budget.

Return type:

None

Returns:

None. Warning are triggered if discrepancies are observed

validation(one_row)[source]

Validation of some abstract methods for all alternatives.

Return type:

list[str]

Parameters:

one_row (Database)

validation_one_alternative(alternative_id, one_row)[source]
Return type:

list[str]

Parameters:

  • alternative_id (int)

  • one_row (Database)

validation_one_alternative_one_consumption(alternative_id, value_consumption, one_row)[source]

Validation of some of the abstract methods.

Return type:

list[str]

Parameters:

  • alternative_id (int)

  • value_consumption (float)

  • one_row (Database)

class biogeme.mdcev.mdcev.MdcevConfiguration(gamma_is_none, price_is_none)[source]

Bases: object

Identify various configurations of the model

Parameters:

  • gamma_is_none (bool)

  • price_is_none (bool)

gamma_is_none: bool
price_is_none: bool