Metadata-Version: 2.4
Name: numeraire-dataset
Version: 0.1.0
Summary: Open data builders for numeraire: fetch + clean public and WRDS-sourced data into tidy, point-in-time tables.
Project-URL: Homepage, https://github.com/py-numeraire/numeraire-dataset
Project-URL: Repository, https://github.com/py-numeraire/numeraire-dataset
Project-URL: Issues, https://github.com/py-numeraire/numeraire-dataset/issues
Project-URL: Changelog, https://github.com/py-numeraire/numeraire-dataset/blob/main/CHANGELOG.md
Author-email: Yuheng Wu <wuyuheng20074@live.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: asset-pricing,fred-md,macro,point-in-time,real-time-data,vintage
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: pyarrow>=15
Requires-Dist: tidyfinance>=0.3
Provides-Extra: dev
Requires-Dist: basedpyright>=1.18; extra == 'dev'
Requires-Dist: numeraire<0.3,>=0.2; extra == 'dev'
Requires-Dist: pandas-stubs>=2.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: numeraire
Requires-Dist: numeraire<0.3,>=0.2; extra == 'numeraire'
Provides-Extra: wrds
Requires-Dist: wrds>=3.2; extra == 'wrds'
Description-Content-Type: text/markdown

# numeraire-dataset

Open, reproducible **data loaders + builders** for
[`numeraire`](https://github.com/py-numeraire/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.

## Install

```bash
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**](https://github.com/tidy-finance/py-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

| Builder | Source | License of output | Status |
|---|---|---|---|
| `fredmd` | FRED-MD monthly vintages (St. Louis Fed, McCracken-Ng) | public (cite McCracken-Ng 2016) | in progress |
| `famafrench` | Ken French Data Library | public (cite, carry copyright notice) | planned |
| `zones.wrds` | CRSP / Compustat panels (your WRDS account) | **not redistributable** — local only | implemented |

## Usage

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

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