kalman_filter¶

Defined in fynance.features.filters

kalman_filter(y, G, F, W, V, m0=None, C0=None)[source]

Linear Gaussian Kalman filter.

Recursive Bayesian estimator for the latent state x_t of a linear Gaussian state-space model. At each step, the prior obtained from the dynamics G is updated with the new observation through the Kalman gain, yielding the posterior. The output is causal — only past and present observations are used — making the filter suitable for live signal extraction. For an offline smoothed estimate that also conditions on future observations, run rts_smoother on the returned m, C, a, R.

Implementation is JIT-compiled with Numba; the first call incurs a one-off compilation cost.

State-space model:

x_t = G @ x_{t-1} + w_t,   w_t ~ N(0, W)
y_t = F @ x_t    + v_t,   v_t ~ N(0, V)

Alternates between a predict step (prior a, R) and an update step (posterior m, C).

Parameters:

ynp.ndarray of shape (T, n): Observed data.
Gnp.ndarray of shape (n, n): State transition matrix.
Fnp.ndarray of shape (n, n): Observation matrix.
Wnp.ndarray of shape (n, n): Process noise covariance.
Vnp.ndarray of shape (n, n): Observation noise covariance.
m0np.ndarray of shape (n,), optional: Initial state mean (default: zeros).
C0np.ndarray of shape (n, n), optional: Initial state covariance (default: identity).

Returns:

mnp.ndarray of shape (T, n): Filtered state means (posterior).
Cnp.ndarray of shape (T, n, n): Filtered state covariances (posterior).
anp.ndarray of shape (T, n): Prior state means (predict step).
Rnp.ndarray of shape (T, n, n): Prior state covariances (predict step).
enp.ndarray of shape (T, n): Innovations y_t - F @ a_t.
Snp.ndarray of shape (T, n, n): Innovation covariances F @ R_t @ F.T + V.

References

R. E. Kalman, “A New Approach to Linear Filtering and Prediction Problems”, Journal of Basic Engineering, 1960.

Examples

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> y = rng.standard_normal((5, 1))
>>> G = F = W = V = np.eye(1)
>>> m, C, a, R, e, S = kalman_filter(y, G, F, W, V)
>>> m.shape
(5, 1)
>>> C.shape
(5, 1, 1)
>>> e.shape
(5, 1)