Low-rank state-space models

LRStateSpaceModel is geossm’s model for large-scale spatial and spatio-temporal data. It subclasses StateSpaceModel (State-space models), but instead of requiring the system matrices to be supplied directly, it builds them from:

  • a geopandas.GeoDataFrame of observations,

  • one Patsy/R-style formula per response variable (block), and

  • a spatial domain and a fitted covariance model (spdeAppoxCov, see Covariance models and meshes) giving a low-rank basis for the latent spatial field.

Representing the latent field through the low-rank, mesh-based SPDE basis (rather than one latent dimension per observed site) is what makes the model scale to a large number of spatial locations, per the package’s associated research (see the citations on the geossm: Geostatistics with State-Space Models page).

Typical workflow

This is the same workflow used in Quick Start:

from geossm.stmodel import LRStateSpaceModel
from geossm.covmodel import spdeAppoxCov
from geossm.covmodel.utils import buildMesh2d

# 1. Build the model from the data, formula(s) and domain
model = LRStateSpaceModel(geodf, ["y ~ 1 + x1"], domain=domain)

# 2. Build a mesh and a covariance model, then attach it
mesh_io, _ = buildMesh2d(model.points[0], domain=domain)
cov_fun = spdeAppoxCov(latlon=True).setup(mesh_io, domain=domain)
model = model.setup(cov_fun=[cov_fun])

# 3. Fit
results = model.fit()
print(results.summary())

fit() estimates the model parameters (regression coefficients, observation noise variance, and the spatial covariance parameters) with an EM-type procedure built on the parent class’s Kalman filter/smoother; FitOptions controls the stopping rule (max_iter, tol_relat), and ModelParams / Param let you pass custom initial values or fix specific parameters instead of estimating them (see examples/example_LRSSM_estimate_2.py and example_LRSSM_estimate_3.py).

Multiple response variables / domains

formulas and domain are lists so that several response variables (each with its own spatial domain and covariance model) can be modeled jointly, as separate “blocks” sharing the same latent state-space machinery.

Results, inference, and prediction

LRStateSpaceResults extends StateSpaceResults with:

  • compute_cov_params() and the derived bse, tvalues, pvalues, conf_int() – parameter standard errors and significance from the observed-information Hessian (see examples/example_LRSSM_inference.py). Before calling compute_cov_params(), these show as NaN placeholders in summary().

  • aic / bic – information criteria for model comparison.

  • predict() and to_geo() – predict at new locations/times and export fitted/predicted values back to a geopandas.GeoDataFrame.

  • back_transform() – map parameters back through a formula transformation (e.g. undo a np.sqrt(...) response transform) via the delta method.

See Examples for the full set of runnable LRSSM scripts, and API Reference for the complete parameter reference.