Convenience API

High-level convenience API for grubeta.

These functions are the “front door” for non-technical users who want to estimate dynamic beta without understanding ML concepts.

Usage:
>>> from grubeta import estimate_beta
>>> result = estimate_beta("AAPL", "SPY")
>>> print(result["summary"])
grubeta.convenience.format_summary(beta_series, dates=None, stock_returns=None, market_returns=None, stock_name='Stock', market_name='Market')[source]

Format a human-readable summary of dynamic beta results.

Parameters:

  • beta_series (pd.Series or np.ndarray) – Dynamic beta estimates (may contain NaN for burn-in).

  • dates (pd.DatetimeIndex, optional) – Date index corresponding to beta_series.

  • stock_returns (pd.Series or np.ndarray, optional) – Stock returns for R² calculation.

  • market_returns (pd.Series or np.ndarray, optional) – Market returns for R² calculation.

  • stock_name (str) – Ticker or label for the stock.

  • market_name (str) – Ticker or label for the market.

Returns:

Human-readable summary string.

Return type:

str

grubeta.convenience.estimate_beta(stock, market='SPY', start=None, end=None, preset='default', plot=True, verbose=True)[source]

Estimate time-varying beta for a stock relative to a market index.

This is the simplest way to use grubeta. Pass ticker symbols or return series, and get back a complete analysis with summary and plot.

Parameters:

  • stock (str or pd.Series) – Stock ticker (e.g., “AAPL”) or daily return series.

  • market (str or pd.Series) – Market ticker (e.g., “SPY”) or daily return series.

  • start (str, optional) – Start date as “YYYY-MM-DD”. Default: 10 years ago.

  • end (str, optional) – End date as “YYYY-MM-DD”. Default: today.

  • preset (str) – Configuration preset: “default”, “responsive”, “smooth”, “research”.

  • plot (bool) – Whether to display a plot of the beta trajectory.

  • verbose (bool) – Whether to print progress updates.

Returns:

Keys: ‘beta’, ‘alpha’, ‘dates’, ‘summary’, ‘model’, ‘results’, ‘fig’ - beta: pd.Series of dynamic beta estimates - alpha: pd.Series of dynamic alpha estimates - dates: DatetimeIndex - summary: human-readable summary string - model: fitted DynamicBeta object - results: full DataFrame from fit_predict - fig: matplotlib Figure (if plot=True, else None)

Return type:

dict

Examples

>>> from grubeta import estimate_beta
>>> result = estimate_beta("AAPL", "SPY")
>>> print(result["summary"])
>>> result["beta"].tail()
grubeta.convenience.compare_betas(stocks, market='SPY', start=None, end=None, preset='default')[source]

Compare dynamic betas across multiple stocks.

Parameters:

  • stocks (list of str) – List of stock tickers (e.g., [“AAPL”, “MSFT”, “GOOGL”]).

  • market (str or pd.Series) – Market ticker or return series.

  • start (str, optional) – Start date. Default: 10 years ago.

  • end (str, optional) – End date. Default: today.

  • preset (str) – Configuration preset.

Returns:

Keys: ‘betas’ (DataFrame), ‘summary’, ‘fig’, ‘results’ (dict per stock)

Return type:

dict

grubeta.convenience.quick_report(stock, market='SPY', output='report.html', start=None, end=None, preset='default')[source]

Generate a formatted HTML report with plots, metrics, and interpretation.

Parameters:

  • stock (str or pd.Series) – Stock ticker or return series.

  • market (str or pd.Series) – Market ticker or return series.

  • output (str) – Output file path for the HTML report.

  • start (str, optional) – Start date.

  • end (str, optional) – End date.

  • preset (str) – Configuration preset.

Returns:

Path to the generated report file.

Return type:

str