fintech-algorithms
/
Using a coding agent? Give it the skill: npx skills add IslamBaraka90/Fintech-Algorithms-Library What it does →

Markov-Switching Autoregression

Install and import#

bash
npm install fintech-algorithms
ts
import { runFilter } from "fintech-algorithms/statistical-time-series/state-and-regime-models/markov-switching-autoregression";

Signature#

runFilter(observations, config)

An autoregression whose coefficients switch with a hidden regime. Captures the common situation where a series is persistent in calm conditions and mean-reverting in stressed ones — one AR fit across both describes neither.

Parameters#

NameTypeNotes
observationsnumber[]Observations in chronological order.
config{ transition: number[][]; intercepts: number[]; phis: number[]; stds: number[]; initial: number[] }One intercept, AR coefficient and standard deviation per regime, plus the transition matrix.

Returns#

{ …per-step filtered probabilities and predictions }[]

Regime probabilities alongside the regime-weighted prediction at each step.

Errors#

  • When the parameter arrays differ in length from the number of regimes — throws

Complexity: time O(n × states²), space O(n × states).

Worked example#

verified This is the worked example published in the article, replayed by the test suite on every run. The output cannot drift.

Input#

observations
[-0.0710447869, 0.2119198541, 0.4036856432]
config
{
  "transition": [
    [0.95, 0.05],
    [0.1, 0.9]
  ],
  "intercepts": [0.12, -0.18],
  "phis": [0.72, -0.3],
  "stds": [0.35, 1.05],
  "initial": [0.85, 0.15]
}

Call#

runFilter(observations, config)

Returns#

object with 1 field: 2

{
  "2": {
    "index": 2,
    "regime_0_forecast": 0.272582294952,
    "regime_1_forecast": -0.24357595623,
    "predicted_state_0": 0.8867587273436667,
    "predicted_state_1": 0.11324127265633334,
    "posterior_state_0": 0.9636140438968227,
    "posterior_state_1": 0.03638595610317732,
    "most_likely_state": 0,
    "next_mixture_forecast": 0.3530523573178951,
    "log_predictive_density": -0.022389779102029245
  }
}

Diagrams#

Markov-Switching Autoregression — diagnostic scorecard
Markov-Switching Autoregression — failure boundary
Markov-Switching Autoregression — family handoff
Markov-Switching Autoregression — scenario comparison
Markov-Switching Autoregression — state update
Markov-Switching Autoregression — uncertainty ledger

Calculation flow#

Markov-Switching Autoregression Causal Update Flow 
flowchart LR
    A["Filtered state at t-1"] --> B["Predict state at t"]
    B --> C["Read observation available at t"]
    C --> D["Compute evidence or innovation"]
    D --> E["Normalize or gain-weight update"]
    E --> F["Filtered state at t"]
    F --> G["Publish diagnostics"]
    F --> A

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

The rest of the State and Regime Models family#

  • Kalman FilterOptimal recursive estimation of a hidden state from noisy observations in a linear Gaussian system.
  • Extended Kalman FilterThe Kalman filter for non-linear systems, linearised at each step.
  • Unscented Kalman FilterPropagates a set of deterministically chosen sigma points through the non-linearity instead of linearising it.
  • Hidden Markov ModelInfers a discrete hidden regime from observations.
  • Bayesian Change-Point DetectionOnline detection of structural breaks by tracking the posterior over run length — how long since the last change.