bssm (version 2.0.2)

ssm_mlg: General multivariate linear Gaussian state space models

Description

Construct an object of class ssm_mlg by directly defining the corresponding terms of the model.

Usage

ssm_mlg(
  y,
  Z,
  H,
  T,
  R,
  a1 = NULL,
  P1 = NULL,
  init_theta = numeric(0),
  D = NULL,
  C = NULL,
  state_names,
  update_fn = default_update_fn,
  prior_fn = default_prior_fn
)

Value

An object of class ssm_mlg.

Arguments

y

Observations as multivariate time series or matrix with dimensions n x p.

Z

System matrix Z of the observation equation as p x m matrix or p x m x n array.

H

Lower triangular matrix H of the observation. Either a scalar or a vector of length n.

T

System matrix T of the state equation. Either a m x m matrix or a m x m x n array.

R

Lower triangular matrix R the state equation. Either a m x k matrix or a m x k x n array.

a1

Prior mean for the initial state as a vector of length m.

P1

Prior covariance matrix for the initial state as m x m matrix.

init_theta

Initial values for the unknown hyperparameters theta (i.e. unknown variables excluding latent state variables).

D

Intercept terms for observation equation, given as a p x n matrix.

C

Intercept terms for state equation, given as m x n matrix.

state_names

A character vector defining the names of the states.

update_fn

A function which returns list of updated model components given input vector theta. This function should take only one vector argument which is used to create list with elements named as Z, H, T, R, a1, P1, D, and C, where each element matches the dimensions of the original model It's best to check the internal dimensions with str(model_object) as the dimensions of input arguments can differ from the final dimensions. If any of these components is missing, it is assumed to be constant wrt. theta.

prior_fn

A function which returns log of prior density given input vector theta.

Details

The general multivariate linear-Gaussian model is defined using the following observational and state equations:

$$y_t = D_t + Z_t \alpha_t + H_t \epsilon_t, (\textrm{observation equation})$$ $$\alpha_{t+1} = C_t + T_t \alpha_t + R_t \eta_t, (\textrm{transition equation})$$

where \(\epsilon_t \sim N(0, I_p)\), \(\eta_t \sim N(0, I_k)\) and \(\alpha_1 \sim N(a_1, P_1)\) independently of each other. Here p is the number of time series and k is the number of disturbance terms (which can be less than m, the number of states).

The update_fn function should take only one vector argument which is used to create list with elements named as Z, H T, R, a1, P1, D, and C, where each element matches the dimensions of the original model. If any of these components is missing, it is assumed to be constant wrt. theta. Note that while you can input say R as m x k matrix for ssm_mlg, update_fn should return R as m x k x 1 in this case. It might be useful to first construct the model without updating function

Examples

data("GlobalTemp", package = "KFAS")
model_temp <- ssm_mlg(GlobalTemp, H = matrix(c(0.15,0.05,0, 0.05), 2, 2), 
  R = 0.05, Z = matrix(1, 2, 1), T = 1, P1 = 10,
  state_names = "temperature",
  # using default values, but being explicit for testing purposes
  D = matrix(0, 2, 1), C = matrix(0, 1, 1))
ts.plot(cbind(model_temp$y, smoother(model_temp)$alphahat), col = 1:3)