Factor CLI

A command-line tool for analyzing funds and ETFs using factor regressions (Fama-French, Carhart models).

Caveat emptor

This repo was entirely written by claude code. Accuracy or quality are not guaranteed.

Features

Factor Analysis: Run Fama-French 3-factor, 5-factor, Carhart 4-factor, or 4-factor + momentum regressions
Factor Visualization: Plot factor returns over time (cumulative, raw, or rolling)
Telltale Charts: Compare relative performance of two funds
Implied Equity Risk Premium: Calculate the implied ERP for the S&P 500 using Damodaran's methodology
Portfolio Analysis: Analyze weighted portfolios of multiple holdings
Portfolio Comparison: Compare up to 3 portfolios across factor regressions, returns, and rolling returns
Fund Comparison: Compare factor exposures across multiple funds
Rolling Analysis: Track how factor loadings change over time
UK/International Support: Analyze UK ETFs (.L suffix) with developed market factors
Multiple Data Sources: Fetch prices from Yahoo Finance (default) or Stooq
Caching: Factor data is cached locally for faster subsequent analyses

Installation

Requires Python 3.10+.

asdf install

# Install with uv (recommended)
uv sync

# Or install with pip
pip install -e .

Usage

Analyze a Single Fund

# Basic analysis with Fama-French 3-factor model
uv run factor analyze SPY

# Use 5-factor model
uv run factor analyze SPY --model ff5

# Carhart 4-factor (adds momentum)
uv run factor analyze SPY --model carhart

# 4-factor + momentum (profitability + momentum, no investment factor)
uv run factor analyze SPY --model ff4_mom

# Specify date range
uv run factor analyze SPY --start 2020-01-01 --end 2024-01-01

Example output:

        Factor Regression: SPY (1993-02-28 to 2025-11-30)
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━┓
┃ Factor       ┃ Coefficient ┃   t-stat ┃ Sig ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━┩
│ Alpha (ann.) │      -0.06% │  (-0.24) │     │
│ Mkt-RF       │       0.985 │ (205.33) │ *** │
│ SMB          │      -0.172 │ (-25.24) │ *** │
│ HML          │       0.028 │   (4.34) │ *** │
└──────────────┴─────────────┴──────────┴─────┘
R²: 0.991 | Adj R²: 0.991 | N: 394 monthly

Analyze UK/International ETFs

# UK ETF (London Stock Exchange)
uv run factor analyze VWRL.L --model ff3 --region developed

# Use developed market factors for non-US funds
uv run factor analyze ISF.L --region developed

Analyze Emerging Market ETFs

# Emerging market ETF with FF5 model
uv run factor analyze VWO --model ff5 --region emerging

# Carhart model (includes momentum)
uv run factor analyze EEM --model carhart --region emerging

Note: Ken French only provides monthly data for emerging markets. Daily frequency is not available and will return an error.

Global Factor Analysis

Use the global region to analyze funds against a weighted combination of regional factors:

# Global factors (weighted combination of US, Developed, and Emerging)
uv run factor analyze VT --region global

# Daily frequency (US + Developed only, no EM daily data available)
uv run factor analyze VT --region global --frequency daily

Global factor weights:

Frequency	US	Developed	Emerging
Monthly	60%	30%	10%
Daily	65%	35%	—

The global region combines factor data from multiple regions using weighted averages, which is useful for analyzing globally diversified funds like VT (Vanguard Total World Stock ETF).

Alternative Data Source (Stooq)

If Yahoo Finance has issues with certain tickers, you can use Stooq as an alternative data source:

# Use Stooq for price data
uv run factor analyze VWRL.L --source stooq --region developed

# Works with all commands
uv run factor portfolio VWRL.L:60 ISF.L:40 --source stooq
uv run factor compare SPY QQQ --source stooq
uv run factor rolling SPY --source stooq

Stooq automatically converts ticker formats:

UK tickers: .L → .UK (e.g., VWRL.L → VWRL.UK)
US tickers: adds .US suffix (e.g., SPY → SPY.US)

Compare Multiple Funds

# Compare funds side by side
uv run factor compare SPY QQQ IWM

# Sort by alpha
uv run factor compare SPY QQQ IWM --sort alpha

# Sort by a specific factor loading
uv run factor compare SPY QQQ IWM --sort SMB

Example output:

               Fund Comparison (Fama-French 3-Factor)
┏━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┓
┃ Ticker ┃ Alpha (ann.) ┃   Mkt-RF ┃       SMB ┃       HML ┃    R² ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━┩
│ QQQ    │       +1.77% │ 1.24 *** │  0.12 *** │ -0.65 *** │ 0.877 │
│ SPY    │       -0.06% │ 0.99 *** │ -0.17 *** │  0.03 *** │ 0.991 │
│ IWM    │   -1.54% *** │ 1.01 *** │  0.82 *** │  0.25 *** │ 0.981 │
└────────┴──────────────┴──────────┴───────────┴───────────┴───────┘

Rolling Factor Analysis

Track how factor exposures change over time:

# 36-month rolling window (default)
uv run factor rolling SPY

# Custom window size
uv run factor rolling SPY --window 24

# Track a specific factor
uv run factor rolling SPY --factor Mkt-RF

Portfolio Analysis

Analyze factor exposures of a weighted portfolio:

# Specify holdings with weights as percentages (must sum to 100)
uv run factor portfolio SPY:60 QQQ:40

# Or use decimals (must sum to 1.0)
uv run factor portfolio SPY:0.6 QQQ:0.4

# Equal-weighted portfolio
uv run factor portfolio SPY QQQ IWM --equal-weight

# With custom name and options
uv run factor portfolio SPY:50 QQQ:30 IWM:20 \
  --model ff5 --name "US Equity Mix"

# Specify date range
uv run factor portfolio SPY:60 QQQ:40 --start 2020-01-01

Example output:

                Portfolio Composition
┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ Ticker ┃ Name                                 ┃ Weight ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ SPY    │ SPDR S&P 500 ETF Trust               │  60.0% │
│ QQQ    │ Invesco QQQ Trust                    │  40.0% │
└────────┴──────────────────────────────────────┴────────┘

      Factor Regression: Portfolio (2010-01-31 to 2025-01-31)
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━┓
┃ Factor       ┃ Coefficient ┃   t-stat ┃ Sig ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━┩
│ Alpha (ann.) │      +0.72% │   (1.42) │     │
│ Mkt-RF       │       1.064 │ (115.29) │ *** │
│ SMB          │      -0.103 │  (-7.89) │ *** │
│ HML          │      -0.215 │ (-15.95) │ *** │
└──────────────┴─────────────┴──────────┴─────┘
R²: 0.989 | Adj R²: 0.989 | N: 180 monthly

Compare Multiple Portfolios

Compare up to 3 portfolios side by side across factor regressions, returns metrics, and rolling returns:

# Compare two portfolios
uv run factor compare-portfolios "SPY:60 QQQ:40" "VTI:100"

# Compare three portfolios with custom names
uv run factor compare-portfolios "SPY:60 QQQ:40" "VTI:100" "IWM:50 BND:50" \
  --name "Growth" --name "Simple" --name "Balanced"

# With different model and rolling window
uv run factor compare-portfolios "SPY:60 QQQ:40" "VTI:70 BND:30" \
  --model ff5 --rolling-window 24

Each portfolio is specified as a quoted string with space-separated TICKER:WEIGHT pairs.

Example output:

       Factor Regression Comparison (Fama-French 3-Factor)
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Factor           ┃ Growth      ┃ Simple     ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ Alpha (ann.)     │ +0.72%      │ +0.12%     │
│ Mkt-RF (Market)  │ 1.06 ***    │ 1.01 ***   │
│ SMB (Size)       │ -0.10 ***   │ -0.05 ***  │
│ HML (Value)      │ -0.22 ***   │ 0.02       │
│ R-squared        │ 0.989       │ 0.998      │
└──────────────────┴─────────────┴────────────┘

                Returns Comparison
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Metric             ┃ Growth    ┃ Simple   ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━┩
│ Total Return       │ +245.2%   │ +198.1%  │
│ Annualized Return  │ +12.3%    │ +10.5%   │
│ Annualized Vol.    │ 15.2%     │ 13.8%    │
│ Sharpe Ratio       │ 0.81      │ 0.76     │
│ Max Drawdown       │ -22.3%    │ -19.1%   │
└────────────────────┴───────────┴──────────┘

        Rolling 12-Period Returns Summary
┏━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Statistic  ┃ Growth    ┃ Simple   ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━┩
│ Mean       │ +14.2%    │ +11.8%   │
│ Std Dev    │ 12.5%     │ 10.2%    │
│ Min        │ -18.3%    │ -15.1%   │
│ Max        │ +42.1%    │ +35.6%   │
└────────────┴───────────┴──────────┘

Search for Funds

# Search by name
uv run factor search "vanguard global"

# Search by ticker
uv run factor search VWRL

# Search by ISIN
uv run factor search GB00B4L5F271

Plot Factor Returns

Visualize factor returns over time as a chart:

# Basic: cumulative returns (growth of $1) for all FF3 factors
uv run factor plot

# Exclude market factor (useful since it dominates other factors)
uv run factor plot --no-market

# Plot specific factors only
uv run factor plot --factors Mkt-RF --factors SMB

# Rolling returns with 24-month window
uv run factor plot --chart-type rolling --window 24

# Raw periodic returns
uv run factor plot --chart-type returns

# FF5 model with date range, save to custom file without opening
uv run factor plot --model ff5 --start 2010-01-01 --output factors.png --no-open

Chart types:

cumulative (default): Growth of $1 over time
returns: Raw periodic returns
rolling: Rolling N-period returns

The chart is saved as a PNG file and automatically opened in your system's default image viewer. Use --no-open to skip opening.

Compare Two Funds (Telltale Chart)

Create a relative strength chart comparing two funds:

# Basic comparison - SPY vs QQQ
uv run factor telltale SPY QQQ

# With date range
uv run factor telltale VTI BND --start 2020-01-01

# UK ETFs via Stooq
uv run factor telltale VWRL.L ISF.L --source stooq

# Log scale for long time periods
uv run factor telltale SPY IWM --log-scale --output spy_vs_iwm.png

The telltale chart shows the normalized price ratio of the first fund to the second:

Line rising: First fund is outperforming the second
Line falling: Second fund is outperforming the first
Starting point: Always normalized to 1.0

The chart displays the total outperformance percentage at the end of the period.

Calculate Implied Equity Risk Premium

Calculate the implied equity risk premium (ERP) for the S&P 500 using Damodaran's methodology:

# Basic calculation with live market data
uv run factor erp

# Show detailed cash flow projections
uv run factor erp --details

# Skip fetching buyback yield, use 2.5% default
uv run factor erp --use-default-buyback

# Override specific inputs
uv run factor erp --base-growth 0.08 --buyback-yield 0.03

# Full custom inputs with details
uv run factor erp -g 0.10 -b 0.025 -t 0.04 -r 0.045 --details

Options:

Option	Short	Description
`--dividend-yield`	`-d`	Override dividend yield (decimal, e.g., 0.015)
`--buyback-yield`	`-b`	Override buyback yield (decimal, e.g., 0.025)
`--base-growth`	`-g`	Override base growth rate (decimal, e.g., 0.10)
`--terminal-growth`	`-t`	Override terminal growth rate (decimal)
`--risk-free-rate`	`-r`	Override risk-free rate (decimal, e.g., 0.045)
`--use-default-buyback`		Skip buyback fetch, use 2.5% default
`--details`		Show detailed cash flow projections

The calculation uses a 2-stage dividend discount model with tapering growth rates. It solves for the discount rate that equates the present value of expected cash flows (dividends + buybacks) to the current S&P 500 index level, then subtracts the risk-free rate to get the implied ERP.

List Available Models

uv run factor models

Output:

                    Available Factor Models
┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Model   ┃ Name                 ┃ Factors                    ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ ff3     │ Fama-French 3-Factor │ Mkt-RF, SMB, HML           │
│ carhart │ Carhart 4-Factor     │ Mkt-RF, SMB, HML, Mom      │
│ ff5     │ Fama-French 5-Factor │ Mkt-RF, SMB, HML, RMW, CMA │
│ ff4_mom │ 4-Factor + Momentum  │ Mkt-RF, SMB, HML, RMW, Mom │
└─────────┴──────────────────────┴────────────────────────────┘

Manage Cache

Factor data is cached locally to speed up subsequent analyses:

# View cache info
uv run factor cache --info

# Clear cache
uv run factor cache --clear

Options Reference

Option	Short	Description
`--model`	`-m`	Factor model: `ff3`, `ff5`, `carhart`, `ff4_mom` (default: `ff3`)
`--region`	`-r`	Factor region: `us`, `developed`, `emerging`, `global` (default: `us`)
`--start`	`-s`	Start date (YYYY-MM-DD)
`--end`	`-e`	End date (YYYY-MM-DD)
`--frequency`	`-f`	Data frequency: `monthly`, `daily` (default: `monthly`)
`--source`	`-S`	Price data source: `yfinance`, `stooq` (default: `yfinance`)
`--sort`		Sort comparison by factor (e.g., `alpha`, `Mkt-RF`, `SMB`)
`--window`	`-w`	Rolling window size in periods (default: 36 for rolling, 12 for plot)
`--rolling-window`	`-w`	Rolling window for compare-portfolios (default: 12)
`--equal-weight`	`-E`	Use equal weights for portfolio holdings
`--name`	`-n`	Custom name for portfolio (repeatable in compare-portfolios)
`--chart-type`	`-t`	Chart type for plot: `cumulative`, `returns`, `rolling` (default: `cumulative`)
`--factors`	`-F`	Specific factors to plot (repeatable, e.g., `--factors Mkt-RF --factors SMB`)
`--output`	`-o`	Output file path for plot/telltale (default: `factor_plot.png` or `telltale.png`)
`--no-open`		Skip opening the chart file after creation
`--no-market`		Exclude market factor (Mkt-RF) from plot
`--log-scale`	`-l`	Use logarithmic scale for y-axis (telltale command)

Interpreting Results

Factor Loadings

Factor	Interpretation
Mkt-RF	Market beta. 1.0 = market-like, >1 = aggressive, <1 = defensive
SMB	Size. Positive = small-cap tilt, negative = large-cap tilt
HML	Value. Positive = value tilt, negative = growth tilt
Mom	Momentum. Positive = momentum strategy, negative = contrarian
RMW	Profitability. Positive = quality/profitable companies
CMA	Investment. Positive = conservative, negative = aggressive

Significance Levels

*** p < 0.01 (highly significant)
** p < 0.05 (significant)
* p < 0.10 (marginally significant)

Alpha

Alpha represents the annualized excess return not explained by the factor model. A statistically significant positive alpha suggests the fund outperforms its factor exposures.

Data Sources

Fund prices:
- Yahoo Finance via yfinance (default)
- Stooq via --source stooq (alternative)
Factor data: Ken French Data Library

Development

# Install dev dependencies
uv sync --all-extras

# Run tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=factor_cli

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
src/factor_cli		src/factor_cli
tests		tests
.gitignore		.gitignore
.tool-versions		.tool-versions
README.md		README.md
pyproject.toml		pyproject.toml
tickers.md		tickers.md
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Factor CLI

Caveat emptor

Features

Installation

Usage

Analyze a Single Fund

Analyze UK/International ETFs

Analyze Emerging Market ETFs

Global Factor Analysis

Alternative Data Source (Stooq)

Compare Multiple Funds

Rolling Factor Analysis

Portfolio Analysis

Compare Multiple Portfolios

Search for Funds

Plot Factor Returns

Compare Two Funds (Telltale Chart)

Calculate Implied Equity Risk Premium

List Available Models

Manage Cache

Options Reference

Interpreting Results

Factor Loadings

Significance Levels

Alpha

Data Sources

Development

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

joecorkerton/investing-factors-cli

Folders and files

Latest commit

History

Repository files navigation

Factor CLI

Caveat emptor

Features

Installation

Usage

Analyze a Single Fund

Analyze UK/International ETFs

Analyze Emerging Market ETFs

Global Factor Analysis

Alternative Data Source (Stooq)

Compare Multiple Funds

Rolling Factor Analysis

Portfolio Analysis

Compare Multiple Portfolios

Search for Funds

Plot Factor Returns

Compare Two Funds (Telltale Chart)

Calculate Implied Equity Risk Premium

List Available Models

Manage Cache

Options Reference

Interpreting Results

Factor Loadings

Significance Levels

Alpha

Data Sources

Development

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages