numeraire-dataset

Open, reproducible data loaders + builders for numeraire. This package ships code, not data: it fetches public (and, with your own WRDS credentials, licensed) sources and cleans them into tidy, point-in-time tables that numeraire consumes. Part of the numeraire ecosystem.

Install

pip install numeraire-dataset               # frame loaders + builders (tidyfinance backend)
pip install "numeraire-dataset[numeraire]"  # + the point-in-time view helpers (numeraire bridge)
pip install "numeraire-dataset[wrds]"       # + live CRSP/Compustat pulls (your own WRDS account)

Two layers

• sources — tidyfinance (MIT) is the primary backend for standard sources (Fama-French, Goyal-Welch, FRED, JKP, q-factors, OSAP). Thin loaders return tidy frames (+ an optional point-in-time view helper) with data_vintage provenance — no loader hand-rolling.
• builders — self-built ETL for what tidyfinance does not cover: vintage-aware FRED-MD (reference period × vintage × series, tcodes applied at build time) and, with your own credentials, WRDS panels. (The FRED-MD vintage/tcode design is a candidate to upstream into tidyfinance — once merged, its sources path could replace the local builder.)

Why a separate project

numeraire (the framework) bundles only tiny public example slices. Anything that needs to be downloaded, merged across releases, or built from a subscription source lives here, as transparent open-source ETL — so the cleaning is auditable and re-runnable, and no licensed data is ever redistributed inside a wheel. Build outputs land in a local cache (git-ignored), never the repo.

Design: build once, read clean

raw vendor files  ──build (this package)──▶  tidy point-in-time table  ──read──▶  numeraire
   (download)            clean / tcode                [reference period × vintage × series]

• The vintage axis is a column. Each value carries the reference period it describes and the vintage (data release) it came from, so revisions are first-class and asof is leak-safe.
• Stationarity transforms (FRED-MD tcodes) are applied at build time, per vintage — never inside numeraire's main pipeline. transform=False keeps raw levels.
• Availability lag (L) is NOT baked in. It stays a read-time parameter in numeraire, so you can sweep it for robustness. The table stores only (reference period, vintage, series…).

Builders

Usage

# Standard sources via tidyfinance (frames; + a view helper with the `numeraire` extra):
from numeraire_dataset import load_ff_factors, load_gw_view

ff = load_ff_factors()                       # date, mkt_excess, smb, hml, risk_free  (decimals)
view, vintage = load_gw_view(start_date="1926-07-01", end_date="2020-12-31")
# → feed `view` straight into numeraire's backtest_forecast; `vintage` is the provenance stamp.

# Vintage-aware FRED-MD (what tidyfinance lacks) via the local builder:
from numeraire_dataset.builders import fredmd

paths = fredmd.download(vintages=["2025-01", "2025-02", "2025-03"], dest="~/.numeraire_data")
table = fredmd.build_table(paths, transform=True)   # tidy [reference, vintage, series…]

Frame loaders vs. *_view helpers

The split is intentional, not an oversight. Frame loaders (load_ff_factors, load_goyal_welch) return plain tidy pandas frames and carry no numeraire dependency, so they are usable on their own. The *_view helpers (load_gw_view, zones.view) add the optional bridge into a numeraire view plus a data_vintage stamp, and only import numeraire lazily (install the [numeraire] extra). A frame loader is therefore a strict subset of the work a view helper does — the names differ because their return contracts and dependency footprints differ, and both are kept rather than collapsed into one signature.

Citation

numeraire-dataset is a companion to numeraire. If you use the ecosystem in your research, please cite numeraire — see How to cite.

License: BSD-3-Clause (code). Source datasets keep their own terms — see each builder's docstring.