getfactormodels 0.0.11

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]
• The 6-factor model of Barillas and Shanken^[12]

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

Python

get_factors

from getfactormodels import DHSFactors

model = DHSFactors(
    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-Factor
ff3 = FamaFrenchFactors(model='3', frequency='m', region='developed', start_date='2020-01-01')

ff3.end_date = '2020'
ff3.frequency = 'd'

df_ff3 = ff3.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

(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	✓		✓		✓	-
hmld	HML $^{DEVIL}$	1990-07-02	✓		✓			-
dhs	DHS	1972-07-03	✓		✓			2023-12-29
icr	ICR	1970-01-31 Daily: 1999-05-03	✓		✓	✓		2025-06-27
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$	✓	2022-12-30
bs	Barillas-Shanken	1967-01-03	✓		✓			2024-12-31

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

• HML Devil: initial download is slow, particulary for daily data.

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