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 asymptotic covariance matrix for \(\sqrt{N}(\hat{\theta} - \theta_0)\), in which \(\theta\) are the stacked parameters. Standard errors are the square root of the diagonal of this matrix divided by \(N\). 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

theta_labels¶

Variable labels for \(\theta\), which are derived from the above labels.

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

xi_fe¶

Estimated demand-side fixed effects \(\xi_{k_1} + \cdots \xi_{k_{E_D}}\) in (32), which are only computed when there are demand-side fixed effects.

Type: ndarray

omega_fe¶

Estimated supply-side fixed effects \(\omega_{k_1} + \cdots \omega_{k_{E_D}}\) in (32), which are only computed when there are supply-side fixed effects.

Type: ndarray

micro¶

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

Type: ndarray

micro_values¶

Estimated micro moment values, \(f_m(v)\). Rows are in the same order as ProblemResults.micro.

Type: ndarray

micro_covariances¶

Estimated micro moment covariance matrix \(S_M\) in (37) divided by \(N\). Equal to micro_sample_covariances if overridden in Problem.solve().

Type: ndarray

moments¶

Moments, \(\bar{g}\), in (11).

Type: ndarray

moments_jacobian¶

Jacobian \(\bar{G}\) of moments with respect to \(\theta\), in (19).

Type: ndarray

simulation_covariances¶

Adjustment in (29) to moment covariances to account for simulation error. This will be all zeros unless resample_agent_data was specified in Problem.solve().

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

Tutorial

Methods

`bootstrap`([draws, seed, iteration, …])	Use a parametric bootstrap to create an empirical distribution of results.
`compute_agent_scores`(dataset[, micro_data, …])	Compute scores for all agent-choices, treated as observations \(n \in N_d\) from a micro dataset \(d\).
`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_demand_hessians`([name, market_id])	Estimate arrays of second derivatives of demand with respect to a variable, \(x\).
`compute_demand_jacobians`([name, market_id])	Estimate matrices of derivatives of demand with respect to a variable, \(x\).
`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_micro_scores`(dataset, micro_data[, …])	Compute scores for observations \(n \in N_d\) from a micro dataset \(d\).
`compute_micro_values`(micro_moments)	Estimate micro moment values, \(f_m(v)\).
`compute_optimal_instruments`([method, draws, …])	Estimate feasible optimal or efficient instruments, \(Z_D^\text{opt}\) and \(Z_S^\text{opt}\).
`compute_passthrough`([firm_ids, ownership, …])	Estimate matrices of passthrough of marginal costs to equilibrium prices, \(\Upsilon\).
`compute_prices`([firm_ids, ownership, costs, …])	Estimate equilibrium prices after firm or cost changes, \(p^*\).
`compute_probabilities`([prices, delta, …])	Estimate matrices of choice probabilities.
`compute_profit_hessians`([prices, costs, …])	Estimate arrays of second derivatives of profits with respect to a prices.
`compute_profits`([prices, shares, costs, …])	Estimate population-normalized gross expected profits, \(\pi\).
`compute_shares`([prices, delta, agent_data, …])	Estimate shares.
`extract_diagonal_means`(matrices[, market_id])	Extract means of diagonals from stacked \(J_t \times J_t\) matrices for each market \(t\).
`extract_diagonals`(matrices[, market_id])	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.
`simulate_micro_data`(dataset[, seed])	Simulate observations \(n \in N_d\) from a micro dataset \(d\).
`to_dict`([attributes])	Convert these results into a dictionary that maps attribute names to values.
`to_pickle`(path)	Save these results as a pickle file.