quantlite 0.7.0__tar.gz → 0.8.0__tar.gz

{quantlite-0.7.0/src/quantlite.egg-info → quantlite-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantlite
-Version: 0.7.0
+Version: 0.8.0
 Summary: A fat-tail-native quantitative finance toolkit: EVT, risk metrics, and honest modelling for markets that bite.
 Author-email: Prasant Sudhakaran <code@prasant.net>
 License: MIT License
@@ -713,6 +713,69 @@ Same Stephen Few theme, same muted palette, but with hover info, zoom, and nativ
 | `quantlite.crypto.stablecoin` | Depeg probability, peg deviation tracking, recovery time, reserve risk scoring |
 | `quantlite.crypto.exchange` | Exchange concentration (HHI), wallet risk, proof of reserves, liquidity risk, slippage |
 | `quantlite.crypto.onchain` | Wallet exposure, TVL tracking, DeFi dependency graphs, smart contract risk scoring |
+| `quantlite.factors.classical` | Fama-French three/five-factor, Carhart four-factor, factor attribution, factor summary |
+| `quantlite.factors.custom` | CustomFactor, significance testing, correlation matrix, factor portfolios, decay analysis |
+| `quantlite.factors.tail_risk` | CVaR decomposition, regime factor exposure, crowding score, tail factor beta |
+
+## v0.8: Factor Models
+
+Three modules for comprehensive factor analysis: classical academic models, custom factor tools, and tail-risk-aware factor decomposition.
+
+### Classical Factor Models
+
+Decompose returns into systematic factor exposures and genuine alpha.
+
+```python
+from quantlite.factors import fama_french_three, factor_summary
+
+# Fama-French three-factor regression
+result = fama_french_three(fund_returns, market, smb, hml)
+print(f"Alpha: {result['alpha']:.5f} (t={result['t_stats']['alpha']:.2f})")
+print(f"Market beta: {result['betas']['market']:.3f}")
+print(f"R-squared: {result['r_squared']:.3f}")
+```
+
+![Factor Betas](docs/images/factor_betas.png)
+
+### Custom Factor Tools
+
+Build, test, and analyse proprietary factors.
+
+```python
+from quantlite.factors import CustomFactor, factor_portfolio, factor_decay
+
+# Test factor decay
+decay = factor_decay(returns, momentum_signal, max_lag=20)
+print(f"Half-life: {decay['half_life']:.1f} periods")
+
+# Build long-short portfolios
+result = factor_portfolio(stock_returns, factor_values, n_quantiles=5)
+print(f"Long-short spread: {result['spread'] * 252:.2%} annualised")
+```
+
+![Factor Quintiles](docs/images/factor_quintiles.png)
+
+### Tail Risk Factor Analysis
+
+Understand how factor exposures behave in the tails and across regimes.
+
+```python
+from quantlite.factors import tail_factor_beta, factor_crowding_score
+
+# Tail betas: how exposures amplify in crises
+result = tail_factor_beta(returns, [market, value], ["Market", "Value"])
+for name in ["Market", "Value"]:
+    print(f"{name}: full={result['full_betas'][name]:.2f}, "
+          f"tail={result['tail_betas'][name]:.2f}")
+
+# Factor crowding detection
+crowd = factor_crowding_score([value_rets, momentum_rets])
+print(f"Crowding score: {crowd['current_score']:.3f}")
+```
+
+![Factor Crowding](docs/images/factor_crowding.png)
+
+See [docs/factors_classical.md](docs/factors_classical.md), [docs/factors_custom.md](docs/factors_custom.md), and [docs/factors_tail_risk.md](docs/factors_tail_risk.md) for the full API reference.
 
 ## v0.4: The Taleb Stack
 

{quantlite-0.7.0 → quantlite-0.8.0}/README.md

@@ -632,6 +632,69 @@ Same Stephen Few theme, same muted palette, but with hover info, zoom, and nativ
 | `quantlite.crypto.stablecoin` | Depeg probability, peg deviation tracking, recovery time, reserve risk scoring |
 | `quantlite.crypto.exchange` | Exchange concentration (HHI), wallet risk, proof of reserves, liquidity risk, slippage |
 | `quantlite.crypto.onchain` | Wallet exposure, TVL tracking, DeFi dependency graphs, smart contract risk scoring |
+| `quantlite.factors.classical` | Fama-French three/five-factor, Carhart four-factor, factor attribution, factor summary |
+| `quantlite.factors.custom` | CustomFactor, significance testing, correlation matrix, factor portfolios, decay analysis |
+| `quantlite.factors.tail_risk` | CVaR decomposition, regime factor exposure, crowding score, tail factor beta |
+
+## v0.8: Factor Models
+
+Three modules for comprehensive factor analysis: classical academic models, custom factor tools, and tail-risk-aware factor decomposition.
+
+### Classical Factor Models
+
+Decompose returns into systematic factor exposures and genuine alpha.
+
+```python
+from quantlite.factors import fama_french_three, factor_summary
+
+# Fama-French three-factor regression
+result = fama_french_three(fund_returns, market, smb, hml)
+print(f"Alpha: {result['alpha']:.5f} (t={result['t_stats']['alpha']:.2f})")
+print(f"Market beta: {result['betas']['market']:.3f}")
+print(f"R-squared: {result['r_squared']:.3f}")
+```
+
+![Factor Betas](docs/images/factor_betas.png)
+
+### Custom Factor Tools
+
+Build, test, and analyse proprietary factors.
+
+```python
+from quantlite.factors import CustomFactor, factor_portfolio, factor_decay
+
+# Test factor decay
+decay = factor_decay(returns, momentum_signal, max_lag=20)
+print(f"Half-life: {decay['half_life']:.1f} periods")
+
+# Build long-short portfolios
+result = factor_portfolio(stock_returns, factor_values, n_quantiles=5)
+print(f"Long-short spread: {result['spread'] * 252:.2%} annualised")
+```
+
+![Factor Quintiles](docs/images/factor_quintiles.png)
+
+### Tail Risk Factor Analysis
+
+Understand how factor exposures behave in the tails and across regimes.
+
+```python
+from quantlite.factors import tail_factor_beta, factor_crowding_score
+
+# Tail betas: how exposures amplify in crises
+result = tail_factor_beta(returns, [market, value], ["Market", "Value"])
+for name in ["Market", "Value"]:
+    print(f"{name}: full={result['full_betas'][name]:.2f}, "
+          f"tail={result['tail_betas'][name]:.2f}")
+
+# Factor crowding detection
+crowd = factor_crowding_score([value_rets, momentum_rets])
+print(f"Crowding score: {crowd['current_score']:.3f}")
+```
+
+![Factor Crowding](docs/images/factor_crowding.png)
+
+See [docs/factors_classical.md](docs/factors_classical.md), [docs/factors_custom.md](docs/factors_custom.md), and [docs/factors_tail_risk.md](docs/factors_tail_risk.md) for the full API reference.
 
 ## v0.4: The Taleb Stack
 

{quantlite-0.7.0 → quantlite-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantlite"
-version = "0.7.0"
+version = "0.8.0"
 description = "A fat-tail-native quantitative finance toolkit: EVT, risk metrics, and honest modelling for markets that bite."
 requires-python = ">=3.9"
 license = { file = "LICENSE" }
@@ -73,3 +73,6 @@ python_version = "3.10"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

quantlite-0.8.0/src/quantlite/factors/__init__.py

@@ -0,0 +1,43 @@
+"""Factor models: classical, custom, and tail risk factor analysis.
+
+Provides tools for multi-factor attribution, custom factor construction,
+factor significance testing, and tail-risk-aware factor decomposition.
+"""
+
+from quantlite.factors.classical import (
+    carhart_four,
+    factor_attribution,
+    factor_summary,
+    fama_french_five,
+    fama_french_three,
+)
+from quantlite.factors.custom import (
+    CustomFactor,
+    factor_correlation_matrix,
+    factor_decay,
+    factor_portfolio,
+    test_factor_significance,
+)
+from quantlite.factors.tail_risk import (
+    factor_crowding_score,
+    factor_cvar_decomposition,
+    regime_factor_exposure,
+    tail_factor_beta,
+)
+
+__all__ = [
+    "fama_french_three",
+    "fama_french_five",
+    "carhart_four",
+    "factor_attribution",
+    "factor_summary",
+    "CustomFactor",
+    "test_factor_significance",
+    "factor_correlation_matrix",
+    "factor_portfolio",
+    "factor_decay",
+    "factor_cvar_decomposition",
+    "regime_factor_exposure",
+    "factor_crowding_score",
+    "tail_factor_beta",
+]

quantlite-0.8.0/src/quantlite/factors/classical.py

@@ -0,0 +1,288 @@
+"""Classical factor models: Fama-French, Carhart, and generic multi-factor attribution.
+
+Implements the standard academic factor models used in performance attribution
+and risk analysis, plus a flexible generic factor regression framework.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy import stats as sp_stats
+
+
+def _ols_regression(y, X):
+    """Run OLS regression with intercept already included in X.
+
+    Returns dict with coefficients, t-stats, p-values, R-squared,
+    adjusted R-squared, and residuals.
+    """
+    y = np.asarray(y, dtype=float)
+    X = np.asarray(X, dtype=float)
+    n, k = X.shape
+
+    # OLS: beta = (X'X)^-1 X'y
+    XtX = X.T @ X
+    Xty = X.T @ y
+    try:
+        beta = np.linalg.solve(XtX, Xty)
+    except np.linalg.LinAlgError:
+        beta = np.linalg.lstsq(X, y, rcond=None)[0]
+
+    residuals = y - X @ beta
+    ss_res = float(np.sum(residuals ** 2))
+    ss_tot = float(np.sum((y - np.mean(y)) ** 2))
+
+    r_squared = 1.0 - ss_res / ss_tot if ss_tot > 0 else 0.0
+    adj_r_squared = 1.0 - (1.0 - r_squared) * (n - 1) / (n - k) if n > k else 0.0
+
+    # Standard errors
+    dof = max(n - k, 1)
+    mse = ss_res / dof
+    try:
+        cov_matrix = mse * np.linalg.inv(XtX)
+    except np.linalg.LinAlgError:
+        cov_matrix = mse * np.linalg.pinv(XtX)
+    se = np.sqrt(np.maximum(np.diag(cov_matrix), 0.0))
+
+    t_stats = np.where(se > 0, beta / se, 0.0)
+    p_values = np.array([
+        2.0 * (1.0 - sp_stats.t.cdf(abs(t), df=dof)) for t in t_stats
+    ])
+
+    return {
+        "coefficients": beta,
+        "t_stats": t_stats,
+        "p_values": p_values,
+        "r_squared": r_squared,
+        "adj_r_squared": adj_r_squared,
+        "residuals": residuals,
+        "se": se,
+    }
+
+
+def _run_factor_model(returns, factor_arrays, factor_names):
+    """Common logic for running a factor regression.
+
+    Parameters
+    ----------
+    returns : array-like
+        Asset return series.
+    factor_arrays : list of array-like
+        Factor return series (each same length as returns).
+    factor_names : list of str
+        Names for each factor.
+
+    Returns
+    -------
+    dict with alpha, betas, r_squared, t_stats, p_values, residuals,
+    adj_r_squared, and named beta entries.
+    """
+    y = np.asarray(returns, dtype=float)
+    factors = [np.asarray(f, dtype=float) for f in factor_arrays]
+
+    n = len(y)
+
+    # Build design matrix with intercept
+    X = np.column_stack([np.ones(n)] + factors)
+
+    reg = _ols_regression(y, X)
+
+    alpha = float(reg["coefficients"][0])
+    betas = {name: float(reg["coefficients"][i + 1]) for i, name in enumerate(factor_names)}
+
+    result = {
+        "alpha": alpha,
+        "betas": betas,
+        "r_squared": reg["r_squared"],
+        "adj_r_squared": reg["adj_r_squared"],
+        "t_stats": {
+            "alpha": float(reg["t_stats"][0]),
+        },
+        "p_values": {
+            "alpha": float(reg["p_values"][0]),
+        },
+        "residuals": reg["residuals"],
+    }
+
+    for i, name in enumerate(factor_names):
+        result["t_stats"][name] = float(reg["t_stats"][i + 1])
+        result["p_values"][name] = float(reg["p_values"][i + 1])
+
+    return result
+
+
+def fama_french_three(returns, market_returns, smb, hml):
+    """Fama-French three-factor model regression.
+
+    Regresses asset returns against market excess returns, SMB (Small Minus
+    Big), and HML (High Minus Low) factors.
+
+    Parameters
+    ----------
+    returns : array-like
+        Asset excess return series.
+    market_returns : array-like
+        Market excess return series.
+    smb : array-like
+        Size factor (Small Minus Big).
+    hml : array-like
+        Value factor (High Minus Low).
+
+    Returns
+    -------
+    dict
+        Keys: alpha, betas (dict with 'market', 'smb', 'hml'),
+        r_squared, adj_r_squared, t_stats, p_values, residuals.
+    """
+    return _run_factor_model(
+        returns,
+        [market_returns, smb, hml],
+        ["market", "smb", "hml"],
+    )
+
+
+def fama_french_five(returns, market_returns, smb, hml, rmw, cma):
+    """Fama-French five-factor model regression.
+
+    Extends the three-factor model with profitability (RMW) and
+    investment (CMA) factors.
+
+    Parameters
+    ----------
+    returns : array-like
+        Asset excess return series.
+    market_returns : array-like
+        Market excess return series.
+    smb : array-like
+        Size factor (Small Minus Big).
+    hml : array-like
+        Value factor (High Minus Low).
+    rmw : array-like
+        Profitability factor (Robust Minus Weak).
+    cma : array-like
+        Investment factor (Conservative Minus Aggressive).
+
+    Returns
+    -------
+    dict
+        Keys: alpha, betas (dict with 'market', 'smb', 'hml', 'rmw', 'cma'),
+        r_squared, adj_r_squared, t_stats, p_values, residuals.
+    """
+    return _run_factor_model(
+        returns,
+        [market_returns, smb, hml, rmw, cma],
+        ["market", "smb", "hml", "rmw", "cma"],
+    )
+
+
+def carhart_four(returns, market_returns, smb, hml, mom):
+    """Carhart four-factor model regression.
+
+    Extends the Fama-French three-factor model with a momentum factor.
+
+    Parameters
+    ----------
+    returns : array-like
+        Asset excess return series.
+    market_returns : array-like
+        Market excess return series.
+    smb : array-like
+        Size factor (Small Minus Big).
+    hml : array-like
+        Value factor (High Minus Low).
+    mom : array-like
+        Momentum factor (Winners Minus Losers).
+
+    Returns
+    -------
+    dict
+        Keys: alpha, betas (dict with 'market', 'smb', 'hml', 'mom'),
+        r_squared, adj_r_squared, t_stats, p_values, residuals.
+    """
+    return _run_factor_model(
+        returns,
+        [market_returns, smb, hml, mom],
+        ["market", "smb", "hml", "mom"],
+    )
+
+
+def factor_attribution(returns, factor_returns, factor_names):
+    """Generic multi-factor attribution.
+
+    Decomposes total returns into factor contributions and unexplained
+    (alpha) component.
+
+    Parameters
+    ----------
+    returns : array-like
+        Asset return series.
+    factor_returns : list of array-like
+        Factor return series.
+    factor_names : list of str
+        Names for each factor.
+
+    Returns
+    -------
+    dict
+        Keys: alpha, factor_contributions (dict mapping factor name to
+        mean contribution), unexplained (mean residual return),
+        r_squared, total_return (annualised mean).
+    """
+    result = _run_factor_model(returns, factor_returns, factor_names)
+
+    y = np.asarray(returns, dtype=float)
+    factors = [np.asarray(f, dtype=float) for f in factor_returns]
+
+    contributions = {}
+    for i, name in enumerate(factor_names):
+        beta = result["betas"][name]
+        mean_factor = float(np.mean(factors[i]))
+        contributions[name] = beta * mean_factor
+
+    total_mean = float(np.mean(y))
+    explained = sum(contributions.values())
+    unexplained = total_mean - explained
+
+    return {
+        "alpha": result["alpha"],
+        "factor_contributions": contributions,
+        "unexplained": unexplained,
+        "r_squared": result["r_squared"],
+        "total_return": total_mean,
+    }
+
+
+def factor_summary(returns, factor_returns, factor_names):
+    """One-call summary table for multi-factor regression.
+
+    Returns a comprehensive summary including alpha, each factor beta,
+    t-statistics, p-values, R-squared, and adjusted R-squared.
+
+    Parameters
+    ----------
+    returns : array-like
+        Asset return series.
+    factor_returns : list of array-like
+        Factor return series.
+    factor_names : list of str
+        Names for each factor.
+
+    Returns
+    -------
+    dict
+        Keys: alpha, alpha_t, alpha_p, betas (dict), t_stats (dict),
+        p_values (dict), r_squared, adj_r_squared, n_obs.
+    """
+    result = _run_factor_model(returns, factor_returns, factor_names)
+
+    return {
+        "alpha": result["alpha"],
+        "alpha_t": result["t_stats"]["alpha"],
+        "alpha_p": result["p_values"]["alpha"],
+        "betas": result["betas"],
+        "t_stats": {name: result["t_stats"][name] for name in factor_names},
+        "p_values": {name: result["p_values"][name] for name in factor_names},
+        "r_squared": result["r_squared"],
+        "adj_r_squared": result["adj_r_squared"],
+        "n_obs": len(np.asarray(returns)),
+    }