Skip to content

XBRL acquirer to Revelio mapping

This builder creates a reviewable mapping from XBRL goodwill acquirers to Revelio parent firms. The reported XBRL cik and company_name jointly define the source identity, so historical issuer names are retained rather than collapsed into an arbitrary one-per-CIK crosswalk.

flowchart LR
    xbrl[(XBRL goodwill deals)]
    ref[(Revelio company reference)]
    builder[Acquirer mapping builder]
    output[(XBRL acquirer–Revelio candidates)]

    xbrl --> builder
    ref --> builder
    builder --> output

    classDef input fill:#e8eef7,stroke:#52739e,stroke-width:2px
    classDef process fill:#fff0d8,stroke:#b7791f,stroke-width:2px
    classDef reusable fill:#e2f2e7,stroke:#3b7a4b,stroke-width:2px
    class xbrl,ref input
    class builder process
    class output reusable
Inputs
Input Location Grain Required fields
Current clean XBRL deal panel /data/full/processed/raw/xbrl_deals.parquet Issuer × reported target cik, company_name, has_goodwill; only goodwill-bearing rows contribute identities
Legacy goodwill extract /data/xbrl_goodwill/goodwill_xbrl_20102022.csv Curated target-deal row cik, company_name, value; rows with nonmissing value contribute legacy identities
Revelio company reference /data/revelio/revelio_individual_company_ref.parquet Revelio parent-company record rcid, company, primary_name, cik

The builder unions issuer identities from the current panel and legacy extract, then aggregates source counts and year ranges by (cik, company_name). The legacy CSV supplements mapping coverage; it is not the source of current Table 9 regression rows. The current panel's date range comes from the staged 10-K/10-Q Parquets, not the legacy filename.

Build
Component Location Purpose
Builder shared/data/build_mapping_xbrl_acquirers_revelio.py Retains CIK candidates, resolves shared CIKs with reported names, and adds conservative name fallbacks when a CIK is absent
Runtime dependency rapidfuzz in the model image Scores parent-name fuzzy candidates for CIKs absent from Revelio
Execution mode Direct Python only No Slurm wrapper is provided for this one-time mapping build
Output
Dataset Location Grain Selection contract
XBRL acquirer–Revelio candidate mapping /data/full/processed/mapping_xbrl_acquirers_revelio.parquet Reported cik × company_name identity × Revelio parent candidate Filter is_selected = true for at most one chosen RCID per source identity; unresolved identities remain unmatched

Matching contract

The builder uses the CIK as primary evidence. If that CIK belongs to one Revelio parent RCID, it is selected as cik_selected, even when the issuer has subsequently changed its name. When a CIK belongs to multiple Revelio parent RCIDs, every candidate remains in the output and the reported XBRL company name is compared to the reference parent names. The leading candidate is selected as cik_disambiguated only with an original-name score of at least 95 and a lead of at least 5 points; otherwise the CIK remains cik_ambiguous.

For XBRL identities whose CIK has no Revelio candidate, the builder considers only parent primary_name and company aliases. A unique normalized exact name is selected; multiple exact matches require the same conservative raw-name tie-break. Otherwise it searches a prefix- and length-bounded parent-name fuzzy candidate set. Fuzzy selection requires a score of at least 90 and a lead of at least 5, with the same high-confidence raw-name tie-break available for close fuzzy ties. It never uses child-company aliases: the acquirer CIK is the SEC filing registrant, not an acquired subsidiary.

The full Parquet is an audit table. Important fields are acquirer_label_id, acquirer_cik, company_name, source-year/deal counts, candidate identifiers, reference fields, match_method, match_status, similarity scores, and is_selected. An unresolved identity has one null-candidate row. The selected subset is one-to-zero-or-one at the source-identity level; separate historical names can legitimately map to the same Revelio RCID.

Selected mapping for joins

Filter to selected candidates and merge on both source fields. Keeping the matching-status and score fields makes later analysis auditable.

WITH selected_acquirers AS (
    SELECT
        acquirer_cik AS cik,
        company_name,
        candidate_rcid AS acquirer_rcid,
        match_status AS acquirer_match_status,
        raw_name_score,
        raw_name_margin,
        fuzzy_score,
        fuzzy_margin
    FROM read_parquet('/data/full/processed/mapping_xbrl_acquirers_revelio.parquet')
    WHERE is_selected = true
)
SELECT
    deals.*,
    acquirers.acquirer_rcid,
    acquirers.acquirer_match_status,
    acquirers.raw_name_score,
    acquirers.raw_name_margin,
    acquirers.fuzzy_score,
    acquirers.fuzzy_margin
FROM read_parquet('/data/full/processed/raw/xbrl_deals.parquet') AS deals
LEFT JOIN selected_acquirers AS acquirers
    ON deals.cik = acquirers.cik
   AND deals.company_name = acquirers.company_name
WHERE deals.has_goodwill = true;

Command reference

python -m shared.data.build_mapping_xbrl_acquirers_revelio
Argument Default Description
--fuzzy-candidate-limit INT 5 Number of fuzzy parent-name alias keys retained before RCID-level collapsing; must be at least 2
--overwrite off Explicitly replace an existing output file

The XBRL source, Revelio reference, and output paths are intentionally not command-line options. They are the project-wide data.* paths in shared/config/config_full.yaml.

No Slurm entry point is supplied for this one-time mapping builder. Run the direct command in the model environment, where rapidfuzz is installed.