做什么（One-liner）

完整 Primiceri (2005) 贝叶斯 MCMC TVP-SVAR：β_t + A_t + log σ_t 三组状态方程全部随机游走，Gibbs 采样器循环 Carter-Kohn simulation smoother + KSC 1998 stochastic volatility + Inverse-Wishart 超参。输出 5%/50%/95% 后验分位数带——有 uncertainty bands 的 TVP-VAR。

怎么用

直接 Python：

from services.mfle.tvp_svar_primiceri import fit_tvp_svar_primiceri
result = fit_tvp_svar_primiceri(
    df,                           # 时间-index macro DataFrame
    lag=2,
    n_iter=5000, burn_in=2000,   # production settings
    thin=3,                       # reduce autocorr
    policy_column='FEDFUNDS',
    irf_horizon=20,
    seed=42,
)
# result['irf_median'], result['irf_q05'], result['irf_q95']
# result['sigma_final_median'] + CI bands
# result['converged_ess'], result['geweke_z_max_abs']

NOT a Canvas graphlet — 2-5 min per fit. Use tvp_var_kk for Canvas.

核心公式

# Primiceri 2005 full specification:
y_t = c_t + B₁ₜ y_{t-1} + ... + Bₚₜ y_{t-p} + u_t
u_t = Aₜ⁻¹ Σₜ εₜ,  εₜ ~ N(0, I)
Σₜ = diag(σ₁ₜ, ..., σ_Mt)

# State equations (random walk):
vec(B_t) = vec(B_{t-1}) + v_t,  Q
a_t      = a_{t-1}      + ζ_t,  S
log σ_t  = log σ_{t-1}  + η_t,  W

# Gibbs sampler (Del Negro-Primiceri 2015 corrected order):
Step 1: B_t  | y, A, Σ, Q  via Carter-Kohn
Step 2: a_t  | y, B, Σ, S  via Carter-Kohn on structural residuals
Step 3: log σ_t  | y, B, A, W  via KSC offset mixture
Step 4: Q, S, W  | states  via Inverse-Wishart posteriors

# Key numerical detail (bug #1 fix):
# KSC Table 4 mixture is MEAN-CENTERED (∑ pⱼμⱼ ≈ 0)
# log(ε²) has E = -1.2704 (digamma(½) + log 2)
# Correct: y_star := log(r²) + 1.2704 = 2h + ξ_KSC
# (缺 +1.2704 → σ 系统低估 × 0.53)

LDL-native Cholesky structure: Σₜ = Aₜ⁻¹ diag(σₜ²) Aₜ⁻ᵀ is LDL form natively. Construct Cholesky factor = Aₜ⁻¹ @ diag(σₜ) directly — avoids sqrt on full Σ.

假设与适用场景

假设：VAR(p) + 所有状态随机游走 + Gaussian residuals + Cholesky ID + T > training+lag+20 + numpy/scipy pinned。

适用：货币政策传导严谨分析（带 uncertainty bands）、policy shock attribution、结构 A 时变演化、监管 IRF 报告、研究级 TVP 轨迹。

不适用：Canvas 实时（用 tvp_var_kk）、intraday、M>5 大系统、sign/long-run restrictions。

输入 / 输出契约

(df, lag=2, n_iter=2000, burn_in=500, thin=2, training_size?, policy_column?, irf_horizon=20, prior_scale_factor=0.01, seed=42) →

所有后验统计量 median/q05/q95 triplet：

• sigma_final_*: (M,) σ_T posterior
• beta_final_*: (K,) β_T posterior
• A_final_*: (M, M) lower-triangular A_T posterior
• irf_*: (horizon+1, M, M) structural IRF posterior

加 收敛诊断: geweke_z_max_abs, ess_min, converged_geweke/ess, per-σ diagnostics.

已知局限

1. 每次 fit 2-5 分钟 — 不适合 Canvas real-time；用 tvp_var_kk 代替
2. β chain Gibbs 自相关强（标准 TVP-VAR 问题，不是 bug）
3. 单链采样 — 多链 r̂ 靠 pymc cross-validator
4. Geweke anti-conservative — ESS 为首要收敛指标
5. prior_scale_factor=0.01 固定（Primiceri §4.1）；非数据驱动
6. Cholesky ordering 对 policy_column 位置敏感
7. 无 auto-convergence stop — 用户须自行选 n_iter
8. 仅递归 Cholesky — 无 sign / long-run restrictions
9. Bug 修复透明历史: KSC offset + self-ref prior（见 changelog + fixture_meta hand-trace）

参考文献

• Primiceri (2005) ReStud — 主模型
• Del Negro-Primiceri (2015) 勘误 — Gibbs 顺序修正
• Carter-Kohn (1994) Biometrika — simulation smoother
• Kim-Shephard-Chib (1998) ReStud — 7-component mixture
• Geweke (1992) — 收敛 z-test
• Cook-Gelman-Rubin (2006) JCGS — simulation-based calibration

Golden Test

tests/golden/fixtures/tier3/tvp_svar_primiceri/，3 条独立证据链：

Category 1: Determinism（CI-fast, 8 tests）

• 4 scenarios（baseline / seed=123 / insufficient / single_var）
• Contract tests: A 对角=1 / 上三角=0, q05≤median≤q95, convergence diagnostics present
• σ 真值恢复 within 20%（真值 [0.4, 0.3, 0.2]，估计 [0.39, 0.30, 0.19]）

Category 2: Cook-Gelman-Rubin Coverage（pre-computed artifact）

• 15 replications with independent DGPs
• σ 真值覆盖率阈值 ≥ 80%（binomial SE ≈ 10% at N=15）
• Median relative bias < 15%

Category 3: PyMC NUTS Cross-Validation（pre-computed artifact）

• 两套独立实现 σ posterior medians 差异 < 2% (观测实际)
• 90% credible intervals 全部重叠
• A structural matrix max abs diff < 0.02
• pymc r̂ = 1.01 ✓, hand-coded Geweke ✓

总测试数 17 (8 determinism + 4 coverage + 5 pymc crossval)。

Changelog

• 1.0.0 (2026-04-21) — 首次 Active；2 bugs fixed transparent in changelog；3 条独立验证证据链