What (One-liner)

The Koop-Korobilis (2013) forgetting-factor Kalman time-varying-parameter VAR: β_t evolves continuously (unlike MS's finite regime jumps) + EWMA time-varying Σ_t + Cholesky identification + structural IRFs + FEVD. The central-bank mainstream method.

How to use

Direct Python:

from services.mfle.tvp_var_kk import fit_tvp_var_kk
result = fit_tvp_var_kk(
    df,                              # macro DataFrame
    lag=2,                           # VAR(2)
    forgetting_lambda=0.97,          # β change speed
    ewma_kappa=0.96,                 # Σ smoothing
    policy_column='FEDFUNDS',        # policy variable (moved last)
    irf_horizon=20,                  # IRF horizon
)
# result['irf'] shape = (21, M, M)
# result['fevd'] shape = (21, M, M)
# result['beta_trajectory'] shows the coefficient evolution

Canvas exposure via the tvp_var_v1 graphlet arrives with Phase B+.

Core formulas

# State equations:
y_t = Z_t β_t + ε_t,   ε_t ~ N(0, Σ_t)
β_t = β_{t-1} + η_t,   η_t ~ N(0, Q_t)

# The Koop-Korobilis key simplifications:
P_{t|t-1} = (1/λ) P_{t-1|t-1}    # forgetting factor replaces Q sampling
Σ_t = κ Σ_{t-1} + (1-κ) ê_t ê_t'  # EWMA replaces SV

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

# FEVD: cumsum(IRF²) / rowsum

Assumptions & applicability

Assumptions: linear VAR(p) + β_t random walk + smooth EWMA Σ_t + Cholesky ID + T > training + lag + 5 + M ≥ 2.

Fits: monetary transmission, cross-asset macro shock paths, time-varying sensitivity, Canvas structural macro nodes.

Does not fit: MCMC uncertainty bands (use the Primiceri version), strict stochastic vol, sign restrictions, intraday, samples < 40 obs.

Input / Output contract

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

Known limitations

1. No MCMC uncertainty bands — point estimates only; tvp_svar_primiceri gives 5%/50%/95% posteriors
2. EWMA is the SV simplification — strict log-σ² random walk lives in Primiceri
3. Cholesky sensitive to policy position — users must grasp the ordering semantics
4. λ, κ are hyperparameters — no cross-validation; defaults per Koop-Korobilis
5. β_t random-walk assumption — for regime-switching DGPs use MS-AR (detect_regime)
6. OLS prior depends on training_size — too small is noisy, too large shrinks Kalman coverage
7. VAR(p=5+) cost — companion matrix Mp × Mp; A^h costs O(h·M³p³)
8. No VARX — autoregressive only
9. Joseph-form update — numerically stable, slightly slower

References

Koop-Korobilis (2013) Large TVP-VARs + Raftery-Kárný-Ettler (2010) forgetting factors + Primiceri (2005) TVP-SVAR motivation + Lütkepohl (2005) VAR textbook + Sims (1980) Macroeconomics and Reality + Bierman (1977) factorization methods. Full citations in the frontmatter.

Golden Test

tests/golden/fixtures/tier3/tvp_var_kk/ — numpy_manual reference + structural-invariant contract tests, 1e-6 tolerance, 15 tests:

7 Scenarios

• macro_4var_baseline — 4-variable VAR(2) + FEDFUNDS policy, the central-bank staple
• stationary_2var_lag1 — minimal 2-variable VAR(1), core math
• regime_shift_3var — mid-sample vol shift, λ=0.95 fast adaptation
• high_forgetting_lambda_099 — λ=0.99 slow change
• low_forgetting_lambda_095 — λ=0.95 fast change
• insufficient_data — < training + lag + 5, error path
• single_variable — M=1, error path

8 Contract Tests

• determinism — 5 reruns byte-identical (no MCMC)
• fevd_cholesky_row_zero_is_one_shock — under Cholesky ID the first variable is 100% driven by the first shock
• fevd_rows_sum_to_one — every (h, i) row sums exactly to 1.0
• irf_shape_locked — the (horizon+1, M, M) contract
• policy_column_moved_last — Cholesky ordering semantics
• lambda_sensitivity_smooth_vs_fast — coefficient movement strictly monotone between λ 0.99 vs 0.93
• training_size_prior_stability — β strictly identical over the first training_size periods
• method_enum_contract — method ∈ the 2 allowed values

Changelog

• 1.0.0 (2026-04-21) — First Active (the new Tier 3 Koop-Korobilis TVP-VAR; sister operator to the Primiceri Bayesian MCMC version)