pyblp.ProblemResults.compute_consumer_surpluses

ProblemResults.compute_consumer_surpluses(prices=None, keep_all=False, eliminate_product_ids=None, product_ids_index=0, market_id=None)

Estimate population-normalized consumer surpluses, \(\text{CS}\).

Assuming away nonlinear income effects, the surplus in market \(t\) is

(1)\[\text{CS} = \sum_{i \in I_t} w_{it}\text{CS}_{it},\]

in which the consumer surplus for individual \(i\) is

(2)\[\text{CS}_{it} = \log\left(1 + \sum_{j \in J_t} \exp V_{ijt}\right) \Big/ \left(-\frac{\partial V_{i1t}}{\partial p_{1t}}\right),\]

or with nesting parameters,

(3)\[\text{CS}_{it} = \log\left(1 + \sum_{h \in H} \exp V_{iht}\right) \Big/ \left(-\frac{\partial V_{i1t}}{\partial p_{1t}}\right)\]

where \(V_{ijt}\) is defined in (1) and \(V_{iht}\) is defined in (44).

Warning

\(\frac{\partial V_{1ti}}{\partial p_{1t}}\) is the derivative of utility for the first product with respect to its price. The first product is chosen arbitrarily because this method assumes that there are no nonlinear income effects, which implies that this derivative is the same for all products. Computed consumer surpluses will likely be incorrect if prices are formulated in a nonlinear fashion like log(prices).

Comparing consumer surpluses with the same values computed after eliminating one or more products from the agents’ choice sets (i.e. setting \(\exp V_{ijt} = 0\) for eliminated products \(j\)) gives a measure of willingness to pay. This can be done with the eliminate_product_ids argument.

Parameters

  • prices (array-like, optional) – Prices at which utilities and price derivatives will be evaluated, such as equilibrium prices, \(p^*\), computed by ProblemResults.compute_prices(). By default, unchanged prices are used.

  • keep_all (bool, optional) – Whether to keep all individuals’ surpluses \(\text{CS}_{it}\) or just market-level surpluses. By default only market-level surpluses are returned, but returning all surpluses will be important for analysis by agent type or demographic category.

  • eliminate_product_ids (sequence of object, optional) – IDs of the products to eliminate from the choice set. These IDs should show up in the product_ids field of product_data in Problem. Eliminating one or more products and comparing consumer surpluses gives a measure of willingness to pay for these products.

  • product_ids_index (int, optional) – Index between 0 and the number of columns in the product_ids field of product_data minus one, inclusive, which determines which column of product IDs eliminate_product_ids refers to. By default, it refers to the first column, which is index 0.

  • market_id (object, optional) – ID of the market in which to compute consumer surplus. By default, consumer surpluses are computed in all markets and stacked.

Returns

Estimated population-normalized consumer surpluses, \(\text{CS}\) (or individuals’ surpluses if keep_all is True). If market_ids was not specified, rows are in the same order as Problem.unique_market_ids. If keep_all is True, columns for a market are in the same order as agents for the market. If a market has fewer agents than others, extra columns will contain numpy.nan.

Return type

ndarray

Examples