pyRVtest.build_ownership

pyRVtest.build_ownership(product_data, firm_ids_column_name, 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}\).

Note

This function is a copy of the function from PyBLP, with a slight change. In order to allow upstream and downstream firms to have different ownership structures, the user can pass in the names of the columns corresponding to firm ids for downstream and upstream firms.

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_column_name (column in product_data with firm 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 identity 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