Skip to content

"Vibe-Trading: Your Personal Trading Agent"

Merge branch 'pr1166' into quantlib-batch

Haozhe Wu3e736331c4a9
diff --cc agent/src/quantlib/factormodel.py
index a347d62b4,5f32e6c1d..b610bd135
--- a/agent/src/quantlib/factormodel.py
+++ b/agent/src/quantlib/factormodel.py
@@@ -62,7 -63,7 +63,8 @@@ __all__ =
"MIN_CROSS_SECTION",
"STYLE_FACTOR_DEFINITIONS",
"FactorReturnFit",
+ "FactorRiskDecomposition",
+ "FactorICResult",
"StyleDrift",
"standardise_exposures",
"build_style_exposures",
@@@ -70,7 -71,7 +72,8 @@@
"portfolio_style_exposure",
"style_drift",
"factor_return_attribution",
+ "factor_risk_decomposition",
+ "factor_ic_analysis",
]
#: Fraction trimmed from each tail before standardising.
@@@ -562,153 -547,107 +594,259 @@@ def factor_return_attribution
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)})"
+ )
+
+ unmatched_weight = float(w_series.drop(index=assets, errors="ignore").abs().sum())
+ 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]
+ F_mat = F.to_numpy(dtype=float)
+ if not np.allclose(F_mat, F_mat.T, atol=1e-8):
+ raise ValueError("factor_cov matrix must be symmetric")
+ eigvals = np.linalg.eigvalsh(F_mat)
+ if np.min(eigvals) < -1e-8:
+ raise ValueError("factor_cov matrix must be positive semi-definite")
+
+ # 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,
+ unmatched_weight=unmatched_weight,
+ )
++
++
+ def factor_ic_analysis(
+ factor_panel: pd.DataFrame,
+ forward_returns: pd.DataFrame,
+ method: str = "spearman",
+ min_cross_section: int = MIN_CROSS_SECTION,
+ ) -> FactorICResult:
+ """Evaluate cross-sectional Information Coefficient (IC) time-series dynamics.
+
+ Measures the predictive power and persistence of a factor by calculating
+ daily/periodic cross-sectional correlations between factor scores and subsequent
+ forward returns (Grinold-Kahn fundamental law framework).
+
+ Args:
+ factor_panel: DataFrame of factor scores (index = dates, columns = assets).
+ forward_returns: DataFrame of forward returns (same shape and alignment; should be pre-shifted by caller).
+ method: Correlation method, ``'spearman'`` (Rank IC) or ``'pearson'`` (Linear IC).
+ min_cross_section: Minimum number of valid assets on a date to compute IC.
+
+ Returns:
+ :class:`FactorICResult` containing mean IC, IC IR, t-statistic, p-value,
+ higher moments, and full IC time series.
+
+ Raises:
+ ValueError: If inputs are empty, share no common dates or assets, or method is unknown.
+ """
+ if method not in ("spearman", "pearson"):
+ raise ValueError(f"method must be 'spearman' or 'pearson', got {method!r}")
+
+ if factor_panel.empty or forward_returns.empty:
+ raise ValueError("factor_panel and forward_returns must be non-empty")
+
+ # Align dates and assets
+ common_dates = factor_panel.index.intersection(forward_returns.index)
+ common_assets = factor_panel.columns.intersection(forward_returns.columns)
+
+ if common_dates.empty or common_assets.empty:
+ raise ValueError("No common dates and assets between factor_panel and forward_returns")
+
+ f_sub = factor_panel.loc[common_dates, common_assets]
+ r_sub = forward_returns.loc[common_dates, common_assets]
+
+ ic_records: dict[object, float] = {}
+
+ for date in common_dates:
+ f_row = f_sub.loc[date].dropna()
+ r_row = r_sub.loc[date].dropna()
+ shared = f_row.index.intersection(r_row.index)
+ if len(shared) < min_cross_section:
+ continue
+
+ f_vals = f_row.loc[shared].to_numpy(dtype=float)
+ r_vals = r_row.loc[shared].to_numpy(dtype=float)
+
+ if method == "spearman":
+ f_vals = rankdata(f_vals)
+ r_vals = rankdata(r_vals)
+
+ f_std = np.std(f_vals, ddof=1)
+ r_std = np.std(r_vals, ddof=1)
+
+ if f_std > 0 and r_std > 0:
+ corr = float(np.corrcoef(f_vals, r_vals)[0, 1])
+ if np.isfinite(corr):
+ ic_records[date] = corr
+
+ if not ic_records:
+ raise ValueError(
+ f"No cross-section had at least {min_cross_section} valid asset pairs to compute IC"
+ )
+
+ ic_series = pd.Series(ic_records, dtype=float, name="ic").sort_index()
+ n = len(ic_series)
+ mean_ic = float(ic_series.mean())
+
+ if n > 1:
+ std_ic = float(ic_series.std(ddof=1))
+ ic_ir = mean_ic / std_ic if std_ic > 0 else float("nan")
+ t_stat = ic_ir * np.sqrt(n) if std_ic > 0 else float("nan")
+ p_val = float(2 * student_t.sf(abs(t_stat), df=n - 1)) if np.isfinite(t_stat) else float("nan")
+ sk = float(skew(ic_series.to_numpy(), bias=False)) if n > 2 else 0.0
+ # Non-excess kurtosis (normal == 3.0)
+ kurt = float(kurtosis(ic_series.to_numpy(), fisher=False, bias=False)) if n > 3 else 3.0
+ else:
+ std_ic = float("nan")
+ ic_ir = float("nan")
+ t_stat = float("nan")
+ p_val = float("nan")
+ sk = 0.0
+ kurt = 3.0
+
+ pos_frac = float((ic_series > 0).mean()) if n > 0 else 0.0
+
+ return FactorICResult(
+ ic_mean=mean_ic,
+ ic_std=std_ic,
+ ic_ir=ic_ir,
+ ic_t_stat=t_stat,
+ ic_p_value=p_val,
+ ic_skewness=sk,
+ ic_kurtosis=kurt,
+ positive_ic_fraction=pos_frac,
+ n_periods=n,
+ ic_series=ic_series,
+ )
diff --cc agent/tests/quantlib/test_factormodel.py
index 484adc1f4,f1da70fb2..f40076a32
--- a/agent/tests/quantlib/test_factormodel.py
+++ b/agent/tests/quantlib/test_factormodel.py
@@@ -14,12 -14,12 +14,15 @@@ from src.quantlib.factormodel import
MARKET_FACTOR,
MIN_CROSS_SECTION,
STYLE_FACTOR_DEFINITIONS,
+ FactorReturnFit,
+ FactorRiskDecomposition,
+ FactorICResult,
+ FactorReturnFit,
build_style_exposures,
cross_sectional_factor_returns,
+ factor_ic_analysis,
factor_return_attribution,
+ factor_risk_decomposition,
portfolio_style_exposure,
standardise_exposures,
style_drift,
@@@ -429,146 -429,51 +432,194 @@@ def test_attribution_rejects_disjoint_f
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"])
+ )
+
+ with pytest.raises(ValueError, match="symmetric"):
+ factor_risk_decomposition(
+ pd.Series([0.5, 0.5], index=["A", "B"]),
+ pd.DataFrame([[1.0, 0.5], [0.5, 1.0]], index=["A", "B"], columns=["F1", "F2"]),
+ pd.DataFrame([[0.04, 0.01], [0.03, 0.04]], index=["F1", "F2"], columns=["F1", "F2"]),
+ )
+
+ with pytest.raises(ValueError, match="positive semi-definite"):
+ factor_risk_decomposition(
+ pd.Series([0.5, 0.5], index=["A", "B"]),
+ pd.DataFrame([[1.0], [1.0]], index=["A", "B"], columns=["F1"]),
+ pd.DataFrame([[-0.04]], index=["F1"], columns=["F1"]),
+ )
+
+
+def test_factor_risk_decomposition_reports_unmatched_weight():
+ weights = pd.Series([0.6, 0.4], index=["A", "UNCOVERED"])
+ exposures = pd.DataFrame([[1.0]], index=["A"], columns=["market"])
+ factor_cov = pd.DataFrame([[0.04]], index=["market"], columns=["market"])
+
+ decomp = factor_risk_decomposition(weights, exposures, factor_cov)
+ assert decomp.unmatched_weight == pytest.approx(0.4)
+ assert decomp.total_volatility == pytest.approx(0.6 * 0.20)
+ # --- factor IC analysis ---
+
+
+ def test_factor_ic_analysis_positive_predictive_factor():
+ dates = pd.date_range("2024-01-01", periods=20, freq="B")
+ assets = _assets(50)
+ rng = np.random.default_rng(101)
+
+ # Create factor scores and positively correlated forward returns
+ factor_data = rng.normal(0, 1, size=(len(dates), len(assets)))
+ noise = rng.normal(0, 0.5, size=(len(dates), len(assets)))
+ returns_data = 0.02 * factor_data + 0.01 * noise
+
+ factor_panel = pd.DataFrame(factor_data, index=dates, columns=assets)
+ forward_returns = pd.DataFrame(returns_data, index=dates, columns=assets)
+
+ result = factor_ic_analysis(factor_panel, forward_returns, method="spearman")
+
+ assert isinstance(result, FactorICResult)
+ assert result.n_periods == 20
+ assert result.ic_mean > 0.5 # strong positive correlation
+ assert result.ic_ir > 1.0
+ assert result.ic_t_stat > 3.0
+ assert result.ic_p_value < 0.01
+ assert result.positive_ic_fraction == pytest.approx(1.0)
+ assert len(result.ic_series) == 20
+
+
+ def test_factor_ic_analysis_methods_and_validation():
+ dates = pd.date_range("2024-01-01", periods=5, freq="B")
+ assets = _assets(20)
+ rng = np.random.default_rng(102)
+
+ factor_panel = pd.DataFrame(rng.normal(0, 1, size=(5, 20)), index=dates, columns=assets)
+ forward_returns = pd.DataFrame(rng.normal(0, 0.02, size=(5, 20)), index=dates, columns=assets)
+
+ # Test Pearson method
+ res_pearson = factor_ic_analysis(factor_panel, forward_returns, method="pearson")
+ assert isinstance(res_pearson, FactorICResult)
+ assert -1.0 <= res_pearson.ic_mean <= 1.0
+
+ # Invalid method
+ with pytest.raises(ValueError, match="method must be"):
+ factor_ic_analysis(factor_panel, forward_returns, method="kendall")
+
+ # Empty inputs
+ with pytest.raises(ValueError, match="non-empty"):
+ factor_ic_analysis(pd.DataFrame(), forward_returns)