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(\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(\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(\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

sigma_squared

Estimated covariance matrix for unobserved taste heterogeneity, \(\hat{\Sigma}\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

sigma_squared_se

Estimated standard errors for \(\hat{\Sigma}\hat{\Sigma}'\), which are computed with the delta method, and 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

sigma_labels

Variable labels for rows and columns of \(\Sigma\), which are derived from the formulation for \(X_2\).

Type

list of str

pi_labels

Variable labels for columns of \(\Pi\), which are derived from the formulation for demographics.

Type

list of str

rho_labels

Variable labels for \(\rho\). If \(\rho\) is not a scalar, this is Problem.unique_nesting_ids.

Type

list of str

beta_labels

Variable labels for \(\beta\), which are derived from the formulation for \(X_1\).

Type

list of str

gamma_labels

Variable labels for \(\gamma\), which are derived from the formulation for \(X_3\).

Type

list of str

delta

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

Type

ndarray

clipped_shares

Vector of booleans indicator whether the associated simulated shares were clipped during the last fixed point iteration to compute \(\delta(\hat{\theta})\). All elements will be False if shares_bounds in Problem.solve() is disabled (by default shares are bounded from below by a small number to alleviate issues with underflow and negative shares).

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

micro_values

Simulated micro moment values, \(v_{mt}\). Rows are in the same order as Problem.unique_market_ids. Columns are in the same order as ProblemResults.micro. If a micro moment is not computed in one or more markets, the associated values will be numpy.nan.

Type

ndarray

objective

GMM objective value, \(q(\hat{\theta})\), defined in (10). If scale_objective was True in Problem.solve() (which is the default), this value was scaled by \(N\) so that objective values are more comparable across different problem sizes. 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, …])

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

compute_costs([firm_ids, ownership, market_id])

Estimate marginal costs, \(c\).

compute_delta([agent_data, integration, …])

Estimate mean utilities, \(\delta\).

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^\text{opt}\) and \(Z_S^\text{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, delta, agent_data, …])

Estimate shares.

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

importance_sampling(draws[, ar_constant, …])

Use importance sampling to construct nodes and weights for integration.

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.