做什么（One-liner）

Peaks-Over-Threshold (POT) EVT：returns → losses → 90% 分位阈值 → 超出部分拟合 GPD → closed-form VaR + ES。scipy.stats.genpareto 主路径 + 历史分位 fallback。单标的极端损失尾部估计。

怎么用

Canvas 拖 evt_tail_var_v1（POST /algorithms/evt_tail_var/run），params.returns 必填 + 可选 confidence=0.99 + threshold_quantile=0.9。典型用法：

price_factor → (derive returns) → evt_tail_var_v1 → risk overlay / report

核心公式

losses = -returns
threshold = quantile(losses, 0.9)                   # POT 阈值
exceedances = losses[losses > threshold] - threshold

# GPD fit (scipy):
shape, loc=0, scale = genpareto.fit(exceedances, floc=0)

# VaR (Pickands-Balkema-de Haan inverse):
p = 1 - confidence
VaR_EVT = threshold + (scale/shape) * ((n/n_u * p)**(-shape) - 1)
          if |shape| > 1e-8 else threshold + scale * log((n/n_u) * p)

# Expected Shortfall:
ES_EVT = (VaR + scale - shape*threshold) / (1 - shape)  if shape < 1
       = NaN                                             if shape >= 1

Rounding 契约：values → 6; shape → 4.

假设与适用场景

假设：stationary tail + i.i.d. exceedances + ≥30 returns + ≥5 exceedances + scipy 数值稳定 + threshold_quantile=0.9 default 适用于 ~N(0,σ) 数据。

适用：单标的 historical VaR 的补强（EVT 外推）、GPD shape 作 fat-tail 指标、监管报告。

不适用：组合级 VaR（用 portfolio_risk_metrics）、intraday、non-stationary、需要 bootstrap CI、rigorous threshold 选择。

输入 / 输出契约

{returns, confidence?=0.99, threshold_quantile?=0.9} → Primary: {var_evt, es_evt, confidence, threshold, n_exceedances, gpd_shape, gpd_scale, historical_var, _method='POT_GPD (scipy.stats.genpareto)'}；Fallback: {var_evt, es_evt, confidence, _method='historical_quantile_fallback'}；Error: {error, message}.

已知局限

1. threshold_quantile=0.9 default ad-hoc：学术 POT 应用 mean excess plot 选阈；本 operator 固定 90%
2. No threshold diagnostic（shape 对阈值选择敏感，用户须自行 sweep）
3. No bootstrap CI（点估计）
4. 不处理 serial correlation（GARCH filter 应做但未实现）
5. shape >= 1 时 ES = NaN（客户端需容错）
6. Fallback 用 historical_quantile 无 EVT 外推
7. Fallback ES 定义非标（sort_desc[:int(n*(1-c))].mean()）
8. scipy fit 无显式收敛诊断（silent → fallback）

参考文献

McNeil-Frey (2000) EVT for financial VaR + Coles (2001) Statistical Modeling of Extreme Values + Embrechts-Klüppelberg-Mikosch (1997) Modelling Extremal Events + Pickands (1975) Pickands-Balkema-de Haan theorem。详见 frontmatter。

Golden Test

tests/golden/fixtures/tier3/evt_tail_var/，scipy reference。1e-6 tolerance。11 tests：

• fat_tail_student_t — t(df=4) 500 obs → positive shape
• normal_returns_99 — near-zero shape, ≈ historical_var
• normal_returns_95 — 同数据不同 confidence → 不同 VaR
• injected_outliers — 5 固定 extreme losses → shape ≈ 0.6, ES >> VaR
• too_short_returns — < 30 obs → error
• insufficient_exceedances — threshold=0.99 → < 5 exceedances → error
• determinism — 5 reruns 一致
• confidence_monotonic — VaR(0.9) < VaR(0.95) < VaR(0.99)
• rounding_contract — round 6 values / round 4 shape
• result_structure_primary — 9 fixed keys
• n_exceedances_positive — > 5; threshold 精确匹配

Changelog

• 1.0.0 (2026-04-20) — 首次 Active（Tier 3 batch 2.3）