"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
feat(quantlib): add multi-factor risk decomposition and risk attribution
santhrealebc6c4f83687
diff --git a/agent/src/quantlib/factormodel.py b/agent/src/quantlib/factormodel.pyindex 66b11d1b7..7eac99a52 100644--- a/agent/src/quantlib/factormodel.py+++ b/agent/src/quantlib/factormodel.py@@ -62,6 +62,7 @@ __all__ = ["MIN_CROSS_SECTION","STYLE_FACTOR_DEFINITIONS","FactorReturnFit",+ "FactorRiskDecomposition","StyleDrift","standardise_exposures","build_style_exposures",@@ -69,6 +70,7 @@ __all__ = ["portfolio_style_exposure","style_drift","factor_return_attribution",+ "factor_risk_decomposition",]#: Fraction trimmed from each tail before standardising.@@ -158,6 +160,49 @@ class StyleDrift:max_abs_change: pd.Series++@dataclass(frozen=True)+class FactorRiskDecomposition:+ """Portfolio risk decomposition into factor and asset-specific components.++ Attributes:+ total_variance: Total portfolio variance.+ total_volatility: Total portfolio volatility (standard deviation).+ factor_variance: Portfolio variance explained by common factors.+ factor_volatility: Portfolio volatility from common factors.+ specific_variance: Portfolio variance from asset-specific (idiosyncratic) risk.+ specific_volatility: Portfolio volatility from asset-specific risk.+ factor_variance_fraction: Fraction of total variance explained by factors.+ specific_variance_fraction: Fraction of total variance from idiosyncratic risk.+ portfolio_exposures: Portfolio exposures across factors.+ factor_marginal_contributions: Marginal contribution to risk (MCR) per factor.+ factor_risk_contributions: Absolute risk contribution per factor (sums to factor risk).+ factor_pcr: Percentage contribution to risk (PCR) per factor.+ asset_marginal_contributions: Marginal contribution to risk (MCR) per asset.+ asset_risk_contributions: Absolute risk contribution per asset (sums to total volatility).+ asset_pcr: Percentage contribution to risk (PCR) per asset (sums to 1.0).+ specific_risk_contributions: Specific risk contribution per asset.+ specific_pcr: Percentage contribution from specific risk per asset.+ """++ total_variance: float+ total_volatility: float+ factor_variance: float+ factor_volatility: float+ specific_variance: float+ specific_volatility: float+ factor_variance_fraction: float+ specific_variance_fraction: float+ portfolio_exposures: pd.Series+ factor_marginal_contributions: pd.Series+ factor_risk_contributions: pd.Series+ factor_pcr: pd.Series+ asset_marginal_contributions: pd.Series+ asset_risk_contributions: pd.Series+ asset_pcr: pd.Series+ specific_risk_contributions: pd.Series+ specific_pcr: pd.Series+def standardise_exposures(values: pd.Series,market_caps: pd.Series | None = None,@@ -513,3 +558,147 @@ def factor_return_attribution(contributions["specific"] = portfolio_return - explainedcontributions["total"] = portfolio_returnreturn contributions+++def factor_risk_decomposition(+ portfolio_weights: pd.Series | Mapping[str, float],+ exposures: pd.DataFrame,+ factor_cov: pd.DataFrame,+ specific_variances: pd.Series | Mapping[str, float] | None = None,+) -> FactorRiskDecomposition:+ """Decompose portfolio risk into systematic factor and idiosyncratic components.++ Implements the Euler homogeneous risk decomposition for multi-factor models+ (Barra/Axioma standard framework):++ Total Variance = w^T X Sigma_F X^T w + w^T D w++ where:+ * ``w`` is the portfolio weight vector (N x 1)+ * ``X`` is the asset factor exposure matrix (N x K)+ * ``Sigma_F`` is the factor covariance matrix (K x K)+ * ``D`` is the diagonal matrix of specific variances (N x N)++ Args:+ portfolio_weights: Asset weights in the portfolio.+ exposures: Asset factor exposures (rows = assets, columns = factors).+ factor_cov: Covariance matrix of factor returns (K x K).+ specific_variances: Asset-specific (idiosyncratic) return variances.+ Defaults to zero if omitted.++ Returns:+ :class:`FactorRiskDecomposition` containing total/factor/specific+ variances, volatilities, marginal contributions to risk (MCR), and+ percentage contributions to risk (PCR) per factor and per asset.++ Raises:+ ValueError: If weights or matrices are empty, contain non-finite values,+ or share no common assets or factors.+ """+ w_series = pd.Series(portfolio_weights, dtype=float)+ if w_series.empty:+ raise ValueError("portfolio_weights cannot be empty")+ if not np.isfinite(w_series.values).all():+ raise ValueError("portfolio_weights contains non-finite values")++ if not isinstance(exposures, pd.DataFrame) or exposures.empty:+ raise ValueError("exposures must be a non-empty DataFrame")+ if not np.isfinite(exposures.values).all():+ raise ValueError("exposures contains non-finite values")++ if not isinstance(factor_cov, pd.DataFrame) or factor_cov.empty:+ raise ValueError("factor_cov must be a non-empty DataFrame")+ if not np.isfinite(factor_cov.values).all():+ raise ValueError("factor_cov contains non-finite values")++ # Align assets+ assets = w_series.index.intersection(exposures.index)+ if assets.empty:+ raise ValueError(+ f"No matching assets between weights ({sorted(w_series.index)}) and exposures ({sorted(exposures.index)})"+ )++ w = w_series.loc[assets]+ X = exposures.loc[assets]++ # Align factors+ factors = X.columns.intersection(factor_cov.index).intersection(factor_cov.columns)+ if factors.empty:+ raise ValueError(+ f"No matching factors between exposures ({sorted(X.columns)}) and factor_cov ({sorted(factor_cov.index)})"+ )++ X = X[factors]+ F = factor_cov.loc[factors, factors]++ # Align specific variances+ if specific_variances is not None:+ spec_var_s = pd.Series(specific_variances, dtype=float)+ if not np.isfinite(spec_var_s.values).all():+ raise ValueError("specific_variances contains non-finite values")+ d = spec_var_s.reindex(assets, fill_value=0.0).clip(lower=0.0)+ else:+ d = pd.Series(0.0, index=assets, dtype=float)++ # Portfolio factor exposure: x_p = X^T w (K x 1)+ x_p = X.T.dot(w)++ # Factor variance: x_p^T F x_p+ F_x_p = F.dot(x_p)+ factor_var = float(np.maximum(0.0, x_p.dot(F_x_p)))+ factor_vol = float(np.sqrt(factor_var))++ # Specific variance: sum(w_i^2 * d_i)+ spec_var = float(np.maximum(0.0, (w**2 * d).sum()))+ spec_vol = float(np.sqrt(spec_var))++ total_var = float(np.maximum(0.0, factor_var + spec_var))+ total_vol = float(np.sqrt(total_var))++ var_denom = total_var if total_var > 0 else 1.0+ factor_var_frac = factor_var / var_denom if total_var > 0 else 0.0+ spec_var_frac = spec_var / var_denom if total_var > 0 else 0.0++ if total_vol > 0:+ # Factor MCR = (F x_p) / total_vol+ factor_mcr = F_x_p / total_vol+ factor_rc = x_p * factor_mcr+ factor_pcr = factor_rc / total_vol++ # Specific risk contribution per asset = (w_i^2 * d_i) / total_vol+ spec_rc = (w**2 * d) / total_vol+ spec_pcr = spec_rc / total_vol++ # Asset MCR = (X (F x_p) + d * w) / total_vol+ asset_mcr = (X.dot(F_x_p) + d * w) / total_vol+ asset_rc = w * asset_mcr+ asset_pcr = asset_rc / total_vol+ else:+ factor_mcr = pd.Series(0.0, index=factors, dtype=float)+ factor_rc = pd.Series(0.0, index=factors, dtype=float)+ factor_pcr = pd.Series(0.0, index=factors, dtype=float)+ spec_rc = pd.Series(0.0, index=assets, dtype=float)+ spec_pcr = pd.Series(0.0, index=assets, dtype=float)+ asset_mcr = pd.Series(0.0, index=assets, dtype=float)+ asset_rc = pd.Series(0.0, index=assets, dtype=float)+ asset_pcr = pd.Series(0.0, index=assets, dtype=float)++ return FactorRiskDecomposition(+ total_variance=total_var,+ total_volatility=total_vol,+ factor_variance=factor_var,+ factor_volatility=factor_vol,+ specific_variance=spec_var,+ specific_volatility=spec_vol,+ factor_variance_fraction=factor_var_frac,+ specific_variance_fraction=spec_var_frac,+ portfolio_exposures=x_p,+ factor_marginal_contributions=factor_mcr,+ factor_risk_contributions=factor_rc,+ factor_pcr=factor_pcr,+ asset_marginal_contributions=asset_mcr,+ asset_risk_contributions=asset_rc,+ asset_pcr=asset_pcr,+ specific_risk_contributions=spec_rc,+ specific_pcr=spec_pcr,+ )diff --git a/agent/tests/quantlib/test_factormodel.py b/agent/tests/quantlib/test_factormodel.pyindex aaf1450fa..228caadf2 100644--- a/agent/tests/quantlib/test_factormodel.py+++ b/agent/tests/quantlib/test_factormodel.py@@ -14,9 +14,12 @@ from src.quantlib.factormodel import (MARKET_FACTOR,MIN_CROSS_SECTION,STYLE_FACTOR_DEFINITIONS,+ FactorReturnFit,+ FactorRiskDecomposition,build_style_exposures,cross_sectional_factor_returns,factor_return_attribution,+ factor_risk_decomposition,portfolio_style_exposure,standardise_exposures,style_drift,@@ -425,3 +428,123 @@ def test_attribution_rejects_disjoint_factor_sets():factor_return_attribution(pd.Series({"value": 1.0}), pd.Series({"momentum": 0.01}), portfolio_return=0.0)++# --- risk decomposition ---+++def test_factor_risk_decomposition_euler_sum_identities():+ assets = _assets(4)+ factors = ["market", "value", "momentum"]+ weights = pd.Series([0.4, 0.3, 0.2, 0.1], index=assets)+ exposures = pd.DataFrame(+ [+ [1.0, 0.5, -0.2],+ [0.9, -0.4, 0.8],+ [1.1, 0.2, 0.5],+ [0.8, -0.1, -0.6],+ ],+ index=assets,+ columns=factors,+ )+ factor_cov = pd.DataFrame(+ [+ [0.04, 0.005, -0.002],+ [0.005, 0.02, 0.001],+ [-0.002, 0.001, 0.03],+ ],+ index=factors,+ columns=factors,+ )+ specific_vars = pd.Series([0.01, 0.015, 0.02, 0.008], index=assets)++ decomp = factor_risk_decomposition(+ portfolio_weights=weights,+ exposures=exposures,+ factor_cov=factor_cov,+ specific_variances=specific_vars,+ )++ assert isinstance(decomp, FactorRiskDecomposition)+ # 1. Total variance = factor_variance + specific_variance+ assert decomp.total_variance == pytest.approx(+ decomp.factor_variance + decomp.specific_variance, abs=1e-12+ )+ assert decomp.total_volatility == pytest.approx(np.sqrt(decomp.total_variance), abs=1e-12)++ # 2. Variance fractions sum to 1.0+ assert decomp.factor_variance_fraction + decomp.specific_variance_fraction == pytest.approx(+ 1.0, abs=1e-12+ )++ # 3. Euler decomposition across assets: sum(asset_risk_contributions) == total_volatility+ assert float(decomp.asset_risk_contributions.sum()) == pytest.approx(+ decomp.total_volatility, abs=1e-12+ )++ # 4. Asset PCR sum to 1.0 (100%)+ assert float(decomp.asset_pcr.sum()) == pytest.approx(1.0, abs=1e-12)++ # 5. Factor risk + specific risk = total volatility+ total_rc_by_factors = (+ float(decomp.factor_risk_contributions.sum()) + float(decomp.specific_risk_contributions.sum())+ )+ assert total_rc_by_factors == pytest.approx(decomp.total_volatility, abs=1e-12)++ # 6. Factor PCR + specific PCR = 1.0+ assert float(decomp.factor_pcr.sum()) + float(decomp.specific_pcr.sum()) == pytest.approx(+ 1.0, abs=1e-12+ )+++def test_factor_risk_decomposition_without_specific_variance():+ assets = _assets(2)+ factors = ["market"]+ weights = pd.Series([0.6, 0.4], index=assets)+ exposures = pd.DataFrame([[1.0], [1.0]], index=assets, columns=factors)+ factor_cov = pd.DataFrame([[0.04]], index=factors, columns=factors)++ decomp = factor_risk_decomposition(weights, exposures, factor_cov)++ assert decomp.specific_variance == 0.0+ assert decomp.specific_volatility == 0.0+ assert decomp.factor_variance_fraction == 1.0+ assert decomp.specific_variance_fraction == 0.0+ # Portfolio beta is 1.0, vol is sqrt(0.04) = 0.20+ assert decomp.total_volatility == pytest.approx(0.20, abs=1e-12)+ assert decomp.factor_risk_contributions["market"] == pytest.approx(0.20, abs=1e-12)+++def test_factor_risk_decomposition_zero_weights_safe():+ assets = _assets(2)+ factors = ["market"]+ weights = pd.Series([0.0, 0.0], index=assets)+ exposures = pd.DataFrame([[1.0], [1.0]], index=assets, columns=factors)+ factor_cov = pd.DataFrame([[0.04]], index=factors, columns=factors)++ decomp = factor_risk_decomposition(weights, exposures, factor_cov)+ assert decomp.total_variance == 0.0+ assert decomp.total_volatility == 0.0+ assert (decomp.asset_risk_contributions == 0.0).all()+ assert (decomp.asset_pcr == 0.0).all()+++def test_factor_risk_decomposition_input_validation():+ assets = _assets(2)+ factors = ["market"]+ weights = pd.Series([0.5, 0.5], index=assets)+ exposures = pd.DataFrame([[1.0], [1.0]], index=assets, columns=factors)+ factor_cov = pd.DataFrame([[0.04]], index=factors, columns=factors)++ with pytest.raises(ValueError, match="weights cannot be empty"):+ factor_risk_decomposition(pd.Series(dtype=float), exposures, factor_cov)++ with pytest.raises(ValueError, match="non-finite"):+ factor_risk_decomposition(pd.Series([np.nan, 0.5], index=assets), exposures, factor_cov)++ with pytest.raises(ValueError, match="No matching assets"):+ factor_risk_decomposition(pd.Series([0.5, 0.5], index=["X1", "X2"]), exposures, factor_cov)++ with pytest.raises(ValueError, match="No matching factors"):+ factor_risk_decomposition(+ weights, exposures, pd.DataFrame([[0.04]], index=["other"], columns=["other"])+ )