User guide

The package has two layers: sources (tidyfinance-backed loaders for standard data) and builders (self-built ETL for what tidyfinance does not cover). Golden reproductions keep their own pinned fixtures; the loaders here are for convenience, exploration, and building those fixtures.

Sources

The source loaders return tidy pandas frames with a data_vintage provenance stamp. They wrap tidyfinance, so there is no loader to hand-roll.

from numeraire_dataset import load_ff_factors, load_goyal_welch

ff = load_ff_factors()          # date, mkt_excess, smb, hml, risk_free  (decimals)
gw = load_goyal_welch()         # the Goyal–Welch predictor set

Frame loaders vs. view helpers

The split is intentional. Frame loaders (load_ff_factors, load_goyal_welch) return plain tidy frames and carry no numeraire dependency, so they are usable on their own. The view helpers (load_gw_view, to_timeseries_view) add the optional bridge into a numeraire TimeSeriesView plus a data_vintage stamp, importing numeraire lazily (install the [numeraire] extra):

from numeraire_dataset import load_gw_view

view, vintage = load_gw_view(start_date="1926-07-01", end_date="2020-12-31")
# view -> feed straight into numeraire's backtest; vintage -> the provenance string

Builders

Self-built ETL for what tidyfinance does not provide. The flagship is vintage-aware FRED-MD: a real-time macro panel indexed by reference period × vintage × series, with the FRED-MD stationarity transforms (tcodes) applied at build time, per vintage — so revisions are first-class and an asof read is leak-safe.

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…]

transform=False keeps raw levels. The availability lag stays a read-time parameter in numeraire (not baked into the table), so you can sweep it for robustness. See API reference for the full builder surface (download, download_archive, read_vintage, apply_tcode, build_table, build_from_dir).

Data zones (WRDS-scale)

For subscription panels (CRSP / Compustat, via your own WRDS account), the package uses a three-zone raw → clean → view lifecycle that pins preprocessing as tightly as the model, so a result’s data_vintage traces back to exact bytes and an exact transform recipe. The design is described in Data zones: raw → clean → view (design).