Skip to content

Commit af79d37

Browse files
author
Stefan Jansen
committed
docs: add economic and specialized source references
Closes #69.
1 parent 5ddcc21 commit af79d37

13 files changed

Lines changed: 217 additions & 366 deletions

‎docs/getting-started/provider-selection.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,9 @@ data = SyntheticProvider(seed=42).fetch_ohlcv(
2424
| Equity bars | Yahoo Finance, Alpaca, EODHD, Tiingo, Twelve Data, Massive, Finnhub | Some adapters require credentials, accounts, or paid history |
2525
| Foreign exchange | OANDA, Twelve Data, FXMacroData | OANDA and Twelve Data require credentials |
2626
| Futures and options | Databento, Binance, OKX | Historical or licensed data may be metered |
27-
| Macroeconomic series | FRED, FXMacroData | FRED requires an API key for normal use |
28-
| Research factors | Fama-French, AQR | Network access and source-specific terms |
29-
| Prediction markets | Kalshi, Polymarket | Network access and changing public endpoints |
27+
| [Macroeconomic series](../providers/macro.md) | FRED, FXMacroData | FRED requires an API key for normal use |
28+
| [Research factors](../providers/factors.md) | Fama-French, AQR | Network access and source-specific terms |
29+
| [Prediction markets](../providers/prediction_markets.md) | Kalshi, Polymarket | Network access and changing public endpoints |
3030
| Frozen equity history | Wiki Prices | Local historical dataset ending in 2018 |
3131
| CFTC positioning | COT | Install the `cot` extra |
3232

‎docs/providers/alternative_data.md‎

Lines changed: 39 additions & 204 deletions
Large diffs are not rendered by default.

‎docs/providers/etfs.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,5 @@ the current ticker.
2727
## Related References
2828

2929
- [Equity data sources](equities.md)
30+
- [Fixed-income data sources](fixed_income.md)
3031
- [Market data selection](market_data.md)

‎docs/providers/factors.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Research Factor Data Sources
2+
3+
Factor libraries publish returns from research portfolios, not returns from investable products.
4+
Choose a source by universe, formation method, weighting, frequency, and revision policy. Do not
5+
combine similarly named factors without reconciling their construction.
6+
7+
!!! note "Verified September 2026"
8+
This category has enough distinct, maintained sources for a standalone reference. Entries were
9+
checked against the linked official or author-maintained data page.
10+
11+
| Source and product | Coverage or history | Acquisition | Access | Material research caveat | ml4t-data provider |
12+
|--------------------|---------------------|-------------|--------|--------------------------|--------------------|
13+
| [Kenneth French Data Library](https://mba.tuck.dartmouth.edu/pages/faculty/ken.french/data_library.html) | US and international factors, sorted portfolios, industries, and breakpoints; core US monthly series begin in 1926 | Downloadable ZIP, CSV, and text files | Free | Histories can be reconstructed after upstream CRSP revisions; archive vintages when reproducibility matters | `FamaFrenchProvider` |
14+
| [AQR Data Library](https://www.aqr.com/Insights/Datasets) | Equity and cross-asset value, momentum, quality, low-beta, trend, and long-history research portfolios | Downloadable spreadsheets | Free under dataset terms | Series are hypothetical research portfolios, not AQR product returns; methodology differs by paper | `AQRFactorProvider` |
15+
| [Global Factor Data](https://jkpfactors.com/data) | 153 characteristics across 93 countries and four regions, with portfolio sorts and reference files | Configurable file downloads; stock-level data through WRDS | Factor returns free under CC BY-NC 4.0; stock-level access requires WRDS | Noncommercial data license and global data-screening choices constrain reuse and comparison | No |
16+
17+
`FamaFrenchProvider.fetch()` selects supported factor, portfolio, industry, international, or
18+
breakpoint datasets. `AQRFactorProvider.download()` acquires the spreadsheets and `fetch()` reads a
19+
supported local dataset. Neither class computes live portfolio returns.
20+
21+
## Selection Notes
22+
23+
- Use Fama-French for canonical academic benchmarks and portfolio sorts.
24+
- Use AQR for paper-specific equity and cross-asset premia such as QMJ, BAB, VME, and TSMOM.
25+
- Use Global Factor Data for broad characteristic definitions and consistent country coverage.
26+
- Store the downloaded file and retrieval date because published research histories may be
27+
revised.

‎docs/providers/fixed_income.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Fixed-Income Data Sources
2+
3+
Fixed-income research combines security reference data, evaluated or traded prices, yields,
4+
cash flows, ratings, and transactions. A yield curve or evaluated price is a model output, while a
5+
TRACE record is an executed trade. Keep those sources distinct.
6+
7+
!!! note "Verified September 2026"
8+
Entries were checked against the linked official product documentation. Coverage and access
9+
depend on the vendor contract and can change.
10+
11+
| Source and product | Coverage or history | Acquisition | Access | Material research caveat | ml4t-data provider |
12+
|--------------------|---------------------|-------------|--------|--------------------------|--------------------|
13+
| [FRED and ALFRED](https://fred.stlouisfed.org/docs/api/fred/) | Treasury yields, credit spreads, policy rates, indexes, and other fixed-income series from contributing agencies | REST API | Free API key | Many series are aggregates or model outputs; use ALFRED vintages when release-time correctness matters | `FREDProvider` |
14+
| [US Treasury Fiscal Data](https://fiscaldata.treasury.gov/api-documentation/) | Marketable debt, interest expense, auction, ownership, and related fiscal datasets | REST API and downloadable files | Free | Fiscal series and security records are not secondary-market quotes | No |
15+
| [New York Fed Markets Data](https://www.newyorkfed.org/markets/reference-rates) | SOFR, EFFR, OBFR, repo rates, operations, and related money-market data | Markets Data APIs and downloads | Free | Reference rates are published aggregates with documented revision rules, not executable quotes | No |
16+
| [FINRA Fixed Income and TRACE](https://www.finra.org/finra-data/fixed-income) | Corporate, agency, securitized, and 144A security and trade data | Website, daily files, feeds, and enhanced historical products | Public summaries or licensed subscription | TRACE disseminates executed trades, not quotes; caps, delays, and corrections affect interpretation | No |
17+
| [CRSP US Treasury Database](https://www.crsp.org/research/) | Bills, notes, bonds, and fixed-term indexes for academic research | Institutional files | Academic or institutional license | CRSP conventions and month-end index calculations differ from live execution data | No |
18+
| [ICE Fixed Income Data](https://www.ice.com/fixed-income-data-services) | Evaluated pricing, reference data, indexes, analytics, and market data across global debt markets | Feeds, APIs, and managed files | Institutional license | Evaluated prices are estimates and methodology, contributor coverage, and redistribution rights are product-specific | No |
19+
20+
For exchange-traded interest-rate and bond futures, use the [futures data reference](futures.md).
21+
For policy rates and economic releases, use the [macroeconomic data reference](macro.md).
22+
23+
## Selection Notes
24+
25+
- Use security-level reference data with dated identifiers, coupons, call schedules, and cash
26+
flows. CUSIPs can change and a current description is not a historical master.
27+
- Avoid treating a stale last trade as a current market price. Corporate bonds can trade
28+
infrequently, and evaluated prices add a pricing model.
29+
- Preserve publication and revision timestamps for curves and macro-derived spreads.

0 commit comments

Comments
 (0)