"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
Merge branch 'pr1166' into quantlib-batch
Haozhe Wu3e736331c4a9
diff --cc agent/src/quantlib/factormodel.pyindex 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_attributionreturn 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.pyindex 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 importMARKET_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_fpd.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)