pyblp.Simulation.replace_exogenous

Simulation.replace_exogenous(X1_name, X3_name=None, delta=None, iteration=None, fp_type='safe_linear', shares_bounds=(1e-300, None), error_behavior='raise')

Replace exogenous product characteristics with values that are consistent with true parameters.

This method implements a less common way of solving the simulation. It may be preferable to Simulation.replace_endogenous() when for some reason it is desirable to retain the prices and market shares from Simulation, which are assumed to be in equilibrium. For example, it can be helpful when approximating the pure characteristics model of Berry and Pakes (2007) by setting a small epsilon_scale value in Simulation.

For this method of solving the simulation to be used, there must be an exogenous product characteristic \(v\) that shows up only in \(X_1^\text{ex}\), and if there is a supply side, another product characteristic \(w\) that shows up only in \(X_3^\text{ex}\). These characteristics will be replaced with values that are consistent with true parameters.

First, the mean utility \(\delta\) is computed in each market by iterating over the contraction in (13) and \((\delta - \xi - X_1 \beta)\beta_v^{-1}\) is added to the \(v\) from Simulation. Here, \(\beta_v\) is the linear parameter in \(\beta\) on \(v\).

With a supply side, the marginal cost function \(\tilde{c}\) is computed according to (7) and (9) and \((\tilde{c} - \omega - X_3 \gamma)\gamma_w^{-1}\) is added to the \(w\) from Simulation. Here, \(\gamma_w\) is the linear parameter in \(\gamma\) on \(w\).

Note

This method supports parallel() processing. If multiprocessing is used, market-by-market computation of prices and shares will be distributed among the processes.

Parameters

  • X1_name (str) – The name of the variable \(v\) in \(X_1^\text{ex}\) that will be replaced. It should show up only once in the formulation for \(X_1\) from Simulation and it should not be transformed in any way.

  • X3_name (str, optional) – The name of the variable \(w\) in \(X_3^\text{ex}\) that will be replaced. It should show up only once in the formulation for \(X_3\) from Simulation and it should not be transformed in any way. This will only be used if there is a supply side.

  • delta (array-like, optional) – Initial values for the mean utility, \(\delta\), which the fixed point iteration routine will start at. By default, the solution to the logit model in (46) is used. If there is a nesting structure, solution to the nested logit model in (47) under the initial rho is used instead.

  • iteration (Iteration, optional) – Iteration configuration for how to solve the fixed point problem used to compute \(\delta\) in each market. This configuration is only relevant if there are nonlinear parameters, since \(\delta\) can be estimated analytically in the logit model. By default, Iteration('squarem', {'atol': 1e-14}) is used. For more information, refer to the same argument in Problem.solve().

  • fp_type (str, optional) – Configuration for the type of contraction mapping used to compute \(\delta\). For information about the different types, refer to the same argument in Problem.solve().

  • shares_bounds (tuple, optional) – Configuration for \(s_{jt}(\delta, \theta)\) bounds of the form (lb, ub), in which both lb and ub are floats or None. By default, simulated shares are bounded from below by 1e-300. This is only relevant if fp_type is 'safe_linear' or 'linear'. Bounding shares in the contraction does nothing with a nonlinear fixed point. For more information, refer to Problem.solve().

  • error_behavior (str, optional) –

    How to handle errors when computing \(\delta\) and \(\tilde{c}\). The following behaviors are supported:

    • 'raise' (default) - Raise an exception.

    • 'warn' - Use the last computed \(\delta\) and \(\tilde{c}\). If the fixed point routine fails to converge, these are the last \(\delta\) and the associated \(\tilde{c}\) by the routine. If there are other issues, these are the starting \(\delta\) values and their associated \(\tilde{c}\).

Returns

SimulationResults of the solved simulation.

Return type

SimulationResults

Examples