pyblp.Simulation¶

class
pyblp.
Simulation
(product_formulations, product_data, beta, sigma=None, pi=None, gamma=None, rho=None, agent_formulation=None, agent_data=None, integration=None, xi=None, omega=None, xi_variance=1, omega_variance=1, correlation=0.9, distributions=None, epsilon_scale=1.0, costs_type='linear', seed=None)¶ Simulation of data in BLPtype models.
Any data left unspecified are simulated during initialization. Simulated prices and shares can be replaced by
Simulation.replace_endogenous()
with equilibrium values that are consistent with true parameters. Less commonly, simulated exogenous variables can be replaced instead bySimulation.replace_exogenous()
. To choose your own prices, refer to the first note inSimulation.replace_endogenous()
. Simulations are typically used for two purposes:Solving for equilibrium prices and shares under more complicated counterfactuals than is possible with
ProblemResults.compute_prices()
andProblemResults.compute_shares()
. For example, this class can be initialized with estimated parameters, structural errors, and marginal costs from aProblemResults()
, but with changed data (fewer products, new products, different characteristics, etc.) andSimulation.replace_endogenous()
can be used to compute the corresponding prices and shares.Simulation of BLPtype models from scratch. For example, a model with fixed true parameters can be simulated many times, converted into problems with
SimulationResults.to_problem()
, and solved withProblem.solve()
to evaluate in a Monte Carlo study how well the true parameters can be recovered.
If data for variables (used to formulate product characteristics in \(X_1\), \(X_2\), and \(X_3\), as well as agent demographics, \(d\), and endogenous prices and market shares \(p\) and \(s\)) are not provided, the values for each unspecified variable are drawn independently from the standard uniform distribution. In each market \(t\), market shares are divided by the number of products in the market \(J_t\). Typically,
Simulation.replace_endogenous()
is used to replace prices and shares with equilibrium values that are consistent with true parameters.If data for unobserved demandand supplyside product characteristics, \(\xi\) and \(\omega\), are not provided, they are by default drawn from a meanzero bivariate normal distribution.
After variables are loaded or simulated, any unspecified integration nodes and weights, \(\nu\) and \(w\), are constructed according to a specified
Integration
configuration. Parameters
product_formulations (Formulation or sequence of Formulation) –
Formulation
configuration or a sequence of up to threeFormulation
configurations for the matrix of demandside linear product characteristics, \(X_1\), for the matrix of demandside nonlinear product characteristics, \(X_2\), and for the matrix of supplyside characteristics, \(X_3\), respectively. If the formulation for \(X_2\) is not specified or isNone
, the logit (or nested logit) model will be simulated.The
shares
variable should not be included in the formulations for \(X_1\) or \(X_2\). Ifshares
is included in the formulation for \(X_3\), care should be taken when solving for equilibrium prices in, for example,Simulation.replace_endogenous()
, since this routine assumes that marginal costs remain constant.The
prices
variable should not be included in the formulation for \(X_3\), but it should be included in the formulation for \(X_1\) or \(X_2\) (or both). Variables that cannot be loaded fromproduct_data
will be drawn from independent standard uniform distributions. Unlike inProblem
, fixed effect absorption is not supported during simulation.Warning
Characteristics that involve prices, \(p\), or shares, \(s\), should always be formulated with the
prices
andshares
variables, respectively. If another name is used,Simulation
will not understand that the characteristic is endogenous. For example, to include a \(p^2\) characteristic, includeI(prices**2)
in a formula instead of manually constructing and including aprices_squared
variable.product_data (structured arraylike) –
Each row corresponds to a product. Markets can have differing numbers of products. The convenience function
build_id_data()
can be used to construct the following required ID data:market_ids : (object)  IDs that associate products with markets.
firm_ids : (object)  IDs that associate products with firms.
Custom ownership matrices can be specified as well:
ownership : (numeric, optional)  Custom stacked \(J_t \times J_t\) ownership or product holding matrices, \(\mathscr{H}\), for each market \(t\), which can be built with
build_ownership()
. By default, standard ownership matrices are built only when they are needed to reduce memory usage. If specified, there should be as many columns as there are products in the market with the most products. Rightmost columns in markets with fewer products will be ignored.
Note
The
ownership
field can either be a matrix or can be broken up into multiple onedimensional fields with column index suffixes that start at zero. For example, if there are three products in each market, aownership
field with three columns can be replaced by three onedimensional fields:ownership0
,ownership1
, andownership2
.To use certain types of micro moments, product IDs must be specified:
product_ids (object, optional)  IDs that identify individual products within markets. The IDs referenced by
DemographicExpectationMoment
orDiversionProbabilityMoment
must be unique within the relevant markets.
To simulate a nested logit or random coefficients nested logit (RCNL) model, nesting groups must be specified:
nesting_ids (object, optional)  IDs that associate products with nesting groups. When these IDs are specified,
rho
must be specified as well.
Along with
market_ids
,firm_ids
,product_ids
, andnesting_ids
, the names of any additional fields can typically be used as variables inproduct_formulations
. However, there are a few variable names such as'X1'
, which are reserved for use byProducts
.beta (arraylike) – Vector of demandside linear parameters, \(\beta\). Elements correspond to columns in \(X_1\), which is formulated by
product_formulations
.sigma (arraylike, optional) – Lowertriangular Cholesky root of the covariance matrix for unobserved taste heterogeneity, \(\Sigma\). Rows and columns correspond to columns in \(X_2\), which is formulated by
product_formulations
. If \(X_2\) is not formulated, this should not be specified, since the logit model will be simulated.pi (arraylike, optional) – Parameters that measure how agent tastes vary with demographics, \(\Pi\). Rows correspond to the same product characteristics as in
sigma
. Columns correspond to columns in \(d\), which is formulated byagent_formulation
. If \(d\) is not formulated, this should not be specified.gamma (arraylike, optional) – Vector of supplyside linear parameters, \(\gamma\). Elements correspond to columns in \(X_3\), which is formulated by
product_formulations
. If \(X_3\) is not formulated, this should not be specified.rho (arraylike, optional) – Parameters that measure within nesting group correlation, \(\rho\). If this is a scalar, it corresponds to all groups defined by the
nesting_ids
field ofproduct_data
. If this is a vector, it must have \(H\) elements, one for each nesting group. Elements correspond to group IDs in the sorted order ofSimulation.unique_nesting_ids
. If nesting IDs are not specified, this should not be specified either.agent_formulation (Formulation, optional) –
Formulation
configuration for the matrix of observed agent characteristics called demographics, \(d\), which will only be included in the model if this formulation is specified. Any variables that cannot be loaded fromagent_data
will be drawn from independent standard uniform distributions.agent_data (structured arraylike, optional) –
Each row corresponds to an agent. Markets can have differing numbers of agents. Since simulated agents are only used if there are demandside nonlinear product characteristics, agent data should only be specified if \(X_2\) is formulated in
product_formulations
. If agent data are specified, market IDs are required:market_ids : (object, optional)  IDs that associate agents with markets. The set of distinct IDs should be the same as the set in
product_data
. Ifintegration
is specified, there must be at least as many rows in each market as the number of nodes and weights that are built for the market.
If
integration
is not specified, the following fields are required:weights : (numeric, optional)  Integration weights, \(w\), for integration over agent choice probabilities.
nodes : (numeric, optional)  Unobserved agent characteristics called integration nodes, \(\nu\). If there are more than \(K_2\) columns (the number of demandside nonlinear product characteristics), only the first \(K_2\) will be used. If any columns of
sigma
are fixed at zero, only the first few columns of these nodes will be used.
The convenience function
build_integration()
can be useful when constructing custom nodes and weights.Note
If
nodes
has multiple columns, it can be specified as a matrix or broken up into multiple onedimensional fields with column index suffixes that start at zero. For example, if there are three columns of nodes, anodes
field with three columns can be replaced by three onedimensional fields:nodes0
,nodes1
, andnodes2
.To use certain types of micro moments, agent IDs must be specified:
agent_ids (object, optional)  IDs that identify individual agents within markets. There can be multiple of the same ID within a market.
Along with
market_ids
andagent_ids
, the names of any additional fields can typically be used as variables inagent_formulation
. The exception is the name'demographics'
, which is reserved for use byAgents
.integration (Integration, optional) –
Integration
configuration for how to build nodes and weights for integration over agent choice probabilities, which will replace anynodes
andweights
fields inagent_data
. This configuration is required ifnodes
andweights
inagent_data
are not specified. It should not be specified if \(X_2\) is not formulated inproduct_formulations
.If this configuration is specified, \(K_2\) columns of nodes (the number of demandside nonlinear product characteristics) will be built. However, if
sigma
is left unspecified or is specified with columns fixed at zero, fewer columns will be used.xi (arraylike, optional) – Unobserved demandside product characteristics, \(\xi\). By default, if \(X_3\) is formulated, each pair of unobserved characteristics in this vector and \(\omega\) is drawn from a meanzero bivariate normal distribution. This must be specified if \(X_3\) is not formulated or if
omega
is specified.omega (arraylike, optional) – Unobserved supplyside product characteristics, \(\omega\). By default, if \(X_3\) is formulated, each pair of unobserved characteristics in this vector and \(\xi\) is drawn from a meanzero bivariate normal distribution. This must be specified if \(X_3\) is formulated and
xi
is specified. It is ignored if \(X_3\) is not formulated.xi_variance (float, optional) – Variance of \(\xi\). The default value is
1.0
. This is ignored ifxi
oromega
is specified.omega_variance (float, optional) – Variance of \(\omega\). The default value is
1.0
. This is ignored ifxi
oromega
is specified.correlation (float, optional) – Correlation between \(\xi\) and \(\omega\). The default value is
0.9
. This is ignored ifxi
oromega
is specified.distributions (sequence of str, optional) –
Random coefficient distributions. By default, random coefficients in (3) are assumed to be normally distributed. Nondefault distributions can be specified with a list of the following supported strings:
'normal'
(default)  The random coefficient is assumed to be normal.'lognormal'
 The random coefficient is assumed to be lognormal. The coefficient’s column in (3) is exponentiated before being premultiplied by \(X_2\).
The list should have as many strings as there are columns in \(X_2\). Each string determines the distribution of the random coefficient on the corresponding product characteristic in \(X_2\).
A typical example of a lognormal coefficient is one on prices. Implementing this typically involves having a
I(prices)
in the formulation for \(X_2\), and instead of includingprices
in \(X_1\), including a1
in theagent_formulation
. Then the corresponding coefficient in \(\Pi\) will serve as the mean parameter for the lognormal random coefficient on negative prices, \(p_{jt}\).epsilon_scale (float, optional) –
Factor by which the Type I Extreme Value idiosyncratic preference term, \(\epsilon_{ijt}\), is scaled. By default, \(\epsilon_{ijt}\) is not scaled. The typical use of this parameter is to approximate the pure characteristics model of Berry and Pakes (2007) by choosing a value smaller than
1.0
. As this scaling factor approaches zero, the model approaches the pure characteristics model in which there is no idiosyncratic preference term.For more information about choosing this parameter and estimating models where it is smaller than
1.0
, refer to the same argument inProblem.solve()
. In some situations, it may be easier to solve simulations with small epsilon scaling factors by usingSimulation.replace_exogenous()
rather thanSimulation.replace_endogenous()
.costs_type (str, optional) –
Specification of the marginal cost function \(\tilde{c} = f(c)\) in (9). The following specifications are supported:
'linear'
(default)  Linear specification: \(\tilde{c} = c\).'log'
 Loglinear specification: \(\tilde{c} = \log c\).
seed (int, optional) – Passed to
numpy.random.RandomState
to seed the random number generator before data are simulated. By default, a seed is not passed to the random number generator.

product_formulations
¶ Formulation
configurations for \(X_1\), \(X_2\), and \(X_3\), respectively. Type
tuple

agent_formulation
¶ Formulation
configuration for \(d\). Type
tuple

product_data
¶ Synthetic product data that were loaded or simulated during initialization. Typically,
Simulation.replace_endogenous()
is used replace prices and shares with equilibrium values that are consistent with true parameters. Thedata_to_dict()
function can be used to convert this into a more usable data type. Type
recarray

agent_data
¶ Synthetic agent data that were loaded or simulated during initialization. The
data_to_dict()
function can be used to convert this into a more usable data type. Type
recarray

integration
¶ Integration
configuration for how any nodes and weights were built during initialization. Type
Integration

products
¶ Product data structured as
Products
, which consists of data taken fromSimulation.product_data
along with matrices build according toSimulation.product_formulations
. Thedata_to_dict()
function can be used to convert this into a more usable data type. Type
Products

agents
¶ Agent data structured as
Agents
, which consists of data taken fromSimulation.agent_data
or built bySimulation.integration
along with any demographics formulated bySimulation.agent_formulation
. Thedata_to_dict()
function can be used to convert this into a more usable data type. Type
Agents

unique_market_ids
¶ Unique market IDs in product and agent data.
 Type
ndarray

unique_firm_ids
¶ Unique firm IDs in product data.
 Type
ndarray

unique_nesting_ids
¶ Unique nesting IDs in product data.
 Type
ndarray

unique_product_ids
¶ Unique product IDs in product data.
 Type
ndarray

unique_agent_ids
¶ Unique agent IDs in agent data.
 Type
ndarray

beta
¶ Demandside linear parameters, \(\beta\).
 Type
ndarray

sigma
¶ Cholesky root of the covariance matrix for unobserved taste heterogeneity, \(\Sigma\).
 Type
ndarray

gamma
¶ Supplyside linear parameters, \(\gamma\).
 Type
ndarray

pi
¶ Parameters that measures how agent tastes vary with demographics, \(\Pi\).
 Type
ndarray

rho
¶ Parameters that measure within nesting group correlation, \(\rho\).
 Type
ndarray

xi
¶ Unobserved demandside product characteristics, \(\xi\).
 Type
ndarray

omega
¶ Unobserved supplyside product characteristics, \(\omega\).
 Type
ndarray

distributions
¶ Random coefficient distributions.
 Type
list of str

epsilon_scale
¶ Factor by which the Type I Extreme Value idiosyncratic preference term, \(\epsilon_{ijt}\), is scaled.
 Type
float

costs_type
¶ Functional form of the marginal cost function \(\tilde{c} = f(c)\).
 Type
str

T
¶ Number of markets, \(T\).
 Type
int

N
¶ Number of products across all markets, \(N\).
 Type
int

F
¶ Number of firms across all markets, \(F\).
 Type
int

I
¶ Number of agents across all markets, \(I\).
 Type
int

K1
¶ Number of demandside linear product characteristics, \(K_1\).
 Type
int

K2
¶ Number of demandside nonlinear product characteristics, \(K_2\).
 Type
int

K3
¶ Number of supplyside characteristics, \(K_3\).
 Type
int

D
¶ Number of demographic variables, \(D\).
 Type
int

MD
¶ Number of demandside instruments, \(M_D\), which is always zero because instruments are added or constructed in
SimulationResults.to_problem()
. Type
int

MS
¶ Number of supplyside instruments, \(M_S\), which is always zero because instruments are added or constructed in
SimulationResults.to_problem()
. Type
int

ED
¶ Number of absorbed dimensions of demandside fixed effects, \(E_D\), which is always zero because simulations do not support fixed effect absorption.
 Type
int

ES
¶ Number of absorbed dimensions of supplyside fixed effects, \(E_S\), which is always zero because simulations do not support fixed effect absorption.
 Type
int

H
¶ Number of nesting groups, \(H\).
 Type
int
Examples
Methods
replace_endogenous
([costs, prices, …])Replace simulated prices and market shares with equilibrium values that are consistent with true parameters.
replace_exogenous
(X1_name[, X3_name, delta, …])Replace exogenous product characteristics with values that are consistent with true parameters.