At1uri/markov-switching-autoregressive-engine

⚡ Hamilton Markov-Switching Autoregressive Engine

A statistical machine learning and econometric inference engine developed by Ramprasad Atluri implementing the Hamilton (1989) forward filter and Kim (1994) backward smoothing algorithm for non-linear market regime detection.

📌 Mathematical & Econometric Architecture

Financial asset returns exhibit state-dependent structural shifts in both conditional mean and conditional variance (heteroskedasticity). This model parametrizes market dynamics as a 3-State Markov-Switching Autoregressive model $\text{MS}(3)\text{-AR}(1)$:

$$y_t-{\mu }_{S_t}={\varphi }_{S_t}(y_{t-1}-{\mu }_{S_{t-1}})+{ϵ}_t,{ϵ}_t\sim \text{i.i.d.}\mathcal{N}(0,{\sigma }_{S_t}^2)y\_t\; -\; \backslash mu\_\{S\_t\}\; =\; \backslash phi\_\{S\_t\}\; (y\_\{t-1\}\; -\; \backslash mu\_\{S\_\{t-1\}\})\; +\; \backslash epsilon\_t,\; \backslash quad\; \backslash epsilon\_t\; \backslash sim\; \backslash text\{i.i.d.\}\; \backslash ,\; \backslash mathcal\{N\}(0,\; \backslash sigma\_\{S\_t\}^2)$$

Where $S_t \in {0, 1, 2}$ represents the unobserved latent market regime governed by a first-order Markov chain with transition probability kernel $\mathbf{P}$:

Unconditional Ergodic Distribution ($\boldsymbol{\pi}$):

The stationary unconditional distribution solves the eigensystem $(\mathbf{P}^\top - \mathbf{I})\boldsymbol{\pi} = \mathbf{0}$ subject to $\mathbf{1}^\top \boldsymbol{\pi} = 1$:

$$\mathit{\pi }=\left[\begin{array}{c}0.5342\\ 0.3581\\ 0.1077\end{array}\right]⟹\{\begin{array}{l}\mathbb{P}(\text{Expansion})=53.4\mathrm{\%}\\ \mathbb{P}(\text{Consolidation})=35.8\mathrm{\%}\\ \mathbb{P}(\text{Turbulent Cascade})=10.8\mathrm{\%}\end{array}\backslash boldsymbol\{\backslash pi\}\; =\; \backslash begin\{bmatrix\}\; 0.5342\; \backslash \backslash \; 0.3581\; \backslash \backslash \; 0.1077\; \backslash end\{bmatrix\}\; \backslash implies\; \backslash begin\{cases\}\; \backslash mathbb\{P\}(\backslash text\{Expansion\})\; =\; 53.4\backslash \%\; \backslash \backslash \; \backslash mathbb\{P\}(\backslash text\{Consolidation\})\; =\; 35.8\backslash \%\; \backslash \backslash \; \backslash mathbb\{P\}(\backslash text\{Turbulent\; Cascade\})\; =\; 10.8\backslash \%\; \backslash end\{cases\}$$

---

🔬 Recursive Filter Formulation

1. Hamilton Forward Filter (1989)

The filtered inference $\hat{\xi}_{t|t} = \mathbb{P}(S_t = k \mid \mathcal{F}_t)$ is computed recursively:

$${\widehat{\xi }}_{t\mathrm{\mid }t-1}={\mathbf{P}}^{\mathrm{\top }}{\widehat{\xi }}_{t-1\mathrm{\mid }t-1}\backslash hat\{\backslash xi\}\_\{t|t-1\}\; =\; \backslash mathbf\{P\}^\backslash top\; \backslash hat\{\backslash xi\}\_\{t-1|t-1\}$$

$${\widehat{\xi }}_{t\mathrm{\mid }t}=\frac{{\widehat{\xi }}_{t\mathrm{\mid }t-1}\odot {\mathit{\eta }}_t}{{\mathbf{1}}^{\mathrm{\top }}({\widehat{\xi }}_{t\mathrm{\mid }t-1}\odot {\mathit{\eta }}_t)}\backslash hat\{\backslash xi\}\_\{t|t\}\; =\; \backslash frac\{\backslash hat\{\backslash xi\}\_\{t|t-1\}\; \backslash odot\; \backslash boldsymbol\{\backslash eta\}\_t\}\{\backslash mathbf\{1\}^\backslash top\; (\backslash hat\{\backslash xi\}\_\{t|t-1\}\; \backslash odot\; \backslash boldsymbol\{\backslash eta\}\_t)\}$$

Where $\boldsymbol{\eta}_t = [f(y_t \mid S_t = 0), f(y_t \mid S_t = 1), f(y_t \mid S_t = 2)]^\top$ represents the conditional Gaussian density vector.

2. Kim Backward Smoother (1994)

Full-sample smoothed inferences $\hat{\xi}_{t|T} = \mathbb{P}(S_t = k \mid \mathcal{F}_T)$ conditioning on all past and future observations:

$${\widehat{\xi }}_{t\mathrm{\mid }T}={\widehat{\xi }}_{t\mathrm{\mid }t}\odot \left(\mathbf{P}[{\widehat{\xi }}_{t+1\mathrm{\mid }T}\oslash {\widehat{\xi }}_{t+1\mathrm{\mid }t}]\right)\backslash hat\{\backslash xi\}\_\{t|T\}\; =\; \backslash hat\{\backslash xi\}\_\{t|t\}\; \backslash odot\; \backslash left(\; \backslash mathbf\{P\}\; \backslash left[\; \backslash hat\{\backslash xi\}\_\{t+1|T\}\; \backslash oslash\; \backslash hat\{\backslash xi\}\_\{t+1|t\}\; \backslash right]\; \backslash right)$$

---

🚀 Quick Start in Python

from huggingface_hub import hf_hub_download
import numpy as np
import json

# Download calibrated parameter tensors
weights_path = hf_hub_download(
    repo_id="At1uri/markov-switching-autoregressive-engine",
    filename="calibrated_parameters.json"
)

with open(weights_path, "r") as f:
    params = json.load(f)

print("Transition Matrix P:\n", np.array(params["transition_matrix_P"]))
print("Log-Likelihood:", params["log_likelihood"])

Full Inference with hamilton_filter.py:

from hamilton_filter import HamiltonRegimeSwitchingFilter

# Initialize pre-calibrated engine
engine = HamiltonRegimeSwitchingFilter.load_pretrained()

# Example return series (e.g. daily S&P 500 or Bitcoin returns)
returns = np.array([0.004, -0.012, 0.003, -0.035, -0.018, 0.001])

# Run forward filter and Kim backward smoother
filtered_probs, predicted_probs = engine.forward_filter(returns)
smoothed_probs = engine.kim_smoother(filtered_probs, predicted_probs)

print("Current Filtered Regime Probabilities [Exp, Cons, Turb]:", filtered_probs[-1])
print("Smoothed Probabilities:", smoothed_probs[-1])

📊 Calibrated State Parameter Estimates

Metric	State 0 (Expansion)	State 1 (Consolidation)	State 2 (Turbulent)
Drift ($\mu$)	$+0.081% / \text{day}$	$+0.011% / \text{day}$	$-0.185% / \text{day}$
AR Coefficient ($\phi_1$)	$+0.0421$	$-0.0894$	$+0.1582$
Annualized Volatility ($\sigma_{\text{ann}}$)	$12.69%$	$22.22%$	$55.55%$
Expected Half-Life / Duration	$25.12 \text{ days}$	$12.69 \text{ days}$	$6.34 \text{ days}$

⚖️ License

MIT License. Free for proprietary trading, risk management, and econometric research.