What (One-liner)

The full Primiceri (2005) Bayesian MCMC TVP-SVAR: β_t + A_t + log σ_t all random-walk, with a Gibbs sampler cycling the Carter-Kohn simulation smoother + KSC 1998 stochastic volatility + Inverse-Wishart hyperparameters. Outputs 5%/50%/95% posterior bands — the TVP-VAR with uncertainty bands.

How to use

Direct Python:

from services.mfle.tvp_svar_primiceri import fit_tvp_svar_primiceri
result = fit_tvp_svar_primiceri(
    df,                           # time-indexed 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 minutes per fit. Use tvp_var_kk on Canvas.

Core formulas

# 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 the KSC offset mixture
Step 4: Q, S, W  | states  via Inverse-Wishart posteriors

# Key numerical detail (bug #1 fix):
# The 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
# (omitting +1.2704 → σ biased down ×0.53)

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

Assumptions & applicability

Assumptions: VAR(p) + all states random-walk + Gaussian residuals + Cholesky ID + T > training+lag+20 + numpy/scipy pinned.

Fits: rigorous monetary-transmission analysis (with uncertainty bands), policy shock attribution, time-varying structural A, regulatory IRF reporting, research-grade TVP trajectories.

Does not fit: real-time Canvas (use tvp_var_kk), intraday, M>5 systems, sign/long-run restrictions.

Input / Output contract

(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) →

All posterior statistics as median/q05/q95 triplets:

• 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

Plus convergence diagnostics: geweke_z_max_abs, ess_min, converged_geweke/ess, per-σ diagnostics.

Known limitations

1. 2-5 minutes per fit — not for real-time Canvas; use tvp_var_kk instead
2. Strong β-chain Gibbs autocorrelation (a standard TVP-VAR issue, not a bug)
3. Single-chain sampling — multi-chain r̂ via the pymc cross-validator
4. Geweke anti-conservative — ESS is the primary convergence indicator
5. prior_scale_factor=0.01 fixed (Primiceri §4.1); not data-driven
6. Cholesky ordering sensitive to policy_column position
7. No auto-convergence stop — users pick n_iter themselves
8. Recursive Cholesky only — no sign / long-run restrictions
9. Transparent bug-fix history: the KSC offset + the self-referential prior (see the changelog + the fixture_meta hand-trace)

References

• Primiceri (2005) ReStud — the main model
• Del Negro-Primiceri (2015) corrigendum — the Gibbs-ordering correction
• Carter-Kohn (1994) Biometrika — the simulation smoother
• Kim-Shephard-Chib (1998) ReStud — the 7-component mixture
• Geweke (1992) — the convergence z-test
• Cook-Gelman-Rubin (2006) JCGS — simulation-based calibration

Golden Test

tests/golden/fixtures/tier3/tvp_svar_primiceri/ — three independent evidence chains:

Category 1: Determinism (CI-fast, 8 tests)

• 4 scenarios (baseline / seed=123 / insufficient / single_var)
• Contract tests: A diagonal=1 / upper-triangle=0, q05≤median≤q95, convergence diagnostics present
• True-σ recovery within 20% (truth [0.4, 0.3, 0.2], estimates [0.39, 0.30, 0.19])

Category 2: Cook-Gelman-Rubin Coverage (pre-computed artifact)

• 15 replications with independent DGPs
• True-σ coverage threshold ≥ 80% (binomial SE ≈ 10% at N=15)
• Median relative bias < 15%

Category 3: PyMC NUTS Cross-Validation (pre-computed artifact)

• σ posterior medians of two independent implementations within < 2% (observed)
• All 90% credible intervals overlapping
• Structural A max abs diff < 0.02
• pymc r̂ = 1.01 ✓, hand-coded Geweke ✓

Total 17 tests (8 determinism + 4 coverage + 5 pymc crossval).

Changelog

• 1.0.0 (2026-04-21) — First Active; 2 bugs fixed transparently in the changelog; three independent validation evidence chains