bssm (version 2.0.2)

ssm_nlg: General multivariate nonlinear Gaussian state space models

Description

Constructs an object of class ssm_nlg by defining the corresponding terms of the observation and state equation.

Usage

ssm_nlg(
  y,
  Z,
  H,
  T,
  R,
  Z_gn,
  T_gn,
  a1,
  P1,
  theta,
  known_params = NA,
  known_tv_params = matrix(NA),
  n_states,
  n_etas,
  log_prior_pdf,
  time_varying = rep(TRUE, 4),
  state_names = paste0("state", 1:n_states)
)

Value

An object of class ssm_nlg.

Arguments

y

Observations as multivariate time series (or matrix) of length \(n\).

Z, H, T, R

An external pointers (object of class externalptr) for the C++ functions which define the corresponding model functions.

Z_gn, T_gn

An external pointers (object of class externalptr) for the C++ functions which define the gradients of the corresponding model functions.

a1

Prior mean for the initial state as object of class externalptr

P1

Prior covariance matrix for the initial state as object of class externalptr

theta

Parameter vector passed to all model functions.

known_params

A vector of known parameters passed to all model functions.

known_tv_params

A matrix of known parameters passed to all model functions.

n_states

Number of states in the model (positive integer).

n_etas

Dimension of the noise term of the transition equation (positive integer).

log_prior_pdf

An external pointer (object of class externalptr) for the C++ function which computes the log-prior density given theta.

time_varying

Optional logical vector of length 4, denoting whether the values of Z, H, T, and R vary with respect to time variable (given identical states). If used, this can speed up some computations.

state_names

A character vector containing names for the states.

Details

The nonlinear Gaussian model is defined as

$$y_t = Z(t, \alpha_t, \theta) + H(t, \theta) \epsilon_t, (\textrm{observation equation})$$ $$\alpha_{t+1} = T(t, \alpha_t, \theta) + R(t, \theta)\eta_t, (\textrm{transition equation})$$

where \(\epsilon_t \sim N(0, I_p)\), \(\eta_t \sim N(0, I_m)\) and \(\alpha_1 \sim N(a_1, P_1)\) independently of each other, and functions \(Z, H, T, R\) can depend on \(\alpha_t\) and parameter vector \(\theta\).

Compared to other models, these general models need a bit more effort from the user, as you must provide the several small C++ snippets which define the model structure. See examples in the vignette and cpp_example_model.

Examples

 # Takes a while on CRAN
set.seed(1)
n <- 50
x <- y <- numeric(n)
y[1] <- rnorm(1, exp(x[1]), 0.1)
for(i in 1:(n-1)) {
 x[i+1] <- rnorm(1, sin(x[i]), 0.1)
 y[i+1] <- rnorm(1, exp(x[i+1]), 0.1)
}

pntrs <- cpp_example_model("nlg_sin_exp")

model_nlg <- ssm_nlg(y = y, a1 = pntrs$a1, P1 = pntrs$P1, 
  Z = pntrs$Z_fn, H = pntrs$H_fn, T = pntrs$T_fn, R = pntrs$R_fn, 
  Z_gn = pntrs$Z_gn, T_gn = pntrs$T_gn,
  theta = c(log_H = log(0.1), log_R = log(0.1)), 
  log_prior_pdf = pntrs$log_prior_pdf,
  n_states = 1, n_etas = 1, state_names = "state")

out <- ekf(model_nlg, iekf_iter = 100)
ts.plot(cbind(x, out$at[1:n], out$att[1:n]), col = 1:3)