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

All methods in this class 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

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

converged

Whether the optimization routine converged.

Type

bool

cumulative_converged

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

Type

bool

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.

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}\).

Type

ndarray

pi_se

Estimated standard errors for \(\hat{\Pi}\).

Type

ndarray

rho_se

Estimated standard errors for \(\hat{\rho}\).

Type

ndarray

beta_se

Estimated standard errors for \(\hat{\beta}\).

Type

ndarray

gamma_se

Estimated standard errors for \(\hat{\gamma}\).

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 (31). 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 (31). That is, fixed effects are not included.

Type

ndarray

objective

GMM objective value, \(q(\hat{\theta})\), defined in (10).

Type

float

xi_by_theta_jacobian

Estimated \(\frac{\partial\xi}{\partial\theta} = \frac{\partial\delta}{\partial\theta}\).

Type

ndarray

omega_by_theta_jacobian

Estimated \(\frac{\partial\omega}{\partial\theta} = \frac{\partial\tilde{c}}{\partial\theta}\).

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

sigma_gradient

Estimated gradient of the GMM objective with respect to \(\Sigma\) elements in \(\theta\).

Type

ndarray

pi_gradient

Estimated gradient of the GMM objective with respect to \(\Pi\) elements in \(\theta\).

Type

ndarray

rho_gradient

Estimated gradient of the GMM objective with respect to \(\rho\) elements in \(\theta\).

Type

ndarray

beta_gradient

Estimated gradient of the GMM objective with respect to \(\beta\) elements in \(\theta\).

Type

ndarray

gamma_gradient

Estimated gradient of the GMM objective with respect to \(\gamma\) elements in \(\theta\).

Type

ndarray

gradient_norm

Infinity norm of ProblemResults.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

hessian_eigenvalues

Eigenvalues of ProblemResults.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, name])

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])

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

compute_costs()

Estimate marginal costs, \(c\).

compute_diversion_ratios([name])

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

compute_elasticities([name])

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

compute_hhi([firm_ids, shares])

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

compute_long_run_diversion_ratios()

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

compute_markups([prices, costs])

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_profits([prices, shares, costs])

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

compute_shares([prices])

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\).