Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Time series by state space methods

The solow-statespace crate fits linear-Gaussian state-space models and the time-series estimators built on top of them. At its core is a time-invariant Kalman filter and smoother (StateSpace for a scalar observation, MvStateSpace for a vector observation); on top of that sit three maximum-likelihood estimators — Sarimax (seasonal ARIMA), UnobservedComponents (structural level / trend / seasonal models), and DynamicFactor (a single common factor driving a panel). Every estimator evaluates the exact Gaussian log-likelihood by the prediction-error decomposition and optimizes it with BFGS over an unconstrained reparametrization.

The crate covers the linear-Gaussian core of the reference's state-space machinery. It does not (yet) expose a generic user-specified state-space builder, multi-step forecasting with confidence intervals, simulation smoothing, or exogenous regressors; the "fitted values" exposed are one-step-ahead in-sample predictions.

Background

A time-invariant linear-Gaussian state-space model writes an observed series in terms of an unobserved state vector \( \alpha_t \in \mathbb{R}^m \):

\[ \begin{aligned} \alpha_t &= T,\alpha_{t-1} + R,\eta_t, & \eta_t &\sim N(0, Q),\\ y_t &= Z,\alpha_t + \varepsilon_t, & \varepsilon_t &\sim N(0, H). \end{aligned} \]

Here \( T \) is the transition matrix, \( R \) the selection matrix, \( Q \) the state-disturbance covariance, \( Z \) the design, and \( H \) the measurement-noise covariance. In StateSpace the observation \( y_t \) is a scalar (so \( Z \) is a row and \( H \) a scalar); in MvStateSpace it is a \( p \)-vector.

Kalman filter. Given the prediction \( a_{t\mid t-1} = \mathbb{E}[\alpha_t \mid y_{1:t-1}] \) and its covariance \( P_{t\mid t-1} \), the filter forms the one-step-ahead prediction error and its variance,

\[ v_t = y_t - Z,a_{t\mid t-1}, \qquad F_t = Z,P_{t\mid t-1},Z^{\top} + H, \]

updates to the filtered state with the Kalman gain \( K_t = P_{t\mid t-1} Z^{\top} F_t^{-1} \),

\[ a_{t\mid t} = a_{t\mid t-1} + K_t,v_t, \qquad P_{t\mid t} = P_{t\mid t-1} - K_t,Z,P_{t\mid t-1}, \]

and predicts ahead via \( a_{t+1\mid t} = T,a_{t\mid t} \) and \( P_{t+1\mid t} = T,P_{t\mid t},T^{\top} + R,Q,R^{\top} \).

Log-likelihood (prediction-error decomposition). The exact Gaussian log-likelihood is the sum of the conditional densities of each prediction error,

\[ \log L = \sum_{t} \log p(y_t \mid y_{1:t-1}) = -\tfrac{1}{2}\sum_{t}\Big( p\log 2\pi + \log\lvert F_t\rvert + v_t^{\top} F_t^{-1} v_t \Big), \]

with \( p = 1 \) in the scalar case. The filter method returns this total as loglike (and the per-observation contributions as loglike_obs), along with the prediction errors forecast_error (\( v_t \)) and their variances forecast_error_cov (\( F_t \)). A leading loglike_burn observations can be excluded from the total, which is how differenced and diffuse-initialized models drop their uninformative start-up terms.

Smoother. StateSpace::smooth runs a fixed-interval (Rauch–Tung–Striebel) backward pass, returning the smoothed states \( a_{t\mid n} \) using all observations. Its gain is \( J_t = P_{t\mid t},T^{\top},P_{t+1\mid t}^{-1} \) and the recursion is \( a_{t\mid n} = a_{t\mid t} + J_t,(a_{t+1\mid n} - a_{t+1\mid t}) \).

SARIMAX. A SARIMAX\( (p,d,q)(P,D,Q,s) \) model first applies non-seasonal and seasonal differencing (the simple-differencing convention) and then casts the resulting stationary ARMA into the Harvey companion-form state space, where \( T \) holds the AR coefficients and \( R \) holds the MA coefficients. The state is initialized from its stationary distribution — the solution of the discrete Lyapunov equation \( P = T P T^{\top} + R Q R^{\top} \). During estimation the AR and MA polynomials are kept stationary and invertible through the Monahan reparametrization, and \( \sigma^2 \) is mapped through a square, so the unconstrained BFGS iterates always map to a valid model.

Unobserved components. A structural model decomposes \( y_t \) into a level (and optionally a slope and a stochastic seasonal) plus an irregular term. The local-level model is

\[ y_t = \mu_t + \varepsilon_t, \qquad \mu_t = \mu_{t-1} + \xi_t, \]

and the local-linear-trend model adds a random-walk slope \( \beta_t = \beta_{t-1} + \zeta_t \) so that \( \mu_t = \mu_{t-1} + \beta_{t-1} + \xi_t \). The nonstationary states use an approximate-diffuse initialization (a large multiple of the identity) and their start-up observations are excluded from the log-likelihood.

Example

A short worked example fits a non-seasonal ARIMA(1, 1, 1) to a small series and inspects the fitted result.

#![allow(unused)]
fn main() {
use ndarray::Array1;
use solow_statespace::{Sarimax, SarimaxOrder};

// A small upward-drifting series.
let y = Array1::from_vec(vec![
    1.0, 1.4, 1.1, 1.9, 2.2, 2.0, 2.7, 3.1, 2.9, 3.6,
    3.4, 4.1, 4.5, 4.2, 5.0, 5.3, 5.1, 5.9, 6.2, 6.0,
]);

// ARIMA(1, 1, 1): first-difference, then an AR(1) + MA(1) on the differences.
let order = SarimaxOrder::new(1, 1, 1);
let res = Sarimax::new(y, order).unwrap().fit().unwrap();

// Parameters are ordered [ar.L1, ma.L1, sigma2].
assert_eq!(res.params.len(), 3);
println!("params    = {:?}", res.params);
println!("loglike   = {:.4}", res.llf);
println!("AIC / BIC = {:.3} / {:.3}", res.aic, res.bic);
println!("converged = {}", res.converged);
}

Sarimax::new binds the model to the series; fit differences the data, optimizes the exact log-likelihood, and returns a SarimaxResults. Beyond params, that result exposes the inference battery bse, zvalues, pvalues (standard errors from the inverse negative Hessian, z-statistics, and two-sided normal p-values), the information criteria aic, bic, hqic, the one-step-ahead in-sample fittedvalues and resid, the effective sample size nobs (after differencing), and converged. The exact numbers depend on the optimizer, so they are not reproduced here.

For a seasonal model, use SarimaxOrder::seasonal:

#![allow(unused)]
fn main() {
use solow_statespace::SarimaxOrder;

// (1, 1, 1)(1, 0, 0, 4): a non-seasonal ARIMA(1, 1, 1) plus a seasonal AR(1)
// at period 4.
let order = SarimaxOrder::seasonal(1, 1, 1, 1, 0, 0, 4);
}

Structural (unobserved-components) model. The same series can be fit as a local-linear-trend structural model:

#![allow(unused)]
fn main() {
use ndarray::Array1;
use solow_statespace::{Level, UcSpec, UnobservedComponents};

let y = Array1::from_vec(vec![
    1.0, 1.4, 1.1, 1.9, 2.2, 2.0, 2.7, 3.1, 2.9, 3.6,
    3.4, 4.1, 4.5, 4.2, 5.0, 5.3, 5.1, 5.9, 6.2, 6.0,
]);

let spec = UcSpec::new(Level::LocalLinearTrend);
let res = UnobservedComponents::new(y, spec).unwrap().fit().unwrap();

// Variance parameters, ordered [sigma2.irregular, sigma2.level, sigma2.trend].
println!("variances = {:?}", res.params);
println!("loglike   = {:.4}", res.llf);
}

Add a stochastic seasonal with UcSpec::new(Level::LocalLevel).with_seasonal(4). The fitted UcResults carries the estimated variances in params, the log-likelihood llf, the information criteria aic / bic / hqic, nobs, and converged.

Direct Kalman filtering. If you have your own state-space matrices, build a StateSpace and filter a series directly. The example below is the scalar AR(1) model \( \alpha_t = \phi,\alpha_{t-1} + \eta_t \), \( y_t = \alpha_t \):

#![allow(unused)]
fn main() {
use ndarray::{array, Array1};
use solow_statespace::StateSpace;

let phi = 0.5;
let sigma2 = 1.3;
let y: Array1<f64> = array![0.5, -0.2, 1.1, 0.3, -0.9, 0.7];

let ss = StateSpace {
    transition: array![[phi]],
    selection: array![[1.0]],
    state_cov: array![[sigma2]],
    design: array![1.0],
    obs_cov: 0.0,
    init_state: array![0.0],
    // Stationary AR(1) initial variance.
    init_cov: array![[sigma2 / (1.0 - phi * phi)]],
};

let out = ss.filter(&y, 0);
println!("loglike        = {:.6}", out.loglike);
println!("filtered state = {:?}", out.filtered_state);

// Backward smoothing pass over the same series.
let smoothed = ss.smooth(&y, 0).unwrap();
println!("smoothed state = {:?}", smoothed);
}

Module reference

Models

NameDescription
SarimaxSeasonal ARIMA estimator, fit by exact-likelihood ML.
UnobservedComponentsStructural level / trend / seasonal model, fit by ML.
DynamicFactorSingle common-factor model for a multivariate panel.
StateSpaceTime-invariant linear-Gaussian model with scalar observations; provides filter and smooth.
MvStateSpaceTime-invariant linear-Gaussian model with vector observations; provides loglike and forecasts.

Specifications

NameDescription
SarimaxOrderOrder \( (p,d,q)(P,D,Q,s) \); constructors new and seasonal.
UcSpecStructural-model spec; new, with_seasonal.

Results

NameDescription
SarimaxResultsparams, bse, zvalues, pvalues, llf, aic, bic, hqic, fittedvalues, resid, nobs, converged.
UcResultsparams, llf, aic, bic, hqic, nobs, converged.
DynamicFactorResultsparams, llf, aic, bic, hqic, nobs, converged.
FilterOutputKalman-filter output: loglike, loglike_obs, predicted/filtered states and covariances, forecast_error, forecast_error_cov.

Enums

NameDescription
LevelLevel specification: LocalLevel or LocalLinearTrend.

Full API: see the generated rustdoc for solow-statespace.

References

  • Durbin, J., and Koopman, S. J. (2012). Time Series Analysis by State Space Methods, 2nd ed. Oxford University Press.
  • Harvey, A. C. (1989). Forecasting, Structural Time Series Models and the Kalman Filter. Cambridge University Press.
  • Kalman, R. E. (1960). "A New Approach to Linear Filtering and Prediction Problems." Journal of Basic Engineering, 82(1), 35–45.
  • Monahan, J. F. (1984). "A note on enforcing stationarity in autoregressive – moving average models." Biometrika, 71(2), 403–404.