pyblp.ProblemResults

class pyblp.ProblemResults

Results of a solved BLP problem.

Many results are class attributes. Other post-estimation outputs be computed by calling class methods.

Note

Methods in this class that compute one or more post-estimation output per market support parallel() processing. If multiprocessing is used, market-by-market computation of each post-estimation output will be distributed among the processes.

problem

Problem that created these results.

Type

Problem

last_results

ProblemResults from the last GMM step.

Type

ProblemResults

step

GMM step that created these results.

Type

int

optimization_time

Number of seconds it took the optimization routine to finish.

Type

float

cumulative_optimization_time

Sum of ProblemResults.optimization_time for this step and all prior steps.

Type

float

total_time

Sum of ProblemResults.optimization_time and the number of seconds it took to set up the GMM step and compute results after optimization had finished.

Type

float

cumulative_total_time

Sum of ProblemResults.total_time for this step and all prior steps.

Type

float

converged

Whether the optimization routine converged.

Type

bool

cumulative_converged

Whether the optimization routine converged for this step and all prior steps.

Type

bool

optimization_iterations

Number of major iterations completed by the optimization routine.

Type

int

cumulative_optimization_iterations

Sum of ProblemResults.optimization_iterations for this step and all prior steps.

Type

int

objective_evaluations

Number of GMM objective evaluations.

Type

int

cumulative_objective_evaluations

Sum of ProblemResults.objective_evaluations for this step and all prior steps.

Type

int

fp_converged

Flags for convergence of the iteration routine used to compute \(\delta(\hat{\theta})\) in each market during each objective evaluation. Rows are in the same order as Problem.unique_market_ids and column indices correspond to objective evaluations.

Type

ndarray

cumulative_fp_converged

Concatenation of ProblemResults.fp_converged for this step and all prior steps.

Type

ndarray

fp_iterations

Number of major iterations completed by the iteration routine used to compute \(\delta(\hat{\theta})\) in each market during each objective evaluation. Rows are in the same order as Problem.unique_market_ids and column indices correspond to objective evaluations.

Type

ndarray

cumulative_fp_iterations

Concatenation of ProblemResults.fp_iterations for this step and all prior steps.

Type

ndarray

contraction_evaluations

Number of times the contraction used to compute \(\delta(\hat{\theta})\) was evaluated in each market during each objective evaluation. Rows are in the same order as Problem.unique_market_ids and column indices correspond to objective evaluations.

Type

ndarray

cumulative_contraction_evaluations

Concatenation of ProblemResults.contraction_evaluations for this step and all prior steps.

Type

ndarray

parameters

Stacked parameters in the following order: \(\hat{\theta}\), concentrated out elements of \(\hat{\beta}\), and concentrated out elements of \(\hat{\gamma}\).

Type

ndarray

parameter_covariances

Estimated covariance matrix of the stacked parameters, from which standard errors are extracted. Parameter covariances are not estimated during the first step of two-step GMM.

Type

ndarray

theta

Estimated unfixed parameters, \(\hat{\theta}\), in the following order: \(\hat{\Sigma}\), \(\hat{\Pi}\), \(\hat{\rho}\), non-concentrated out elements from \(\hat{\beta}\), and non-concentrated out elements from \(\hat{\gamma}\).

Type

ndarray

sigma

Estimated Cholesky root of the covariance matrix for unobserved taste heterogeneity, \(\hat{\Sigma}\).

Type

ndarray

pi

Estimated parameters that measures how agent tastes vary with demographics, \(\hat{\Pi}\).

Type

ndarray

rho

Estimated parameters that measure within nesting group correlations, \(\hat{\rho}\).

Type

ndarray

beta

Estimated demand-side linear parameters, \(\hat{\beta}\).

Type

ndarray

gamma

Estimated supply-side linear parameters, \(\hat{\gamma}\).

Type

ndarray

sigma_se

Estimated standard errors for \(\hat{\Sigma}\), which are not estimated in the first step of two-step GMM.

Type

ndarray

pi_se

Estimated standard errors for \(\hat{\Pi}\), which are not estimated in the first step of two-step GMM.

Type

ndarray

rho_se

Estimated standard errors for \(\hat{\rho}\), which are not estimated in the first step of two-step GMM.

Type

ndarray

beta_se

Estimated standard errors for \(\hat{\beta}\), which are not estimated in the first step of two-step GMM.

Type

ndarray

gamma_se

Estimated standard errors for \(\hat{\gamma}\), which are not estimated in the first step of two-step GMM.

Type

ndarray

sigma_bounds

Bounds for \(\Sigma\) that were used during optimization, which are of the form (lb, ub).

Type

tuple

pi_bounds

Bounds for \(\Pi\) that were used during optimization, which are of the form (lb, ub).

Type

tuple

rho_bounds

Bounds for \(\rho\) that were used during optimization, which are of the form (lb, ub).

Type

tuple

beta_bounds

Bounds for \(\beta\) that were used during optimization, which are of the form (lb, ub).

Type

tuple

gamma_bounds

Bounds for \(\gamma\) that were used during optimization, which are of the form (lb, ub).

Type

tuple

delta

Estimated mean utility, \(\delta(\hat{\theta})\).

Type

ndarray

tilde_costs

Estimated transformed marginal costs, \(\tilde{c}(\hat{\theta})\) from (9). If costs_bounds were specified in Problem.solve(), \(c\) may have been clipped.

Type

ndarray

clipped_costs

Vector of booleans indicating whether the associated marginal costs were clipped. All elements will be False if costs_bounds in Problem.solve() was not specified.

Type

ndarray

xi

Estimated unobserved demand-side product characteristics, \(\xi(\hat{\theta})\), or equivalently, the demand-side structural error term. When there are demand-side fixed effects, this is \(\Delta\xi(\hat{\theta})\) in (32). That is, fixed effects are not included.

Type

ndarray

omega

Estimated unobserved supply-side product characteristics, \(\omega(\hat{\theta})\), or equivalently, the supply-side structural error term. When there are supply-side fixed effects, this is \(\Delta\omega(\hat{\theta})\) in (32). That is, fixed effects are not included.

Type

ndarray

micro

Averaged micro moments, \(\bar{g}_M\), in (34).

Type

ndarray

objective

GMM objective value, \(q(\hat{\theta})\), defined in (10). Note that in some of the BLP literature (and earlier versions of this package), this expression was previously scaled by \(N^2\).

Type

float

xi_by_theta_jacobian

Estimated \(\frac{\partial\xi}{\partial\theta} = \frac{\partial\delta}{\partial\theta}\), which is used to compute the gradient and standard errors.

Type

ndarray

omega_by_theta_jacobian

Estimated \(\frac{\partial\omega}{\partial\theta} = \frac{\partial\tilde{c}}{\partial\theta}\), which is used to compute the gradient and standard errors.

Type

ndarray

micro_by_theta_jacobian

Estimated \(\frac{\partial\bar{g}_M}{\partial\theta}\), which is used to compute the gradient and standard errors.

Type

ndarray

gradient

Gradient of the GMM objective, \(\nabla q(\hat{\theta})\), defined in (18). This is computed after the optimization routine finishes even if the routine was configured to not use analytic gradients.

Type

ndarray

projected_gradient

Projected gradient of the GMM objective. When there are no parameter bounds, this will always be equal to ProblemResults.gradient. Otherwise, if an element in \(\hat{\theta}\) is equal to its lower (upper) bound, the corresponding projected gradient value will be truncated at a maximum (minimum) of zero.

Type

ndarray

projected_gradient_norm

Infinity norm of ProblemResults.projected_gradient.

Type

ndarray

hessian

Estimated Hessian of the GMM objective. By default, this is computed with finite central differences after the optimization routine finishes.

Type

ndarray

reduced_hessian

Reduced Hessian of the GMM objective. When there are no parameter bounds, this will always be equal to ProblemResults.hessian. Otherwise, if an element in \(\hat{\theta}\) is equal to either its lower or upper bound, the corresponding row and column in the reduced Hessian will be all zeros.

Type

ndarray

reduced_hessian_eigenvalues

Eigenvalues of ProblemResults.reduced_hessian.

Type

ndarray

W

Weighting matrix, \(W\), used to compute these results.

Type

ndarray

updated_W

Weighting matrix updated according to (24).

Type

ndarray

Examples

Methods

bootstrap([draws, seed, iteration])

Use a parametric bootstrap to create an empirical distribution of results.

compute_aggregate_elasticities([factor, …])

Estimate aggregate elasticities of demand, \(\mathscr{E}\), with respect to a variable, \(x\).

compute_approximate_prices([firm_ids, …])

Approximate equilibrium prices after firm or cost changes, \(p^*\), under the assumption that shares and their price derivatives are unaffected by such changes.

compute_consumer_surpluses([prices, market_id])

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

compute_costs([market_id])

Estimate marginal costs, \(c\).

compute_diversion_ratios([name, market_id])

Estimate matrices of diversion ratios, \(\mathscr{D}\), with respect to a variable, \(x\).

compute_elasticities([name, market_id])

Estimate matrices of elasticities of demand, \(\varepsilon\), with respect to a variable, \(x\).

compute_hhi([firm_ids, shares, market_id])

Estimate Herfindahl-Hirschman Indices, \(\text{HHI}\).

compute_long_run_diversion_ratios([market_id])

Estimate matrices of long-run diversion ratios, \(\bar{\mathscr{D}}\).

compute_markups([prices, costs, market_id])

Estimate markups, \(\mathscr{M}\).

compute_optimal_instruments([method, draws, …])

Estimate feasible optimal or efficient instruments, \(Z_D^\textit{Opt}\) and \(Z_S^\textit{Opt}\).

compute_prices([firm_ids, ownership, costs, …])

Estimate equilibrium prices after firm or cost changes, \(p^*\).

compute_probabilities([market_id])

Estimate matrices of choice probabilities.

compute_profits([prices, shares, costs, …])

Estimate population-normalized gross expected profits, \(\pi\).

compute_shares([prices, market_id])

Estimate shares evaluated at specified prices.

extract_diagonal_means(matrices)

Extract means of diagonals from stacked \(J_t \times J_t\) matrices for each market \(t\).

extract_diagonals(matrices)

Extract diagonals from stacked \(J_t \times J_t\) matrices for each market \(t\).

run_distance_test(unrestricted)

Test the validity of model restrictions with the distance test.

run_hansen_test()

Test the validity of overidentifying restrictions with the Hansen \(J\) test.

run_lm_test()

Test the validity of model restrictions with the Lagrange multiplier test.

run_wald_test(restrictions, …)

Test the validity of model restrictions with the Wald test.

to_dict([attributes])

Convert these results into a dictionary that maps attribute names to values.