getfactormodels

A CLI and Python library to download 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.

Quick start

Install

[!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!

pip install getfactormodels

CLI Examples

Factor Models

• Download Fama-French 3-factor monthly data:

$ getfactormodels --model ff3 --freq m --start 2010 --end 2019-12-31	

Use --list-models to view all available models, IDs, and supported frequencies.

• Combine multiple models of the same frequency:

getfactormodels -m liq misp -f m -o liq_misp.csv

-o / --output automatically detects format from extensions (.csv, .parquet, .feather).

• Query regional models (e.g., Betting Against Beta in Australia):

getfactormodels -m bab -f m -s 2000-01 --region aus

Use --list-regions to see all available geographic regions and aliases (us, jpn, uk, ger, etc.).

• Drop or extract specific factors:

getfactormodels -m ff4 -x mom,rf
getfactormodels -m ff3 -d SMB

Portfolios & Industry Sorts

getfactormodels --portfolio op,bm -n 6 --src ff

Since portfolio factors available at global-q.com are different to the factors in the Fama/French portfolio, source usually isn't needed.

getfactormodels -p inv,size -n 2x3 -s 1990-01-01

-n accepts a grid (2x3, 5x5, 10x10, 2x4x4) or portfolio counts (6, 10, 25, 100).

getfactormodels -p industry 5

Supported industry sizes: 5, 10, 12, 17, 30, 38, 48, 49.

• Global-Q portfolio sorts:

getfactormodels -p me,eg -n 2x3
getfactormodels -p me,ia,roe

--portfolio q can be used as a shorthand for q-factor portfolios.

Anomalies

• A single anomaly with default decile sorting:

getfactormodels --anomaly sue_6 --end 2020-01-01

Use --list-anomalies to see the full categorized list of available anomaly tickers.

• Bivariate (2-way, 3x5) anomaly sorts:

getfactormodels -a beta_1 --bivariate

By default, -a returns 1-way decile sorts. Pass -b / --bivariate to switch to 3x5 sorts.

• Attach anomalies to a factor model:

getfactormodels -a abr_1,ta -m ff3 -s 2000 -o file.csv

• Combine models, industry portfolios, and bivariate anomalies:

getfactormodels -m ff3 -p industry 5 -a ol,rev_1 -b

Python Examples

from getfactormodels import model, portfolio, anomaly

# Load Fama-French 3-factor monthly model
ff3 = model("ff3", frequency="m", start_date="2010-01-01")
ff3.load()

# Load global-q anomaly data with 3x5 bivariate sort
a = anomaly(name="abr_1", frequency="m", sort="3x5").load()

# Export to CSV
a.to_file("abr_1_data.parquet")

Model classes

from getfactormodels import FamaFrenchFactors

# Initialize model instance
m = FamaFrenchFactors(model='3', frequency='m', 
			region='developed', start_date='2020-01-01')
m.end_date = '2020'

# Download the data 
m = m.load()

# Access/download the Arrow Table:
table = m.data

# As a dataframe:
df = m.to_polars() # Helper method, see also `.to_pandas()`

from getfactormodels import Qfactors, BABFactors

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

# Extract the Japan Betting Against Beta daily 'BAB' factor:
bab_jpn_df = BABFactors(frequency='d', region='JPN', 
                        start='2000-02-20', end '2010').load().extract("BAB").to_polars()

Example:

getfactormodels -m qmj -f d --output qmj.ipc

Data saved to: qmj.ipc

date            Mkt-RF           QMJ           SMB           HML           UMD    RF_AQR
1957-07-01    0.001784     -0.001566     -0.002166      0.001984      0.000651    0.0001
1957-07-02    0.008514     -0.000484     -0.005030     -0.004436      0.002705    0.0001
1957-07-03    0.007938      0.000869     -0.001245     -0.003676      0.002294    0.0001
1957-07-05    0.007755      0.001975     -0.000769     -0.002781     -0.001137    0.0001
  [...]
2025-10-28    0.001157      0.004138     -0.003897     -0.006681      0.011682    0.0002
2025-10-29   -0.002034     -0.003446     -0.007738     -0.002619      0.015875    0.0002
2025-10-30   -0.010841      0.009058     -0.000406      0.005180     -0.006211    0.0002
2025-10-31    0.003867     -0.006546      0.000620      0.001108      0.000869    0.0002

[17574 rows x 7 columns, 905.3 kb]

getfactormodels -m q -f q -o qfactors_qtrly.md

Data saved to: qfactors_qtrly.md

               Mkt-RF         R_ME         R_IA         R_EG        R_ROE       RF
date
1967-03-31   0.134805     0.114866    -0.053626    -0.015750     0.084400   0.0114
1967-06-30   0.018500     0.087544    -0.026375    -0.018427     0.021278   0.0092
1967-09-30   0.068962     0.055625     0.040412    -0.009986    -0.006436   0.0096
1967-12-31   0.002605     0.052229    -0.052616     0.017556     0.048551   0.0107
  [...]
2024-03-31   0.088848    -0.048872    -0.012363     0.001792     0.034865   0.0132
2024-06-30   0.022145    -0.051355    -0.025798     0.086070     0.084276   0.0135
2024-09-30   0.046601     0.020398     0.017324    -0.058132     0.025571   0.0138
2024-12-31   0.021465    -0.025093    -0.062185     0.024003    -0.038607   0.0116

[232 rows x 7 columns, 12.0 kb]

Interoperability

getfactormodels uses PyArrow internally and supports the Dataframe Interchange Protocol, allowing for zero-copy data sharing with most modern Python data tools.

Create a model instance:

from getfactormodels import QFactors
m = getfactormodels.QFactors(frequency='m')

• DuckDB can query a table without conversion

import duckdb
duckdb.sql("SELECT date, ROE, IA FROM m.data LIMIT 7").show() 

• Polars has first-class support for Arrow:

import polars as pl
df = pl.from_arrow(m.data)

• Pandas/NumPy

# Pandas DataFrame
df = m.to_pandas()

# or NumPy Array (via Pandas)
array = m.to_pandas().to_numpy()

• Libraries like Ibis, Modin or Vaex can use the dataframe interchange protocol directly:

df = vaex.from_arrow_table(m.data)
print(df.mean(vdf.ROE))

(back to top)

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.

• 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).
• Size and Value in China models are only available for China. region= must be ch, china or None (--region ch)
• getfactormodels has two conditional CAPM (CCAPM) models: a High-Income/Affluent CCAPM (annual, 1927-2022) from Campbell & Korniotis (2013)^[15], and an implementation of the Premium-Labor CCAPM (m, q, y; data from 1959-04-30) from Jagganathan & Wang (1996)^[16]

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
15. S. D. Campbell and G. M. Korniotis, "The Human Capital That Matters: Expected Returns and the Income of Affluent Households," Finance and Economics Discussion Series, BiblioGov, 2013. Web
16. R. Jagannathan and Z. Wang, ‘The Conditional CAPM and the Cross-Section of Expected Returns’, The Journal of Finance, vol. 51, no. 1, pp. 3–53, Mar. 1996.

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
• Error handling
• README
• Refactor of FF models
• metadata - copyright, license, bibtex/citations