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