Unscented Kalman Filter
Install and import#
npm install fintech-algorithmsimport { runFilter } from "fintech-algorithms/statistical-time-series/state-and-regime-models/unscented-kalman-filter";Signature#
runFilter(observations, config)Propagates a set of deterministically chosen sigma points through the non-linearity instead of linearising it. More robust than the extended filter for the same cost order, and the usual answer when the EKF diverges.
Parameters#
| Name | Type | Notes |
|---|---|---|
observations | number[] | Noisy observations. |
config | { a, b, c, q, r, alpha, beta, kappa, initial_mean, initial_variance } | alpha, beta and kappa control the sigma-point spread. beta = 2 is optimal for Gaussian state distributions; alpha is normally small. |
Returns#
{ …per-step estimates }[]
Per-step estimates with the sigma-point statistics behind them.
Errors#
- When the sigma-point parameters produce a non-positive-definite covariance — throws
Complexity: time O(n),
space O(n).
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#
[0.1740564489, 0.7180957323, 0.0365723689]{
"a": 0.9,
"b": 0.22,
"c": 0.04,
"q": 0.06,
"r": 0.49,
"alpha": 1,
"beta": 2,
"kappa": 0,
"initial_mean": 0,
"initial_variance": 1.5
}Call#
runFilter(observations, config)Returns#
object with 1 field: 2
{
"2": {
"index": 2,
"sigma_left": -0.0995315114397366,
"sigma_center": 0.4049746384367636,
"sigma_right": 0.9094807883132638,
"predicted_mean": 0.4403571228780741,
"predicted_variance": 0.36471237345744356,
"predicted_measurement": 0.46270219364315,
"innovation": -0.42612982474315003,
"innovation_variance": 0.8812872395279235,
"kalman_gain": 0.4284195343347881,
"filtered_mean": 0.2577947817954489,
"filtered_variance": 0.20295800755826507
}
}Diagrams#
Calculation flow#
Unscented Kalman Filter 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.
References#
- Unscented Filtering and Nonlinear Estimation — Simon J. Julier and Jeffrey K. Uhlmann
- Bayesian Filtering and Smoothing — Simo Särkkä and Lennart Svensson
- A New Approach to Linear Filtering and Prediction Problems — R. E. Kalman
- Time Series Analysis by State Space Methods — statsmodels developers