spb/wp46_uqo

1# Model card — `msgarch2` (two-regime Markov-switching GARCH, Haas–Mittnik–Paolella)23## 1. Identity4- **model_id:** `msgarch2` · **family:** regime-switching · **tier:** A · **status:** implemented · **impl:** custom (`src/wp46/models/custom.py::MSGARCH2`)5- **Label:** MS-GARCH(2) (Haas-Mittnik-Paolella) · **distributions:** normal, t (common ν across regimes) · registry note: "regimes ordered by unconditional variance"6- **Seminal citation:** `haas2004new`7- **Other references:** `hamilton1989new` (filter), `gray1996modeling`, `klaassen2002improving` (collapsing MS-GARCH — different likelihoods, not implemented), `bauwens2010theory`, `augustyniak2014maximum` (path-dependent MS-GARCH, out of scope), `ardia2019markov`/`ardia2016msgarch` (MSGARCH R package implementing the HMP form), `ardia2018forecasting`, `marcucci2005forecasting` (benchmarks).89## 2. Definition10Regime $S_t \in \{1,2\}$, first-order Markov chain with $P(S_t = 1 \mid S_{t-1} = 1) = p_{11}$, $P(S_t = 2 \mid S_{t-1} = 2) = p_{22}$; two parallel GARCH(1,1) variances driven by the common innovation:11$$r_t = \mu + \varepsilon_t,\qquad \sigma_{k,t}^2 = \omega_k + \alpha_k\,\varepsilon_{t-1}^2 + \beta_k\,\sigma_{k,t-1}^2,\ k = 1,2,\qquad \varepsilon_t \mid S_t = k,\ \mathcal F_{t-1} \sim \sigma_{k,t} z_t ,$$12$z_t$ N(0,1) or standardised Student-t with a **common** ν. `hamilton_msgarch`: $\sigma_{k,0}^2 = s_0$ (backcast) for both regimes, prior $P(S_0 = 1) = \pi_1 = (1-p_{22})/(2 - p_{11} - p_{22})$ (ergodic distribution), Hamilton filter with log-sum-exp; the log-likelihood is $\sum_t \log\big[\sum_k P(S_t = k\mid\mathcal F_{t-1})\,f_k(\varepsilon_t)\big]$. Identification: regime 1 = lower unconditional variance $u_k = \omega_k/(1-\alpha_k-\beta_k)$.1314## 3. Parameter space and admissibility15- Parameters: `mu, p11, p22, omega1, alpha1, beta1, omega2, alpha2, beta2` (+ `nu`).16- Reparameterisation: $p_{11}, p_{22} = \sigma(\theta)$; per regime $\omega_k = e^{\theta}$, $\alpha_k + \beta_k = \sigma(\theta) \in (0,1)$, $\alpha_k = (\alpha_k+\beta_k)\,\sigma(\theta')$ — so each regime is covariance stationary by construction.17- Identification constraint $u_1 \le u_2$ enforced by a **soft penalty** added to the negative log-likelihood: $50\,(\ln u_1 - \ln u_2)$ when $u_1 > u_2$ (the reported `loglik` = −objective therefore includes the penalty if it is active at the optimum).18- Admissibility flag: $\omega_1, \omega_2 > 0$, $0 < p_{11}, p_{22} < 1$. The HMP stationarity condition for the mixture (spectral radius of the regime-weighted persistence matrix < 1) is not computed; per-regime $\alpha_k + \beta_k < 1$ is sufficient for it.1920## 4. Nesting and relations21Collapses to `garch11` when the two regimes have identical parameters or when $p_{11} \to 1$ (absorbing). HMP form: regime variances depend only on past $\varepsilon^2$ (no path dependence), unlike Gray/Klaassen (collapsing) or `bauwens2010theory` (path-dependent) — literature-matrix caveat #6. `stgarch` (unsupported) is the smooth-transition analogue.2223## 5. Estimation24Custom MLE (`CustomModel.fit` with `MSGARCH2._negll`): L-BFGS-B on θ (maxiter 2000) from three starts: (p11, p22, ω1, α1, β1, ω2, α2, β2) ∈ {(0.98, 0.97, 0.04v, 0.03, 0.90, 0.30v, 0.10, 0.80), (0.95, 0.95, 0.03v, 0.05, 0.85, 0.30v, 0.15, 0.75), (0.99, 0.99, 0.035v, 0.02, 0.93, 0.15v, 0.08, 0.85)} with $v = \operatorname{var}(r)$; Nelder–Mead polish on failure; μ start = sample mean, ν start 6; backcast $s_0$ arch-style. Point estimates only. `filter` returns the one-step predictive mixture variance $E[\sigma_t^2 \mid \mathcal F_{t-1}] = \pi_{1,t|t-1}\sigma_{1,t}^2 + (1-\pi_{1,t|t-1})\sigma_{2,t}^2$.2526## 6. Forecasting27`MSGARCH2.forecast` (documented in the class as the HMP recursion): with $\boldsymbol\pi_t = (P(S_t=1\mid\mathcal F_t), P(S_t=2\mid\mathcal F_t))$ from the filter, $\mathbf P$ the transition matrix, and $\sigma_{k,t+1}^2 = \omega_k + \alpha_k\varepsilon_t^2 + \beta_k\sigma_{k,t}^2$,28$$\boldsymbol\pi_{t+j|t} = \boldsymbol\pi_t\mathbf P^{j},\qquad \hat\sigma^2_{t+j|t} = \sum_k \pi_{k,t+j|t}\,\hat\sigma^2_{k,t+j},\qquad \hat\sigma^2_{k,t+j+1} = \omega_k + \alpha_k\,\hat\sigma^2_{t+j|t} + \beta_k\,\hat\sigma^2_{k,t+j},$$29for $j = 1..22$ (`e2f = out[j]` feeds both regime recursions). The code treats $E[\varepsilon^2_{t+j}\mid\mathcal F_t]$ as the marginal-probability mixture of the regime variances; whether this coincides with the exact HMP multi-step expression (which conditions the future regime and the regime variances jointly) is **not verified here** — recorded in `_discrepancies.md`. Cumulative = sum over j ≤ h. Method: `analytic`. The forecast object also carries `regime_probs` ($\boldsymbol\pi_{t+22|t}$) and `regime_var`.3031## 7. Implementation32- `src/wp46/models/custom.py::MSGARCH2` (numba `hamilton_msgarch`).33- Cross-check: **none against a library** (MSGARCH R package not run; not in `results/metrics/rugarch_crosscheck.json`).34- Tests: `tests/unit/test_custom_models.py::test_msgarch_two_regimes_ordered_and_forecast_positive` (converged, $u_1 \le 1.01\,u_2$, positive 22-step forecasts), `test_no_lookahead_in_forecasts` (normal); `tests/simulation/test_recovery.py::test_msgarch_recovery_regime_separation` (T = 6,000, P = [[0.98, 0.02],[0.03, 0.97]], regimes (0.02, 0.03, 0.90)/(0.3, 0.10, 0.80): recovers $p_{11}, p_{22} > 0.9$ and $u_2/u_1 > 3$).3536## 8. Known limitations / failure modes37Multimodal likelihood (label switching handled by the soft penalty, which can bias the reported log-likelihood when active); a regime can degenerate (p_kk → 1 or ω_k → 0) → flat likelihood, slow convergence, boundary optima; common ν only; no stationarity flag for the mixture; the Hamilton filter costs a full pass with two GARCH recursions per likelihood evaluation; multi-step recursion caveat above.3839## 9. Computational footprint40Analytic forecasts; 9–10 parameters; Hamilton filter per evaluation (≈ 3× the cost of a GARCH(1,1) evaluation plus more iterations). Not in the pilot; expected to be among the slowest Tier A estimations with `figarch11` and `aparch11`.4142## 10. Literature expectations43`marcucci2005forecasting`: MS-GARCH beats single-regime GARCH at short horizons only on S&P 100; `ardia2018forecasting` (426 assets): MS-GARCH improves VaR/ES and density forecasts rather than point variance accuracy; `haas2004new` show the analytic tractability of the parallel-process form. Expectation (H4, H6): gains concentrated at h = 1 in regime transitions and in tail-risk evaluation, with higher failure rates (H5).44