API Documentation¶
The majority of the package consists of classes, which compartmentalize different aspects of the BLP model. There are some convenience functions as well.
Configuration Classes¶
Various components of the package require configurations for how to approximate integrals, solve fixed point problems, and solve optimimzation problems. Such configurations are specified with the following classes.

Configuration for designing matrices and absorbing fixed effects. 

Configuration for building integration nodes and weights. 

Configuration for solving fixed point problems. 

Configuration for solving optimization problems. 
Data Construction Functions¶
There are also a number of convenience functions that can be used to construct common components of product and agent data.

Construct a matrix according to a formulation. 

Construct traditional excluded BLP instruments. 
Construct excluded differentiation instruments. 


Build a balanced panel of market and firm IDs. 

Build ownership matrices, \(O\). 

Build nodes and weights for integration over agent choice probabilities. 
Simulation Class¶
In addition to reading from data files, data can be simulated by initializing the following class.

Simulation of synthetic data from BLPtype models. 
Once initialized, the following method computes equilibrium prices and shares.

Compute synthetic prices and shares. 
Simulation Results Class¶
Solved simulations return the following results class.
Results of a solved simulation of synthetic BLP data. 
The simulation results can be converted into a Problem
with the following method.
Convert the solved simulation into a problem. 
Problem Class¶
Given real or simulated data and appropriate configurations, the BLP problem can be structured by initializing the following class.

A BLPtype problem. 
Once initialized, the following method solves the problem.

Solve the problem. 
Problem Results Class¶
Solved problems return the following results class.
Results of a solved BLP problem. 
In addition to class attributes, other postestimation outputs can be estimated with the following methods, which each return an array.
Estimate aggregate elasticities of demand, \(\mathscr{E}\), with respect to a variable, \(x\). 

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

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

Estimate matrices of longrun diversion ratios, \(\bar{\mathscr{D}}\). 


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

Extract means of diagonals from stacked \(J_t \times J_t\) matrices for each market \(t\). 
Estimate marginal costs, \(c\). 

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


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

Estimate shares evaluated at specified prices. 

Estimate HerfindahlHirschman Indices, \(\text{HHI}\). 

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

Estimate populationnormalized gross expected profits, \(\pi\). 
Estimate populationnormalized consumer surpluses, \(\text{CS}\). 
A parametric bootstrap can be used, for example, to compute standard errors for the above postestimation outputs. The following method returns a results class with all of the above methods, which returns a distribution of postestimation outputs corresponding to different bootstrapped samples.

Use a parametric bootstrap to create an empirical distribution of results. 
Optimal instruments, which also return a results class instead of an array, can be estimated with the following method.
Estimate feasible optimal or efficient instruments, \(Z_D^\textit{Opt}\) and \(Z_S^\textit{Opt}\). 
Boostrapped Problem Results Class¶
Parametric bootstrap computation returns the following class.
Bootstrapped results of a solved problem. 
This class has all of the same methods as ProblemResults
, except for ProblemResults.bootstrap()
and ProblemResults.compute_optimal_instruments()
.
Optimal Instrument Results Class¶
Optimal instrument computation returns the following results class.
Results of optimal instrument computation. 
The optimal instrument results can be converted into a Problem
with the following method.
Recreate the problem with estimated feasible optimal instruments. 
This method returns the following class, which behaves exactly like a Problem
.
A BLP problem updated with optimal excluded instruments. 
Structured Data Classes¶
Product and agent data that are passed or constructed by Problem
and Simulation
are structured internally into classes with field names that more closely resemble BLP notation. Although these structured data classes are not directly constructable, they can be accessed with Problem
and Simulation
class attributes. It can be helpful to compare these structured data classes with the data or configurations used to create them.
Product data structured as a record array. 

Agent data structured as a record array. 
Multiprocessing¶
A context manager can be used to enable parallel processing for methods that perform marketbymarket computation.

Context manager used for parallel processing in a 
Options and Example Data¶
In addition to classes and functions, there are also two modules that can be used to configure global package options and locate example data that comes with the package.
Global options. 

Locations of example data that are included in the package for convenience. 
Exceptions¶
When errors occur, they will either be displayed as warnings or raised as exceptions.
Multiple errors that occurred around the same time. 

Encountered nonpositive marginal costs in a loglinear specification. 

Failed to compute standard errors because of invalid estimated covariances of GMM parameters. 

Failed to compute a weighting matrix because of invalid estimated covariances of GMM moments. 

Encountered floating point issues when computing \(\delta\). 

Encountered floating point issues when computing the Jacobian of \(\xi\) (equivalently, of \(\delta\)) with respect to \(\theta\). 

Encountered floating point issues when computing marginal costs. 

Encountered floating point issues when computing the Jacobian of \(\omega\) (equivalently, of transformed marginal costs) with respect to \(\theta\). 

Encountered floating point issues when computing synthetic prices. 

Encountered floating point issues when computing synthetic shares. 

Encountered floating point issues when computing equilibrium prices. 

Encountered floating point issues when computing equilibrium shares. 

An iterative demeaning procedure failed to converge when absorbing fixed effects. 

The optimization routine failed to converge. 

The fixed point computation of \(\delta\) failed to converge. 

The fixed point computation of synthetic prices failed to converge. 

The fixed point computation of equilibrium prices failed to converge. 

Reverted a problematic GMM objective value. 

Reverted problematic elements in the GMM objective gradient. 

Reverted problematic elements in \(\delta\). 

Reverted problematic marginal costs. 

Reverted problematic elements in the Jacobian of \(\xi\) (equivalently, of \(\delta\)) with respect to \(\theta\). 

Reverted problematic elements in the Jacobian of \(\omega\) (equivalently, of transformed marginal costs) with respect to \(\theta\). 

Failed to invert the \(A\) matrix from Somaini and Wolak (2016) when absorbing twoway fixed effects. 

Failed to compute eigenvalues for the GMM objective’s Hessian matrix. 

Failed to invert an estimated covariance when computing fitted values. 

Failed to invert a Jacobian of shares with respect to \(\xi\) when computing the Jacobian of \(\xi\) (equivalently, of \(\delta\)) with respect to \(\theta\). 

Failed to invert an intrafirm Jacobian of shares with respect to prices when computing \(\eta\). 

Failed to invert an estimated covariance matrix of linear parameters. 

Failed to invert an estimated covariance matrix of GMM parameters. 

Failed to invert an estimated covariance matrix of GMM moments. 