Three-tier name linkage for Hispanic compound surnames

Replication package for Name-based record linkage for Hispanic compound surnames: a validated three-tier protocol with calibrated abstention (journal destination under evaluation).

The Mexican SNII padrón redistributed here is © SECIHTI, published on datos.gob.mx under CC-BY 4.0 and reduced to the four name fields the benchmark uses.

Contents

• data/renacyt_limpio.csv — canonical name source: Peru's public researcher registry (RENACYT, cut-off 2024-05-30; CONCYTEC open data, ODC-By), cleaned.
• scripts/01_benchmark_sintetico.py — generates the 65,528-case synthetic benchmark (six byline transformations, fixed seed 42) and evaluates the three-tier protocol (v1), the extended protocol (v2), and three baselines.
• scripts/02_analisis_errores.py — abstention mechanism analysis (surname frequency deciles, ambiguous-token ranking, tier usage).
• scripts/03_figures.py / 03b_figures_es.py — manuscript figures (EN / ES), including the threshold-sweep frontiers in Fig. 1.
• scripts/05_barrido_umbrales.py — threshold sweep of the two similarity baselines (Jaccard 0.30–0.70, sequence similarity 0.70–0.95) on the same benchmark sample; single scoring pass, full recall/false-match frontier.
• scripts/06_aplicacion_real.py — application of v1 and v2 to the real corpus (data/openalex_autores_ia.csv): 3,546 Peru-affiliated OpenAlex author profiles in AI, linked against the registry.
• data/openalex_autores_ia.csv — real corpus for script 06 (public OpenAlex author metadata; see the related package below for its provenance).
• scripts/16_baselines_competitivos.py — Jaro–Winkler (Winkler 1990) and Soft-TF-IDF (Cohen et al. 2003), implemented from their definitions with no extra dependencies, on the same comparison sample, plus the full threshold frontier of each.
• scripts/20_fellegi_sunter.py — Fellegi–Sunter (1969) over a five-field comparison vector, fitted twice: by expectation-maximization on the 2,279,500 candidate pairs, and on the known matching as an upper bound. Reports both frontiers and the per-query agreement between the two fits.
• scripts/21_validez_del_banco.py — external validity of the transformation set: shape distribution of the 3,546 real OpenAlex bylines, generator coverage, and the byline shapes it does not produce.
• scripts/22_portabilidad_perfil.py — portability across surname-frequency profiles: two equal-size sub-registries with opposite surname concentration, each its own candidate pool.
• scripts/23_segundo_registro_mx.py — second national registry: Mexico's SNII padrón (SECIHTI, 2nd half of 2025, datos.gob.mx, CC-BY 4.0), run at full scale and at a sub-registry matched in size to the Peruvian roster.
• data/snii_mx_limpio.csv — the SNII padrón reduced to the four fields the benchmark uses (CVU, given names, both surnames); the script rebuilds it from the original download if absent and prints the source URL.
• outputs/ — full per-case results (benchmark_detalle.csv), aggregated metrics, mechanism tables, threshold-sweep frontier (barrido_umbrales.json), real-corpus linkage results (aplicacion_real.json), and figures at 600 dpi.

Reproduce

pip install pandas numpy scipy matplotlib
python scripts/01_benchmark_sintetico.py
python scripts/02_analisis_errores.py
python scripts/05_barrido_umbrales.py
python scripts/06_aplicacion_real.py
python scripts/03_figures.py

Licences

Code: MIT. Derived data and outputs: CC BY 4.0. RENACYT source: ODC-By (CONCYTEC).

Related