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