pyblp.build_ownership¶

pyblp.build_ownership(product_data, kappa_specification=None)

Build ownership matrices, $$O$$.

Ownership or product holding matrices are defined by their cooperation matrix counterparts, $$\kappa$$. For each market $$t$$, $$\mathscr{H}_{jk} = \kappa_{fg}$$ where $$j \in J_{ft}$$, the set of products produced by firm $$f$$ in the market, and similarly, $$g \in J_{gt}$$.

Parameters
• product_data (structured array-like) –

Each row corresponds to a product. Markets can have differing numbers of products. The following fields are required (except for firm_ids when kappa_specification is one of the special cases):

• market_ids : (object) - IDs that associate products with markets.

• firm_ids : (object) - IDs that associate products with firms. This field is ignored if kappa_specification is one of the special cases and not a function.

• kappa_specification (str or callable, optional) –

Specification for each market’s cooperation matrix, $$\kappa$$, which can either be a general function or a string that implements a special case. The general function is is of the following form:

kappa(f, g) -> value


where value is $$\mathscr{H}_{jk}$$ and both f and g are firm IDs from the firm_ids field of product_data.

The default specification, lambda: f, g: int(f == g), constructs traditional ownership matrices. That is, $$\kappa = I$$, the identify matrix, implies that $$\mathscr{H}_{jk}$$ is $$1$$ if the same firm produces products $$j$$ and $$k$$, and is $$0$$ otherwise.

If firm_ids happen to be indices for an actual $$\kappa$$ matrix, lambda f, g: kappa[f, g] will build ownership matrices according to the matrix kappa.

When one of the special cases is specified, firm_ids in product_data are not required and if specified will be ignored:

• 'monopoly' - Monopoly ownership matrices are all ones: $$\mathscr{H}_{jk} = 1$$ for all $$j$$ and $$k$$.

• 'single' - Single product firm ownership matrices are identity matrices: $$\mathscr{H}_{jk} = 1$$ if $$j = k$$ and $$0$$ otherwise.

Returns

Stacked $$J_t \times J_t$$ ownership matrices, $$\mathscr{H}$$, for each market $$t$$. If a market has fewer products than others, extra columns will contain numpy.nan.

Return type

ndarray

Examples