numeraire_dataset.load_hkm_paper_data

numeraire_dataset.load_hkm_paper_data(*, frequency: Literal['quarterly', 'monthly'] = 'quarterly', path: str | Path | None = None, timeout: float = 30.0) → HKMPaperData

Load the fixed He–Kelly–Manela paper factors and 124 test assets.

With path=None, the one official author ZIP is downloaded into memory. Passing path instead reads a caller-supplied local .zip through a POSIX dir_fd/O_NOFOLLOW traversal that fails closed on unsupported platforms. Both routes require the frozen official archive SHA-256 before parsing. No ZIP, CSV, README, or bundled Julia bytes are extracted, copied, cached, executed, or persisted.

Only the original-paper quarterly or monthly test-asset file is exposed. The archive’s updated daily/monthly/quarterly factor-only files are schema/calendar validated but deliberately have no public selection route, preventing their 2013–2018 extension from being mixed into the paper’s 1970Q1–2012Q4 cross-sectional sample.

factors uses decimal units and canonical mkt_excess / risk_free labels. excess_returns contains the 124 distinct official assets after subtracting same-period RF; its cross-class missingness is preserved. The redundant source All_01–All_124 block must exactly duplicate those assets cell-for-cell and is then omitted. asset_metadata maps every asset to its class, within-class position, and duplicate All source column. HKMPaperData.complete_case() performs complete-case selection within one asset class, never across the unbalanced 124-asset panel.

All three frames carry path-free frame_provenance() with archive/member hashes, recipe, rows, units, source mode, and redistributable=false. The author’s page permits free non-commercial use and provides the files as-is, but states no general redistribution grant; the test assets also retain their original third-party source obligations.