State-space models

StateSpaceModel implements a classical linear-Gaussian state-space model: an unobserved (latent) state that evolves over time according to a linear transition, and observations that are a noisy linear function of that state. In geossm’s notation:

  • Observation equation: relates the observed data at time t to the latent state (via the observation/design matrix H), plus an optional exogenous-regressor term (Xbeta, beta) and Gaussian observation noise with covariance R.

  • State equation: propagates the latent state forward in time via the transition matrix F, with Gaussian process noise covariance Q, starting from an initial state x0 with covariance Sigma0.

Given these system matrices, StateSpaceModel provides:

  • filter() – the Kalman filter, producing the filtered (one-step-ahead-updated) state mean/covariance at each timestep from the data observed up to that point.

  • smoother() – a backward (Rauch-Tung-Striebel-style) pass that refines the filtered estimates using all observations, not just those up to time t.

  • estimate() – runs filtering and smoothing together.

  • sim() – simulate data from the model’s system matrices.

  • predict() – project the state forward without new observations.

StateSpaceResults wraps the output of estimate/filter/smoother with derived summaries: residuals, MSE/RMSE, confidence intervals, and a statsmodels-style summary().

The filter/smoother recursions are implemented as JAX kernels (vectorized and, optionally, GPU-accelerated via the backend argument), which is what lets LRStateSpaceModel (see Low-rank state-space models) reuse the same machinery for much larger spatial state vectors.

Minimal example

See examples/example_SSM_build.py, example_SSM_filter.py and example_SSM_smooth.py for constructing a model directly from system matrices and running the filter/smoother. In practice, most geossm users will instead build a LRStateSpaceModel (Low-rank state-space models), which builds and manages its own system matrices from a geopandas.GeoDataFrame, a formula, and a spatial covariance model, rather than constructing H/F/Q/R by hand.

See API Reference for the full parameter-level documentation of every system matrix and method.