Skip to content

XBRL target to Revelio mapping

This builder creates a reviewable candidate mapping from the target labels in XBRL goodwill disclosures to Revelio firms. It does not map acquirers or compute match quality. Rather than silently forcing uncertain records to a single firm, the output retains every exact or fuzzy candidate and marks only high-confidence, unambiguous matches as selected.

flowchart LR
    xbrl[(XBRL goodwill deals)]
    ref[(Revelio company reference)]
    builder[Target mapping builder]
    output[(XBRL target–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 target_firm, has_goodwill; only rows with goodwill contribute labels
Legacy goodwill extract /data/xbrl_goodwill/goodwill_xbrl_20102022.csv Curated target-deal row target_firm, value; rows with nonmissing value contribute legacy labels
Revelio company reference /data/revelio/revelio_individual_company_ref.parquet Revelio parent-company record, optionally with a child-company record rcid, company, primary_name, child_rcid, child_company

The builder unions target labels from the current panel and the legacy extract, then aggregates source counts and year ranges by raw target_firm. The legacy CSV supplements mapping coverage; it does not define the current M&A regression sample. The current panel's date range is determined by the staged 10-K/10-Q Parquets, not by the legacy filename.

Build
Component Location Purpose
Builder shared/data/build_mapping_xbrl_targets_revelio.py Normalizes target labels, creates parent and child aliases, and writes all candidate matches
Runtime dependency rapidfuzz in the model image Scores prefix-blocked fuzzy candidates
Execution mode Direct Python only No Slurm wrapper is currently provided because this is a one-time mapping build
Output
Dataset Location Grain Selection contract
XBRL target–Revelio candidate mapping /data/full/processed/mapping_xbrl_targets_revelio.parquet Reported target label × Revelio candidate; one null-candidate row for labels with none Filter is_selected = true for at most one chosen RCID per raw target label; unresolved labels remain unmatched

Matching contract

The builder reduces punctuation, spacing, CamelCase boundaries, and common legal suffixes to form a matching key. It indexes the reference's primary_name, company, and child_company aliases. A child-company alias selects child_rcid when available and otherwise falls back to its parent's rcid; the source parent and child identifiers remain in the output for review.

Exact candidates are collapsed to one preferred alias per target label and candidate RCID, giving child aliases priority on a tie. A unique exact candidate is selected automatically. For multiple exact candidates, the builder compares the original XBRL label with each retained candidate alias after normalizing only capitalization, CamelCase, punctuation, and spacing; legal suffixes remain informative. The top candidate is selected as exact_disambiguated only when its raw-name score is at least 95 and exceeds the second candidate by at least 5 points. Other cases remain exact_ambiguous for review.

For labels without an exact candidate, rapidfuzz compares the normalized key against aliases in the same three-character prefix block and a proportional length band. The default top candidate is selected only when its score is at least 90 and its lead over the second-best candidate is at least 5. Every returned fuzzy candidate stays in the file, including ambiguous and below-threshold cases. Labels without any candidate receive a null-candidate row. The XBRL source's dup indicator is carried as source_dup_rows; it is never used to drop records.

For fuzzy candidates whose top score clears 90 but whose fuzzy-score margin is below 5, the builder applies the same conservative original-name tie-break as for ambiguous exact candidates. It marks fuzzy_disambiguated only when the raw-name score is at least 95, the raw-name margin is at least 5, and that candidate itself still has a fuzzy score of at least 90. This does not relax the base fuzzy threshold. raw_name_rank makes a raw-name-selected candidate auditable when it differs from the candidate ranked first by fuzzy score.

Important fields are target_label_id, the raw and normalized target names, candidate identifiers and reference columns, match_method, match_status, raw_name_score, raw_name_margin, fuzzy_score, fuzzy_margin, and is_selected. The source metadata columns summarize the number of deal rows, duplicate-flagged rows, distinct acquirers, and observed years for each raw target label.

Selected mapping for joins

The complete Parquet is a candidate and audit table. For an ordinary merge to Revelio, filter it to is_selected = true and use candidate_rcid as the Revelio rcid. This produces exactly one row per identified raw target_firm label. Keep match_status and the score columns with the merge so downstream work can distinguish direct exact, exact-disambiguated, direct fuzzy, and fuzzy-disambiguated links.

WITH selected_targets AS (
    SELECT
        target_label_id,
        target_firm,
        candidate_rcid AS rcid,
        match_status,
        raw_name_score,
        raw_name_margin,
        fuzzy_score,
        fuzzy_margin
    FROM read_parquet('/data/full/processed/mapping_xbrl_targets_revelio.parquet')
    WHERE is_selected = true
)
SELECT
    deals.*,
    selected_targets.rcid AS target_rcid,
    selected_targets.match_status AS target_match_status,
    selected_targets.raw_name_score,
    selected_targets.raw_name_margin,
    selected_targets.fuzzy_score,
    selected_targets.fuzzy_margin
FROM read_parquet('/data/full/processed/raw/xbrl_deals.parquet') AS deals
LEFT JOIN selected_targets USING (target_firm)
WHERE deals.has_goodwill = true;

The result is a partial functional XBRL-target-label → Revelio-RCID mapping: no target label has more than one selected RCID, but unresolved labels have none. It is not necessarily a bijection in the other direction—distinct reported labels can legitimately resolve to the same Revelio firm. To attach the Revelio reference fields, join target_rcid to revelio_individual_company_ref.rcid after this step.

Command reference

python -m shared.data.build_mapping_xbrl_targets_revelio
Argument Default Description
--fuzzy-min-score FLOAT 90 Minimum top fuzzy similarity score for selection
--fuzzy-min-margin FLOAT 5 Minimum top-minus-second fuzzy-score margin for selection
--fuzzy-candidate-limit INT 5 Number of fuzzy alias keys retained before RCID-level collapsing; must be at least 2
--exact-raw-min-score FLOAT 95 Minimum original-name similarity score for resolving multiple exact candidates
--exact-raw-min-margin FLOAT 5 Minimum top-minus-second original-name score margin for resolving multiple exact candidates
--fuzzy-raw-min-score FLOAT 95 Minimum original-name similarity score for resolving fuzzy-score ties
--fuzzy-raw-min-margin FLOAT 5 Minimum original-name score margin for resolving fuzzy-score ties
--overwrite off Explicitly replace an existing output file

The source, company-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 currently supplied for this one-time mapping builder. Run the direct command in the model environment, where rapidfuzz is installed.