Manual

Introduction

In this package we consider the following state-space model

\[\begin{gather*} \begin{aligned} y_{t} &= Z_{t} \alpha_{t} + d_{t} + \varepsilon_{t}, \quad \quad \quad t = 1 \dots n, \\ \alpha_{t+1} &= T \alpha_{t} + c_{t} + R \eta_{t}, \end{aligned} \end{gather*}\]

where

\[\begin{bmatrix} \varepsilon_{t} \\ \eta_{t} \\ \alpha_1 \end{bmatrix} \sim NID \begin{pmatrix} \begin{bmatrix} 0 \\ 0 \\ a_1 \end{bmatrix} , \begin{bmatrix} H & 0 & 0\\ 0 & Q & 0\\ 0 & 0 & P_1\\ \end{bmatrix} \end{pmatrix}\]

Data structures

StateSpaceModels.StateSpaceDimensions — Type
StateSpaceDimensions

StateSpaceModel dimensions, following the notation of on the book "Time Series Analysis by State Space Methods" (2012) by J. Durbin and S. J. Koopman.

  • n is the number of observations
  • p is the dimension of the observation vector $y_t$
  • m is the dimension of the state vector $\alpha_t$
  • r is the dimension of the state covariance matrix $Q$
StateSpaceModels.StateSpaceModel — Type
StateSpaceModel{Typ <: Real}

Following the notation of on the book "Time Series Analysis by State Space Methods" (2012) by J. Durbin and S. J. Koopman.

  • y A $n \times p$ matrix containing observations
  • Z A $p \times m \times n$ matrix
  • T A $m \times m$ matrix
  • R A $m \times r$ matrix
  • d A $n \times p$ matrix
  • c A $n \times m$ matrix
  • H A $p \times p$ matrix
  • Q A $r \times r$ matrix
StateSpaceModels.SmoothedState — Type
SmoothedState{T <: Real}

Following the notation of on the book "Time Series Analysis by State Space Methods" (2012) by J. Durbin and S. J. Koopman.

  • alpha Expected value of the smoothed state $E(\alpha_t|y_1, \dots , y_n)$
  • V Error covariance matrix of smoothed state $Var(\alpha_t|y_1, \dots , y_n)$
StateSpaceModels.FilterOutput — Type
FilterOutput{T <: Real}

Following the notation of on the book "Time Series Analysis by State Space Methods" (2012) by J. Durbin and S. J. Koopman.

  • a Predictive state $E(\alpha_t|y_{t-1}, \dots , y_1)$
  • att Filtered state $E(\alpha_t|y_{t}, \dots , y_1)$
  • v Prediction error $v_t = y_t − Z_t a_t$
  • P Covariance matrix of predictive state $P = Var(\alpha_t|y_{t−1}, \dots , y_1)$
  • Ptt Covariance matrix of filtered state $P = Var(\alpha_t|y_{t}, \dots , y_1)$
  • F Variance of prediction error $Var(v_{t})$
  • steadystate Boolean to indicate if steady state was attained
  • tsteady Instant when steady state was attained; in case it was not, tsteady = n+1
StateSpaceModels.StateSpace — Type
StateSpace{T <: Real}

A state-space structure containing the model, filter output, smoother output, covariance matrices, filter type and optimization method.

Predefined models

The package provides constructors for some classic state-space models.

The local level model is defined by

\[\begin{gather*} \begin{aligned} y_{t} &= \mu_{t} + \varepsilon_{t} \quad \varepsilon_{t} \sim \mathcal{N}(0, \sigma^2_{\varepsilon})\\ \mu_{t+1} &= \mu_{t} + \eta_{t} \quad \eta_{t} \sim \mathcal{N}(0, \sigma^2_{\eta})\\ \end{aligned} \end{gather*}\]
StateSpaceModels.local_level — Function
local_level(y::VecOrMat{Typ}) where Typ <: Real

Build state-space system for a local level model with observations y.

If y is provided as an Array{Typ, 1} it will be converted to an Array{Typ, 2} inside the StateSpaceModel.

The linear trend model is defined by

\[\begin{gather*} \begin{aligned} y_{t} &= \mu_{t} + \varepsilon_{t} \quad &\varepsilon_{t} \sim \mathcal{N}(0, \sigma^2_{\varepsilon})\\ \mu_{t+1} &= \mu_{t} + \nu_{t} + \xi_{t} \quad &\xi_{t} \sim \mathcal{N}(0, \sigma^2_{\xi})\\ \nu_{t+1} &= \nu_{t} + \zeta_{t} \quad &\zeta_{t} \sim \mathcal{N}(0, \sigma^2_{\zeta})\\ \end{aligned} \end{gather*}\]
StateSpaceModels.linear_trend — Function
linear_trend(y::VecOrMat{Typ}) where Typ <: Real

Build state-space system for a linear trend model with observations y.

If y is provided as an Array{Typ, 1} it will be converted to an Array{Typ, 2} inside the StateSpaceModel.

The structural model is defined by

\[\begin{gather*} \begin{aligned} y_{t} &= \mu_{t} + \gamma_{t} + \varepsilon_{t} \quad &\varepsilon_{t} \sim \mathcal{N}(0, \sigma^2_{\varepsilon})\\ \mu_{t+1} &= \mu_{t} + \nu_{t} + \xi_{t} \quad &\xi_{t} \sim \mathcal{N}(0, \sigma^2_{\xi})\\ \nu_{t+1} &= \nu_{t} + \zeta_{t} \quad &\zeta_{t} \sim \mathcal{N}(0, \sigma^2_{\zeta})\\ \gamma_{t+1} &= -\sum_{j=1}^{s-1} \gamma_{t+1-j} + \omega_{t} \quad & \omega_{t} \sim \mathcal{N}(0, \sigma^2_{\omega})\\ \end{aligned} \end{gather*}\]
StateSpaceModels.structural — Function
structural(y::VecOrMat{Typ}, s::Int; X::VecOrMat{Typ} = Matrix{Typ}(undef, 0, 0)) where Typ <: Real

Build state-space system for a given structural model with observations y, seasonality s, and, optionally, exogenous variables X.

If y is provided as an Array{Typ, 1} it will be converted to an Array{Typ, 2} inside the StateSpaceModel. The same will happen to X, if an Array{Typ, 1} it will be converted to an Array{Typ, 2} inside the StateSpaceModel.

A regression can also be defined in terms of state-space model. We consider the simple model $y_t = X_t \beta_t + \varepsilon_t$ where $\varepsilon_{t} \sim \mathcal{N}(0, H_t)$. This can be written in the state-space form by doing $Z_t = X_t, T_t = I, R = 0$ and $Q = 0$

StateSpaceModels.regression — Function
regression(y::VecOrMat{Typ}, X::VecOrMat{Typ}) where Typ <: Real

Build state-space system for estimating a regression model $y_t = X_t\beta_t + \varepsilon_t$. Once the model is estimated the user can recover the parameter $\hat{\beta}$ by the querying the smoothed states of the model.

Custom models

You can also build your own custom model by passing all or some of the matrices that compose the state-space model.

Currently there is a list of constructors that allow you to define a new model. When building the StateSpaceModel the parameters to be estimated will be indicated with a NaN.

 StateSpaceModel(y::Matrix{Typ}, Z::Array{Typ, 3}, T::Matrix{Typ}, R::Matrix{Typ}, H::Matrix{Typ}, Q::Matrix{Typ}) where Typ <: Real
 StateSpaceModel(y::Matrix{Typ}, Z::Matrix{Typ}, T::Matrix{Typ}, R::Matrix{Typ}, H::Matrix{Typ}, Q::Matrix{Typ}) where Typ <: Real
 StateSpaceModel(y::Matrix{Typ}, Z::Array{Typ, 3}, T::Matrix{Typ}, R::Matrix{Typ}) where Typ <: Real
 StateSpaceModel(y::Matrix{Typ}, Z::Matrix{Typ}, T::Matrix{Typ}, R::Matrix{Typ}) where Typ <: Real

In case H and Q are not provided, they are automatically filled with NaN and set to be estimated.

Estimation

The model estimation is made using the function statespace(model; filter_type = KalmanFilter, optimization_method = RandomSeedsLBFGS(), verbose = 1). It receives as argument the pre-specified StateSpaceModel object model. Optionally, the user can define the Kalman filter variant to be used, the optimization method and the verbosity level.

StateSpaceModels.statespace — Function
statespace(model; filter_type = KalmanFilter, opt_method = LBFGS(), verbose = 1)

Estimate the pre-specified state-space model. The function will only estimate the entries that are declared NaN. If there are no NaNs in the model it will only perform the filter and smoother computations.

Forecasting

Forecasting is conducted with the function forecast. It receives as argument a StateSpace object and the number of steps ahead N.

StateSpaceModels.forecast — Function
forecast(ss::StateSpace{Typ}, N::Int) where Typ

Obtain the minimum mean square error forecasts N steps ahead. Returns the forecasts and the predictive distributions at each time period.

Simulation

Simulation is made using the function simulate. It receives as argument a StateSpace object, the number of steps ahead N and the number of scenarios to simulate S.

StateSpaceModels.simulate — Function
simulate(ss::StateSpace{Typ}, N::Int, S::Int) where Typ

Simulate S future scenarios up to N steps ahead. Returns a p x N x S matrix where the dimensions represent, respectively, the number of series in the model, the number of steps ahead, and the number of scenarios.

Filters

Kalman Filter

The implementation of the Kalman Filter follows the recursion

\[\begin{gather*} \begin{aligned} v_{t} &= y_{t} - Z_{t} a_{t}, &F_{t} &= Z_{t} P_{t} Z^{\top}_{t} + H\\ a_{t|t} &= a_{t} - P_{t} Z^{\top}_{t} F_{t}^{-1} v_{t}, \quad \quad \quad &P_{t|t} &= P_{t} - P_{t} Z^{\top}_{t} F_{t}^{-1}Z_{t} P_{t}\\ a_{t+1} &= T a_{t} - K_{t} v_{t}, \quad \quad \quad &P_{t+1} &= T P_{t}(T - K_{t} Z_{t})^{\top} + R Q R\\ \end{aligned} \end{gather*}\]

where $K_{t} = T P_{t} Z^{\top}_{t} F_{t}^{-1}$. The terms $a_{t+1}$ and $P_{t+1}$ can be simplifed to

\[\begin{gather*} \begin{aligned} a_{t+1} &= T a_{t|t},\quad \quad \quad &P_{t+1} &= T P_{t|t} T^{\top} + R Q R\\ \end{aligned} \end{gather*}\]

In case of missing observation the mean of inovations $v_{t}$ and variance of inovations $F_{t}$ become NaN and the recursion becomes

\[\begin{gather*} \begin{aligned} a_{t|t} &= a_{t}, \quad \quad \quad &P_{t|t} &= P_{t}\\ a_{t+1} &= T a_{t}, \quad \quad \quad &P_{t+1} &= T P_{t} T^{\top} + R Q R\\ \end{aligned} \end{gather*}\]
StateSpaceModels.kalman_filter — Function
kalman_filter(model::StateSpaceModel{Typ}; tol::Typ = Typ(1e-5)) where Typ

Kalman filter with big Kappa initialization, i.e., initializing state variances as 1e6.

The implementation of the smoother follows the recursion

\[\begin{gather*} \begin{aligned} r_{t-1} &= Z^{\top}_{t} F_{t}^{-1} v_{t} + L^{\top}_{t} r_{t}, \quad \quad &N_{t-1} &= Z^{\top}_{t} F_{t}^{-1} Z_{t} + L^{\top}_{t} N_{t} L_{t}\\ \alpha_{t} &= a_{t} + P_{t} r_{t}, &V_{t} &= P_{t} - P_{t} N_{t-1} P_{t} \\ \end{aligned} \end{gather*}\]

where $L_{t} = T - K_{t} Z_{t}$.

In case of missing observation then $r_{t-1}$ and $N_{t-1}$ become

\[\begin{gather*} \begin{aligned} r_{t-1} &= T^{\top} r_{t}, \quad \quad &N_{t-1} &= T^{\top}_{t} N_{t} T_{t}\\ \end{aligned} \end{gather*}\]
StateSpaceModels.smoother — Function
smoother(model::StateSpaceModel{Typ}, kfilter::KalmanFilter{Typ}) where Typ

Smoother for state-space model.

Square Root Kalman Filter

StateSpaceModels.sqrt_kalman_filter — Function
sqrt_kalman_filter(model::StateSpaceModel{Typ}; tol::Typ = Typ(1e-5)) where Typ

Square-root Kalman filter with big Kappa initialization.

StateSpaceModels.sqrt_smoother — Function
sqrt_smoother(model::StateSpaceModel, sqrt_filter::SquareRootFilter) where Typ

Square-root smoother for state space model.

StateSpaceModels.filtered_state — Function
filtered_state(model::StateSpaceModel{Typ}, sqrt_filter::SquareRootFilter{Typ}) where Typ

Obtain the filtered state estimates and their covariance matrices.

Filter interface

StateSpaceModels has an interface that allows users to define their own versions of the Kalman filter.

StateSpaceModels.kfas — Function
kfas(model::StateSpaceModel{T}, filter_type::DataType) where T

Perform Kalman filter and smoother according to the chosen filter_type.

Every filter must provide its own version of the statespace_loglik function

StateSpaceModels.statespace_loglik — Function
statespace_loglik(psitilde::Vector{T}, model::StateSpaceModel, unknowns::Unknowns, 
                        valid_insts::Vector{Int}, filter_type::DataType) where T

Compute log-likelihood concerning hyperparameter vector psitilde ($\psi$)

Evaluate $\ell(\psi;y_n)= -\frac{np}{2}\log2\pi - \frac{1}{2} \sum_{t=1}^n \log |F_t| - \frac{1}{2} \sum_{t=1}^n v_t^{\top} F_t^{-1} v_t$

Optimization methods

StateSpaceModels has an interface that allows users to define their own optimization methods. It is easily integrated with Optim.jl.

LBFGS

StateSpaceModels.LBFGS — Type
LBFGS(model::StateSpaceModel{T}, args...; kwargs...)

If an Int is provided the method will sample random seeds and use them as initial points for Optim LBFGS method. If a Vector{Vector{T}} is provided it will use them as initial points for Optim LBFGS method.

BFGS

StateSpaceModels.BFGS — Type
BFGS(model::StateSpaceModel{T}, args...; kwargs...)

If an Int is provided the method will sample random seeds and use them as initial points for Optim BFGS method. If a Vector{Vector{T}} is provided it will use them as initial points for Optim BFGS method.

Optimization methods interface

StateSpaceModels.estimate_statespace — Function
estimate_statespace(model::StateSpaceModel{T}, filter_type::DataType,
                        optimization_method::AbstractOptimizationMethod; verbose::Int = 1) where T

Estimate parameters of the StateSpaceModel according to its filter_type and optimization_method.

Diagnostics

After the estimation is completed, diagnostics can be run over the residuals. The implemented diagnostics include the Jarque-Bera normality test, the Ljung-Box independence test, and a homoscedasticity test.

StateSpaceModels.ljungbox — Function
ljungbox(e::Matrix{T}; maxlag::Int = 20) where T

Run Ljung-Box independence test and return p-values