# pyblp.OptimalInstrumentResults¶

class pyblp.OptimalInstrumentResults

Results of optimal instrument computation.

The OptimalInstrumentResults.to_problem() method can be used to update the original Problem with the computed optimal instruments.

problem_results

ProblemResults that was used to compute these optimal instrument results.

Type

ProblemResults

demand_instruments

Estimated optimal demand-side instruments for $$\theta$$, denoted $$Z_D^\text{opt}$$.

Type

ndarray

supply_instruments

Estimated optimal supply-side instruments for $$\theta$$, denoted $$Z_S^\text{opt}$$.

Type

ndarray

supply_shifter_formulation

Formulation configuration for supply shifters that will by default be included in the full set of optimal demand-side instruments. This is only constructed if a supply side was estimated, and it can be changed in OptimalInstrumentResults.to_problem(). By default, this is the formulation for $$X_3^\text{ex}$$ from Problem excluding any variables in the formulation for $$X_1^\text{ex}$$.

Type

Formulation or None

demand_shifter_formulation

Formulation configuration for demand shifters that will by default be included in the full set of optimal supply-side instruments. This is only constructed if a supply side was estimated, and it can be changed in OptimalInstrumentResults.to_problem(). By default, this is the formulation for $$X_1^\text{ex}$$ from Problem excluding any variables in the formulation for $$X_3^\text{ex}$$.

Type

Formulation or None

inverse_covariance_matrix

Inverse of the sample covariance matrix of the estimated $$\xi$$ and $$\omega$$, which is used to normalize the expected Jacobians. If a supply side was not estimated, this is simply the sample estimate of $$1 / \sigma_{\xi}^2$$.

Type

ndarray

expected_xi_by_theta_jacobian

Estimated $$E[\frac{\partial\xi}{\partial\theta} \mid Z]$$.

Type

ndarray

expected_omega_by_theta_jacobian

Estimated $$E[\frac{\partial\omega}{\partial\theta} \mid Z]$$.

Type

ndarray

expected_prices

Vector of expected prices conditional on all exogenous variables, $$E[p \mid Z]$$, which may have been specified in ProblemResults.compute_optimal_instruments().

Type

ndarray

expected_shares

Vector of expected market shares conditional on all exogenous variables, $$E[s \mid Z]$$.

Type

ndarray

computation_time

Number of seconds it took to compute optimal excluded instruments.

Type

float

draws

Number of draws used to approximate the integral over the error term density.

Type

int

fp_converged

Flags for convergence of the iteration routine used to compute equilibrium prices in each market. Rows are in the same order as Problem.unique_market_ids and column indices correspond to draws.

Type

ndarray

fp_iterations

Number of major iterations completed by the iteration routine used to compute equilibrium prices in each market for each error term draw. Rows are in the same order as Problem.unique_market_ids and column indices correspond to draws.

Type

ndarray

contraction_evaluations

Number of times the contraction used to compute equilibrium prices was evaluated in each market for each error term draw. Rows are in the same order as Problem.unique_market_ids and column indices correspond to draws.

Type

ndarray

Examples

Methods

 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. to_problem([supply_shifter_formulation, …]) Re-create the problem with estimated feasible optimal instruments.