`KalmanFilter`#

Description#

Scalar 1-D Kalman filter for the classic "noisy random walk" model: state and observation are scalars with unit transition/observation matrices. Useful as an adaptive smoother whose responsiveness is governed by the ratio of process to observation noise.

\[\begin{split} \begin{aligned} \text{predict: } & x_\text{pred} = x_{t-1},\quad P_\text{pred} = P_{t-1} + \sigma^2_p \\ \text{gain: } & K = P_\text{pred} / (P_\text{pred} + \sigma^2_o) \\ \text{update: } & x_t = x_\text{pred} + K \cdot (z_t - x_\text{pred}) \\ & P_t = (1 - K) \cdot P_\text{pred} \end{aligned} \end{split}\]

In the steady state \(K\) converges to a constant determined by \(\sigma^2_p / \sigma^2_o\), at which point the filter behaves like an exponential smoother with that effective \(\alpha\).

Parameters#

process_var (\(\ge 0\)): variance of the random-walk innovations. Larger values make the filter trust new measurements more (responsive but noisier).
observation_var (\(> 0\)): variance of the measurement noise.
initial_state (default 0.0): seed for \(x_0\).
initial_variance (default 1.0): seed for \(P_0\). Pass a large value (e.g. 1e9) to make the filter forget the initial state quickly.

Implementation Details#

Constant-time O(1) per step; no buffer, two scalar state variables (x, P).

NaN handling#

Policy: ignore. A NaN in any input at index t causes the function to skip that step: output at t is NaN and internal state is unchanged. Subsequent finite samples are processed as if step t had not occurred.

Examples#

Usage example#

import numpy as np
from screamer import KalmanFilter

# Noisy observations of a roughly-constant value.
truth = 5.0
obs = truth + np.random.normal(0, 1.0, 200)

# Trust the model more than the measurements (slow / smooth).
kf = KalmanFilter(process_var=0.001, observation_var=1.0)
smoothed = kf(obs)

# Edge cases:
# - process_var -> 0 collapses to the running mean
# - process_var -> infinity collapses to "output the latest measurement"

Reference#

Validated in tests/test_signal.py against the limiting cases (extreme noise ratios) plus a steady-state convergence test (zero process variance + constant input). No canonical third-party reference for a scalar Kalman filter with this exact API.

KalmanFilter#