做什么（One-liner）

Koop-Korobilis (2013) 遗忘因子 Kalman filter 的 时变参数 VAR：β_t 连续演化（不像 MS 的有限 regime 跳变）+ EWMA 时变协方差 Σ_t + Cholesky 识别 + 结构冲击 IRF + 预测误差方差分解 (FEVD)。央行主流方法。

怎么用

直接 Python：

from services.mfle.tvp_var_kk import fit_tvp_var_kk
result = fit_tvp_var_kk(
    df,                              # 宏观 DataFrame
    lag=2,                           # VAR(2)
    forgetting_lambda=0.97,          # β 变化速度
    ewma_kappa=0.96,                 # Σ 平滑
    policy_column='FEDFUNDS',        # 政策变量（移到最后）
    irf_horizon=20,                  # IRF 时间跨度
)
# result['irf'] shape = (21, M, M)
# result['fevd'] shape = (21, M, M)
# result['beta_trajectory'] 显示时变系数演化

Canvas（Phase B+ 将通过 tvp_var_v1 graphlet 暴露）。

核心公式

# 状态方程：
y_t = Z_t β_t + ε_t,   ε_t ~ N(0, Σ_t)
β_t = β_{t-1} + η_t,   η_t ~ N(0, Q_t)

# Koop-Korobilis 关键简化：
P_{t|t-1} = (1/λ) P_{t-1|t-1}    # 遗忘因子替代 Q 采样
Σ_t = κ Σ_{t-1} + (1-κ) ê_t ê_t'  # EWMA 替代 SV

# IRF (Cholesky + companion form):
L = chol(Σ_T)
A = companion_matrix(β_T)
IRF[h] = A^h 前 M 行 ⊗ [L; 0]

# FEVD: cumsum(IRF²) / rowsum

假设与适用场景

假设：VAR(p) 线性 + β_t 随机游走 + Σ_t 平稳 EWMA + Cholesky 识别 + T > training + lag + 5 + M ≥ 2。

适用：货币政策传导、跨资产宏观冲击路径、时变敏感度分析、Canvas 结构性宏观节点。

不适用：需要 MCMC uncertainty bands（用 Primiceri 版本）、严格 stochastic vol、sign restrictions 识别、intraday、样本 < 40 obs。

输入 / 输出契约

(df, lag=2, forgetting_lambda=0.97, ewma_kappa=0.96, training_size?, policy_column?, irf_horizon=20) → {method, M, p, T_filtered, training_size, forgetting_lambda, ewma_kappa, irf_horizon, variables, policy_column, policy_shock_idx, beta_final (M,K_per), sigma_final (M,M), beta_trajectory (T_filtered,K), sigma_diag_trajectory (T_filtered,M), irf (horizon+1,M,M), fevd (horizon+1,M,M)}

已知局限

1. 无 MCMC uncertainty bands — 只给点估计；用 tvp_svar_primiceri 获 5%/50%/95% 后验分位数
2. EWMA 是 SV 简化 — 严格 log-σ² 随机游走用 Primiceri
3. Cholesky 对 policy 位置敏感 — 用户须理解 ordering 语义
4. λ, κ 是超参 — 无交叉验证，默认值来自 Koop-Korobilis 推荐
5. β_t 随机游走假设 — 若 DGP 是 regime-switching，用 MS-AR (detect_regime)
6. OLS prior 依赖 training_size — 太小过噪，太大压缩 Kalman 覆盖
7. VAR(p=5+) 计算成本 — 伴随矩阵 Mp × Mp 扩大，A^h 成本 O(h·M³p³)
8. 不支持 VARX — 当前仅自回归
9. Joseph-form 协方差更新 — 数值稳定但略慢

参考文献

Koop-Korobilis (2013) Large TVP-VARs + Raftery-Kárný-Ettler (2010) forgetting factor + Primiceri (2005) TVP-SVAR motivation + Lütkepohl (2005) VAR 教科书 + Sims (1980) Macroeconomics and Reality + Bierman (1977) factorization methods。详见 frontmatter。

Golden Test

tests/golden/fixtures/tier3/tvp_var_kk/，numpy_manual reference + 结构不变量 contract tests。1e-6 tolerance。15 tests：

7 Scenarios

• macro_4var_baseline — 4 变量 VAR(2) + FEDFUNDS policy，央行标配
• stationary_2var_lag1 — 最小 2 变量 VAR(1)，测核心数学
• regime_shift_3var — 半程 vol 转变，λ=0.95 快速适应
• high_forgetting_lambda_099 — λ=0.99 慢变
• low_forgetting_lambda_095 — λ=0.95 快变
• insufficient_data — < 训练 + lag + 5，错误路径
• single_variable — M=1，错误路径

8 Contract Tests

• determinism — 5 reruns 字节一致（无 MCMC）
• fevd_cholesky_row_zero_is_one_shock — Cholesky ID 下第一个变量 100% 由第一个冲击驱动
• fevd_rows_sum_to_one — 每 (h, i) 行和严格 = 1.0
• irf_shape_locked — (horizon+1, M, M) contract
• policy_column_moved_last — Cholesky ordering 语义
• lambda_sensitivity_smooth_vs_fast — λ 0.99 vs 0.93 系数移动量严格单调
• training_size_prior_stability — 前 training_size 期 β 严格相同
• method_enum_contract — method ∈ 2 个允许值

Changelog

• 1.0.0 (2026-04-21) — 首次 Active（Tier 3 新增 Koop-Korobilis TVP-VAR；与 Primiceri Bayesian MCMC 版本为姐妹 operator）