beta-tool

Measure how your stocks and portfolios move with the market, from one command or one web page. No Python required.

License: MIT

• What is it?
• Get started
• Using the CLI
• Reading your results
• Troubleshooting
• For developers

beta-tool downloads price history, runs the statistics for you (regressions, confidence intervals, diagnostics) and hands back a clean summary and charts. You type a command or fill in a form. You never touch the code.

Highlights

• Static and rolling regressions, with log or simple returns at daily, weekly, monthly or annual frequency.
• Optional HAC (Newey-West) robust statistics and automatic diagnostic checks.
• Hedge backtests that avoid look-ahead bias, comparing hedged and unhedged risk.
• Fama-French 5-factor exposure analysis.
• Price data cached on your machine, so repeat runs are fast.

Pick whichever suits you. Both give the same results.

Open https://beta-tool.streamlit.app, choose a tool from the sidebar, fill in the form and read the interactive charts. Results can be downloaded as CSV and JSON.

This takes a couple of minutes and only needs to be done once. You do not need to install Python yourself: the installer below fetches the right version automatically.

1. Install uv (the installer that manages everything)

PowerShell (Windows):

irm https://astral.sh/uv/install.ps1 | iex

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then open a new terminal window.

2. Install beta-tool

uv tool install git+https://github.com/wangjubin-06/beta-tool.git

This puts the beta-tool command on your PATH, in its own isolated environment.

3. Add your data key

beta-tool downloads prices from Tiingo. Create a free account, copy your API token from your account's API page, and save it as an environment variable:

PowerShell (Windows):

setx TIINGO_API_KEY "your-key"

macOS / Linux (zsh; use ~/.bashrc if you use bash):

echo 'export TIINGO_API_KEY="your-key"' >> ~/.zshrc

Open a new terminal window afterwards so the change takes effect.

The factors command with --factor_source etf also needs a free FRED API key, saved the same way as FRED_API_KEY. The default Fama-French mode does not.

4. Run your first analysis

beta-tool beta MSFT SPY --period 5y --rolling -o plots

A results table prints in your terminal and the charts are saved as PNG files in a plots folder.

uv tool upgrade beta-tool
uv tool uninstall beta-tool

Downloaded prices are cached in a data/ folder inside the directory you run the command from.

To reuse one cache from any folder, set BETA_TOOL_DATA_DIR to a fixed folder, the same way you set the API key (for example setx BETA_TOOL_DATA_DIR "C:\beta-tool-data" in PowerShell). It is safe to delete the folder, and it's rebuilt on the next run.

Five commands, one per question. Every command has --help.

beta-tool --help
beta-tool beta --help

# How does MSFT move relative to SPY? Static and rolling beta, plots saved to ./plots
beta-tool beta MSFT SPY --period 5y --rolling -o plots

# Weekly log returns with HAC-robust statistics
beta-tool beta MSFT SPY -p 10y -f weekly -r log --hac -o plots

# One asset against several others
beta-tool multibeta GOOG -x NVDA -x AAPL -x KO --period 10y --hac -o plots

# A portfolio against several benchmarks (weights are percentages and must sum to 100)
beta-tool portfoliobeta --holding AAPL:40 --holding MSFT:35 --holding NVDA:25 -x SPY -x QQQM -x AGG -o plots

# Backtest a rolling hedge over the last 5 years
beta-tool hedge --holding NKE:20 --holding KO:20 --holding AAPL:20 --holding GOOG:20 --holding NVDA:20 -x SPY -x AGG -x QQQM --rolling --period 5y -o plots

# Backtest a static hedge over the last 5 years, estimating beta from the 126 days before the start
beta-tool hedge --holding AAPL:50 --holding MSFT:50 -x SPY --period 5y --static_lookback 126 -o plots

# Fama-French 5-factor loadings, then ETF-proxy factors with advanced output
beta-tool factors --holding NVDA --holding MSFT -f monthly
beta-tool factors --holding NVDA --factor_source etf --advanced

Instead of repeating --holding, put portfolio weights in a TOML file and pass --holdings-file holdings.toml:

[weights]
AAPL = 40
MSFT = 35
NVDA = 25

If you pass neither --output_dir nor --show, the tables print in your terminal and no plots are saved or shown.

If you pass neither --output_dir nor --show, the tables print in your terminal and no plots are saved or shown.

• Static table: window, frequency, return type, HAC settings, beta, alpha (and annualised alpha), R², p-values, t-stats, standard errors, 95% confidence intervals, observations and residual volatility.
• Rolling table (with --rolling): the current beta with its confidence interval and significance, alpha, R², plus the mean, median, min, max and standard deviation of the rolling beta.
• Diagnostic checks when HAC is off.
• Charts saved as 150 dpi PNGs in your --output_dir, for example MSFT_SPY_static_plot.png and MSFT_SPY_rolling_60_plot.png.

Betas are historical estimates. They change with the window, the frequency and the benchmark you pick, so treat them as a guide rather than a prediction.

Still stuck? Open an issue on GitHub with the command you ran and the message you saw.

Everything above is a thin layer over a Python library. If you want to extend it, script it or run the web app locally, this section is for you.

Requires Python 3.12+ and uv.

git clone https://github.com/wangjubin-06/beta-tool.git
cd beta-tool

uv sync                # core library + CLI

uv run beta-tool --help
uv run streamlit run src/beta_tool/webapp/app.py

Prefer pip? pip install -e . works too. From source, export TIINGO_API_KEY (and FRED_API_KEY for the ETF factor mode) in your shell as described in step 3 above.

from beta_tool import Beta, MultiBeta, PortfolioBeta, PortfolioHedge, EquityFactorsRegression

Two-asset beta, static and rolling

beta = Beta("msft", "spy", period="5y", frequency="daily", return_type="simple", hac=True)

beta.summary()                      # printed regression summary
results = beta.get_static_results() # dict: beta, alpha, r_squared, beta_pvalue, beta_ci_low, ...
fig = beta.plot_results()           # prices, return distributions, Q-Q plots and OLS scatter

beta.historical_rolling_beta(window=60)
beta.rolling_beta_summary()
fig = beta.rolling_beta_plot()

One asset against several

mb = MultiBeta("goog", ["nvda", "aapl", "ko"], period="10y", hac=True)
mb.summary()

Portfolio against benchmarks (weights are percentages and must sum to 100)

pb = PortfolioBeta(
    {"aapl": 40, "msft": 35, "nvda": 25},
    asset_to_be_regressed=["spy", "qqqm", "agg"],
    period="10y",
)
pb.summary()

Hedge backtest

hedge = PortfolioHedge(
    target={"nke": 20, "ko": 20, "aapl": 20, "goog": 20, "nvda": 20},
    hedge_instruments=["spy", "agg", "qqqm"],
    backtest_start_date="2018-09-09",
    backtest_end_date="2025-09-09",
    frequency="daily",
    hedge_type="rolling",
)

fig = hedge.backtest(plot=True)
hedge.metrics_df      # hedged vs unhedged risk metrics
hedge.latest_beta     # most recent hedge ratio(s)

Factor exposures

fac = EquityFactorsRegression(factor_source="french", frequency="monthly")
fac.asset_list("nvda", "msft")
fac.regress()          # run this first
fac.results()          # factor loadings with t-stats, p-values, CIs and plain-English notes
fac.advanced_results() # full statsmodels summaries

The three regression tools share their parameters and methods.

Note that the Python API defaults to log returns for Beta and MultiBeta, while the CLI defaults to simple returns.

PortfolioBeta.plot_results() is only available when regressing against a single asset. Duplicate tickers in a portfolio dict are merged, and duplicate factors in MultiBeta are removed.

backtest(plot=False) runs the simulation and returns a figure (or None). Afterwards, metrics_df and hedge_df hold the risk-metric tables, latest_beta holds the current hedge ratio(s), and backtest_plot() returns (fig, axes). Rolling hedges also expose rolling_beta_df.

Methods: asset_list(*tickers), regress(), results(), advanced_results(), reset_assets() and help().

The risk-free rate is the French RF series for Fama-French mode and the FRED 3-month T-bill (DGS3MO) for ETF mode. The ETF-proxy regression is a convenience approximation and is not the true Fama-French model.

Regression models

Beta / PortfolioBeta (one x):    r_y,t = α + β · r_x,t + ε_t
MultiBeta / PortfolioBeta (N x): r_y,t = α + Σ_j β_j · r_xj,t + ε_t
Factors:                         r_i,t − rf_t = α + Σ_k β_k · F_k,t + ε_t

For a portfolio, r_y,t is the weighted sum of its assets' simple returns. Prices are adjusted closes, and returns from different assets are aligned with an inner join on date.

Returns. Simple returns are P_t / P_{t-1} − 1; log returns are ln(P_t / P_{t-1}). In factors mode with log returns, the French factors (which are published as simple returns) are converted with log(1 + r).

HAC / Newey-West. HAC changes standard errors, p-values and confidence intervals but leaves the coefficient estimates unchanged. It is a common defensive default for daily financial returns. When it is off, residual diagnostics are printed instead.

Rolling beta. A fixed-window rolling OLS with a default window of 60 observations for the regression tools.

Hedging

• Hedged return: r_target,t − Σ_j β_j · r_hedge_j,t, built from simple returns because they aggregate linearly across assets at a point in time.
• Static hedge: beta is estimated only from data in the lookback window ending at the backtest start, then held fixed, so the backtest never sees the future.
• Rolling hedge: the hedge ratio applied on day t is the rolling beta from day t−1, refreshed every rebalance_freq observations and held piecewise-constant in between.
• The unhedged portfolio is buy-and-hold: units are bought at the start (index = 100) and never rebalanced.

flowchart TB
    subgraph Data
        TI["Tiingo<br/>adjusted prices"]
        FR["FRED<br/>3M T-bill"]
        KF["Ken French<br/>factor library"]
        TI --> CACHE[("Local cache")]
    end
    CACHE --> RET["Returns<br/>simple or log"]
    RET --> ENG["OLS engines<br/>static, rolling, HAC, diagnostics"]
    ENG --> B["Beta"]
    ENG --> MB["MultiBeta"]
    ENG --> PB["PortfolioBeta"]
    B --> H["PortfolioHedge"]
    MB --> H
    PB --> H
    CACHE --> EF["EquityFactorsRegression"]
    FR --> EF
    KF --> EF
    B --> UI["CLI, Python API, Streamlit"]
    MB --> UI
    PB --> UI
    H --> UI
    EF --> UI

The CLI and web layers are adapters: presentation logic lives there, and the core classes are never modified to suit them. Data-access failures (missing or invalid API key, unknown ticker, rate limit) are raised as DataError subclasses, and the CLI prints them as plain messages instead of tracebacks.

• Betas are historical estimates. They depend on the window, sampling frequency and benchmark you choose. A wide confidence interval or low R² means the number is noisy.
• French factors are US factors. Use them for US equities only. The most recent months may not yet be published.
• ETF-proxy factors are approximations, and momentum replaces the investment factor in that mode.
• Hedge backtests are simplified: no transaction costs, slippage, borrow or financing, and the risk-free rate is set to zero in the risk metrics.
• Portfolio construction differs slightly by tool. PortfolioBeta weights each period's asset returns, while PortfolioHedge tracks a buy-and-hold portfolio.
• Static hedge lookbacks are measured in calendar time (days, weeks or months before the backtest start), not in trading observations.
• Weekly data is not supported for factor regressions.
• Internet access and API keys are required for data that is not already cached.

• pytest test suite
• Kalman-filter time-varying beta
• Rolling factor-stability panel
• Scenario and stress tests using factor-beta dot products

This project is for educational and research purposes only and is not investment advice.