KalmanFilter

Kalman Filter Wiki Page

You can refer to the Wikipedia page for derivations and the underlying process. The documentation only includes the user-facing interface.

Kalman Filter | Wikipedia

@dataclass(frozen=True)
class FilterResult()

dataclass storing the results of a Kalman Filter run.

Fields:

Name	Type	Description
x_pred	`np.ndarray`	State prediction before observing \(y_t\).
x_filt	`np.ndarray`	State estimate after observing \(y_t\).
P_pred	`np.ndarray`	Predicted state covariance \(P_{t\mid t-1}\).
P_filt	`np.ndarray`	Filtered state covariance \(P_{t\mid t}\).
y_pred	`np.ndarray`	Predicted observation. Shape `(T, m)`.
y_filt	`np.ndarray`	Filtered observation. Shape `(T, m)`.
innov	`np.ndarray`	Innovations (measurement residuals). Shape `(T, m)`.
S	`np.ndarray`	Innovation covariance. Shape `(T, m, m)`.
loglik	`float`	Total log-likelihood of observed data under the filter.
eps_hat	`np.ndarray \| None`	Estimated shocks (`None` unless `return_shocks=True`).

class KalmanFilter()

Static class containing methods necessary for filter application.

Methods:

KalmanFilter.run(
    A: np.ndarray[float64 | complex128],
    B: np.ndarray[float64 | complex128],
    C: np.ndarray[float64 | complex128],
    d: np.ndarray[float64 | complex128],
    Q: np.ndarray[float64 | complex128],
    R: np.ndarray[float64 | complex128],
    y: np.ndarray[float64 | complex128],
    x0: np.ndarray[float64] | None = None,
    P0: np.ndarray[float64] | None = None,
    return_shocks: bool = False,
    symmetrize: bool = True,
    jitter: float = 0.0,
) -> FilterResult

Apply a linear Kalman Filter and return FilterResult.

Inputs:

Name	Description
A	State transition matrix.
B	Shock loading matrix.
C	Observation matrix.
d	Observation intercept.
Q	Shock covariance matrix.
R	Observation-noise covariance matrix.
y	Observed data over time.
x0	Initial state mean. Defaults to zero vector.
P0	Initial state covariance. Defaults to large diagonal.
return_shocks	If `True`, compute and return estimated shocks.
symmetrize	Symmetrize covariance matrices each step if `True`.
jitter	Jitter term added to \(S_t\) when Cholesky factorization fails.

KalmanFilter.run_extended(
    A: np.ndarray[float64 | complex128],
    B: np.ndarray[float64 | complex128],
    h: Callable[..., np.ndarray],
    H_jac: Callable[..., np.ndarray],
    calib_params: np.ndarray[float64],
    Q: np.ndarray[float64 | complex128],
    R: np.ndarray[float64 | complex128],
    y: np.ndarray[float64 | complex128],
    x0: np.ndarray[float64] | None = None,
    P0: np.ndarray[float64] | None = None,
    return_shocks: bool = False,
    symmetrize: bool = True,
    jitter: float = 0.0,
    compute_y_filt: bool = True,
) -> FilterResult

Apply an extended Kalman Filter with linear transition and nonlinear measurement function. h and H_jac are evaluated at each predicted state and receive unpacked state values plus calib_params.

Jitter

Though its default is 0.0, running the method with a small jitter is strongly recommended. Using 1e-8 (or similar) can prevent fallback to matrix inversion when Cholesky fails. (Inversion much slower in comparison)

Returns:

Type	Description
`FilterResult`	`dataclass` containing outputs and diagnostics of the filter run.