Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(quantlib): add multi-factor risk decomposition and risk attribution

santhrealebc6c4f83687
diff --git a/agent/src/quantlib/factormodel.py b/agent/src/quantlib/factormodel.py
index 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 - explained
contributions["total"] = portfolio_return
return 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.py
index 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"])
+ )