`statespace_structural`#

The structural components of DK §3.2-3.3, §3.8 and §3.9.

Each component applies to all p series of the model at once, as a seemingly unrelated time series equations (SUTSE) model (DK §3.3): each series has its own states, and the disturbances are correlated across series through a p × p variance matrix of type

COV_DIAGONAL (1): one variance per series;
COV_FULL (2): a full matrix, estimated through its Cholesky factor with log diagonal;
COV_NONE (0): no disturbance: a fixed component.

Within a component the states are ordered series by series, and within a series in DK’s order. Variances use \(\sigma^2 = \exp(2\psi)\) (DK §7.3.2); parameter names follow sigma2.<component>, with the series number appended when p > 1 and cov.<component>.i.j for full matrices.

Components#

type, extends(component_t) :: irregular_t
  integer :: cov = COV_DIAGONAL
  real(dp), allocatable :: weights(:)       ! (n), optional
end type

The irregular \(\varepsilon_t \sim N(0, \Sigma_\varepsilon)\); adds to H and has no states. With weights, \(H_t = w_t \Sigma_\varepsilon\), for unequally spaced or aggregated data (DK §3.8). Always at the observations.

type, extends(component_t) :: level_t
  integer :: cov = COV_DIAGONAL
end type

The random walk level \(\mu_{t+1} = \mu_t + \xi_t\) (DK ch. 2).

type, extends(component_t) :: trend_t
  integer :: cov_level = COV_DIAGONAL, cov_slope = COV_DIAGONAL
end type

The local linear trend \(\mu_{t+1} = \mu_t + \nu_t + \xi_t\), \(\nu_{t+1} = \nu_t + \zeta_t\) (DK §3.2.1). cov_level = COV_NONE gives the smooth trend (integrated random walk); both COV_NONE a deterministic linear trend.

type, extends(component_t) :: seasonal_t
  integer :: period = 4
  integer :: form = SEASONAL_DUMMY
  integer :: cov = COV_DIAGONAL
end type

The seasonal of period s (DK §3.2.2): SEASONAL_DUMMY (1; s - 1 states, DK eq. 3.3), SEASONAL_TRIG (2; s - 1 states, all harmonics with one variance, DK eqs. 3.7-3.8) or SEASONAL_HS (3; Harrison-Stevens, s states). COV_NONE gives a fixed seasonal.

type, extends(component_t) :: cycle_t
  integer :: cov = COV_DIAGONAL
  logical :: damped = .true.
  real(dp) :: period_min = 2.0_dp
  real(dp) :: period_max = 0.0_dp          ! 0: the number of observations
end type

The cycle (DK §3.2.4, eq. 3.13): \((c_{t+1}, c^*_{t+1})' = \rho C(\lambda) (c_t, c^*_t)' + w_t\) with \(C(\lambda)\) the rotation by \(\lambda\) and \(Var(w_t) = \Sigma \otimes I_2\). Parameters: the covariance, then \(\lambda\), bounded by the period bounds, then \(\rho \in (0, 1)\) if damped. A damped cycle is stationary and starts from its unconditional distribution (DK §3.2.4); statsmodels starts it diffuse (see Initialization of a damped cycle).

type, extends(component_t) :: regression_t
  real(dp), allocatable :: x(:, :)              ! (n, k_x)
  logical, allocatable :: random_walk(:)        ! (k_x), default all .false.
  integer :: series = 1
end type

Regression effects \(x_t'\beta_t\) for one series (DK §3.2.5, §3.6). The coefficients are diffuse states, fixed or random walks (DK eq. 3.15) with estimated variances named sigma2.beta.j. With loadings, set at_observations for effects on an observed series, such as the intercepts of the common levels model (DK §3.3.2).

type, extends(component_t) :: continuous_level_t
  real(dp), allocatable :: times(:)             ! (n)
end type
type, extends(component_t) :: continuous_trend_t
  real(dp), allocatable :: times(:)             ! (n)
end type

Continuous-time components observed at times \(t_1 \le \dots \le t_n\) (DK §3.8). The level has \(Var(\eta_i) = \sigma^2 \delta_i\), \(\delta_i = t_{i+1} - t_i\). The smooth trend \(d\nu = \sigma dw\), \(d\mu = \nu\,dt\) gives (DK eqs. 3.41-3.42)

\[\begin{split}T_i = \begin{bmatrix} 1 & \delta_i \\ 0 & 1 \end{bmatrix}, \quad Q_i = \sigma^2 \delta_i \begin{bmatrix} \delta_i^2/3 & \delta_i/2 \\ \delta_i/2 & 1 \end{bmatrix};\end{split}\]

with diffuse initial states and an irregular of variance \(\sigma_\varepsilon^2\), its smoothed level is the cubic smoothing spline with \(\lambda = \sigma_\varepsilon^2 / \sigma^2\) (DK §3.9.2; Wahba 1978). Both are univariate; repeated times are allowed.

Interventions#

pure function step_intervention(n, tau) result(w)    ! 0 before tau, 1 from tau
pure function pulse_intervention(n, tau) result(w)   ! 1 at tau, 0 elsewhere
pure function slope_intervention(n, tau) result(w)   ! 0 before tau, 1 + t - tau from tau

Regressors for intervention effects (DK §3.2.5), to pass to regression_t.

Covariance transforms#

pure function cov_constrain(cov, p, x) result(c)
pure function cov_unconstrain(cov, p, c) result(x)

Map between the unconstrained values and the covariance parameters: for COV_DIAGONAL the variances, \(\exp(2x)\); for COV_FULL the lower triangle of \(\Sigma = L L'\) by columns, with L lower triangular and diagonal \(\exp(x)\). Also used by statespace_mapped.

statespace_structural#

Components#

Interventions#

Covariance transforms#

`statespace_structural`#