# 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](https://github.com/tidy-finance/py-tidyfinance), so there is no loader to hand-roll.

```python
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
{class}`~numeraire.core.data.TimeSeriesView` plus a `data_vintage` stamp, importing numeraire lazily
(install the `[numeraire]` extra):

```python
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.

```python
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 {doc}`api` 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
{doc}`data-zones-design`.