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¶
| 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.