getfactormodels 0.0.12

Download datasets for various multifactor asset pricing models.

getfactormodels

A command-line tool to retrieve data for multi-factor asset pricing models.

Models

• The 3-factor, 5-factor, and 6-factor models of Fama & French ^{[1] [3] [4]}
• Mark Carhart's 4-factor model ^[2]
• Pastor and Stambaugh's liquidity factors ^[5]
• Mispricing factors of Stambaugh and Yuan^[6]
• The $q$-factor model of Hou, Mo, Xue and Zhang^[7]
• The augmented $q^5$-factor model of Hou, Mo, Xue and Zhang^[8]
• Intermediary Capital Ratio (ICR) of He, Kelly & Manela^[9]
• The DHS behavioural factors of Daniel, Hirshleifer & Sun^[10]
• The HML $^{DEVIL}$ factor of Asness & Frazzini^[11]
• Betting Against beta, A. Frazzini, L. Pedersen (2014) ^[12]
• Quality Minus Junk, Asness, Frazzini & Pedersen (2017)^[13]
• The 6-factor model of Barillas and Shanken^[14]

Thanks to: Kenneth French, Robert Stambaugh, Lin Sun, Zhiguo He, AQR Capital Management (AQR.com) and Hou, Xue and Zhang (global-q.org), for their research and for the datasets they provide.

Installation

[!IMPORTANT] getfactormodels is pre-alpha (until version 0.1.0), don't rely on it for anything.

But a huge thanks to anyone who has tried it!

Requires:

• Python >=3.10

The easiest way to install getfactormodels is with pip:

pip install getfactormodels

Quick start

CLI

# Fama-French 3-Factor (monthly) starting Jan 2020
getfactormodels -m ff3 -f m -s 2020-01-01 -o my_factors.csv

# ICR factors (daily) data saved to Parquet
getfactormodels -m icr -f d -s 2015-01-01 -o data.parquet

# Fama-French 6-Factor (Europe) with factor dropping
getfactormodels -m ff6 -f m --region europe --drop "RF" -o europe_factors.csv

getfactormodels -m qmj -f -m --country JPN
getfactormodels -m bab -f d -c AUS -s 1990 -o aus_betting-against-beta.ipc

Python

get_factors

import getfactormodels as gfm

m = gfm.get_factors(
    model = 'dhs',
    frequency='m',
    start_date='2000-01-01',
    end_date='2024-12-31',
    output_file='data.csv',
    cache_ttl=86400
)
df = model.data
model.to_file("factors.md")

Model classes

from getfactormodels import FamaFrenchFactors, DHSFactors, BarillasShankenFactors, QFactors

# Fama-French 3-Factors
ff3 = FamaFrenchFactors(model='3', frequency='m', region='developed', start_date='2020-01-01')
ff3.end_date = '2020'
ff3.frequency = 'd'
df_ff3 = ff3.data


# AQR Models for different countries:
qmj_nor = QMJFactors(frequency='m', country='nor')
bab_jpn = BABFactors(frequency='d', country='JPN', start='2000-02-20', end '2010').data
aus_devil = HMLDevil(frequency='m', country='Aus', end='2020').data


# Q Factors have a "classic" boolean, when true, returns the classic 4 factor model.
q = QFactors(classic=True, frequency='w').data

misp = gfm.MispricingFactors(frequency='m')
df = misp.data

A list of model classes available:

• FamaFrenchFactors
• CarhartFactors
• QFactors
• ICRFactors
• DHSFactors
• LiquidityFactors
• MispricingFactors
• HMLDevilFactors
• BarillasShankenFactors
• BABFactors
• QMJFactors

(back to top)

Data Availability

This table shows each model's start date, available frequencies, and the latest datapoint if not current. The id column contains the shortest identifier for each model. These should all work in python and the CLI.

id	Factor Model	Start	D	W	M	Q	Y	End
3	Fama-French 3	1926-07-01	✓	✓	✓		✓	-
4	Carhart 4	1926-11-03	✓		✓		✓	-
5	Fama-French 5	1963-07-01	✓		✓		✓	-
6	Fama-French 6	1963-07-01	✓		✓		✓	-
icr	ICR	1970-01-31 Daily: 1999-05-03	✓		✓	✓		2025-06-27
dhs	DHS	1972-07-03	✓		✓			2023-12-29
mis	Mispricing	1963-01-02	✓		✓			2016-12-30
liq	Liquidity	1962-08-31			✓			2024-12-31
q q4	$q^5$-factors $q$-factors	1967-01-03	✓	✓	✓	$\checkmark$	✓	2024-12-31
bs	Barillas-Shanken 6	1967-01-03	✓		✓			2024-12-31
hmld	HML $^{DEVIL}$	1926-07-01	✓		✓			2025-10-31
qmj	Quality Minus Junk	1957-07-01	✓		✓			2025-10-31
bab	Betting Against beta	1930-12-01	✓		✓			2025-10-31

• Fama-French: data up until until end of prior month.
• Fama-French: most international/emerging factors (accessed with the region param) begin between 1985-1990.
• AQR models: non-US data begins around 1990 (accessed with the country param).

References

Publications:

1. E. F. Fama and K. R. French, ‘Common risk factors in the returns on stocks and bonds’, Journal of Financial Economics, vol. 33, no. 1, pp. 3–56, 1993. PDF
2. M. Carhart, ‘On Persistence in Mutual Fund Performance’, Journal of Finance, vol. 52, no. 1, pp. 57–82, 1997. PDF
3. E. F. Fama and K. R. French, ‘A five-factor asset pricing model’, Journal of Financial Economics, vol. 116, no. 1, pp. 1–22, 2015. PDF
4. E. F. Fama and K. R. French, ‘Choosing factors’, Journal of Financial Economics, vol. 128, no. 2, pp. 234–252, 2018. PDF
5. L. Pastor and R. Stambaugh, ‘Liquidity Risk and Expected Stock Returns’, Journal of Political Economy, vol. 111, no. 3, pp. 642–685, 2003. PDF
6. R. F. Stambaugh and Y. Yuan, ‘Mispricing Factors’, The Review of Financial Studies, vol. 30, no. 4, pp. 1270–1315, 12 2016. PDF
7. K. Hou, H. Mo, C. Xue, and L. Zhang, ‘Which Factors?’, National Bureau of Economic Research, Inc, 2014. PDF
8. K. Hou, H. Mo, C. Xue, and L. Zhang, ‘An Augmented q-Factor Model with Expected Growth*’, Review of Finance, vol. 25, no. 1, pp. 1–41, 02 2020. PDF
9. Z. He, B. Kelly, and A. Manela, ‘Intermediary asset pricing: New evidence from many asset classes’, Journal of Financial Economics, vol. 126, no. 1, pp. 1–35, 2017. PDF
10. K. Daniel, D. Hirshleifer, and L. Sun, ‘Short- and Long-Horizon Behavioral Factors’, Review of Financial Studies, vol. 33, no. 4, pp. 1673–1736, 2020. PDF
11. C. Asness and A. Frazzini, ‘The Devil in HML’s Details’, The Journal of Portfolio Management, vol. 39, pp. 49–68, 2013. PDF
12. A. Frazzini and L. H. Pedersen, “Betting Against Beta,” Journal of Financial Economics, vol. 111, no. 1, pp. 1–25, Jan. 2014. EconPapersPDF (working paper)
13. C. S. Asness, A. Frazzini, and L. H. Pedersen, “Quality Minus Junk,” Review of Accounting Studies, vol. 24, no. 1, pp. 34–112, Nov. 2019. EconPapers PDF
14. F. Barillas and J. Shanken, ‘Comparing Asset Pricing Models’, Journal of Finance, vol. 73, no. 2, pp. 715–754, 2018. PDF

Data sources:

• K. French, "Data Library," Tuck School of Business at Dartmouth. Link
• R. Stambaugh, "Liquidity" and "Mispricing" factor datasets, Wharton School, University of Pennsylvania. Link
• Z. He, "Intermediary Capital Ratio and Risk Factor" dataset, zhiguohe.net. Link
• K. Hou, G. Xue, R. Zhang, "The Hou-Xue-Zhang q-factors data library," at global-q.org. Link
• AQR Capital Management's Data Sets.
• Lin Sun, DHS Behavioural factors Link

(back to top)

License

Known issues

• AQR Models (HML Devil, Betting Against Beta, Quality Minus Junk) download slowly, particulary daily datasets. Need to implement a progress bar.

Todo

• Documentation
• Example notebook
• better error handling
• HML Devil: progress bar on download, smarter caching.
• this README
• metadata on model (copyright, construction, factors)
• Drop pandas
• Refactor of FF models