SSMarima: Create a State Space Model Object of Class SSModel

Description

Function SSModel creates a state space object object of class SSModel which can be used as an input object for various functions of KFAS package.

Usage

SSMarima(ar = NULL, ma = NULL, d = 0, Q, stationary = TRUE, index,
  n = 1, state_names = NULL, ynames)
SSMcustom(Z, T, R, Q, a1, P1, P1inf, index, n = 1, state_names = NULL)
SSMcycle(period, Q, type, index, a1, P1, P1inf, n = 1,
  state_names = NULL, ynames)
SSModel(formula, data, H, u, distribution, tol = .Machine$double.eps^0.5)
SSMregression(rformula, data, type, Q, index, R, a1, P1, P1inf, n = 1,
  remove.intercept = TRUE, state_names = NULL, ynames)
SSMseasonal(period, Q, sea.type = c("dummy", "trigonometric"), type,
  index, a1, P1, P1inf, n = 1, state_names = NULL, ynames, harmonics)
SSMtrend(degree = 1, Q, type, index, a1, P1, P1inf, n = 1,
  state_names = NULL, ynames)

Arguments

For arima component, a numeric vector containing the autoregressive coeffients.

For arima component, a numericvector containing the moving average coeffients.

For arima component, a degree of differencing.

For arima, cycle and seasonal component, a $p \times p$ covariance matrix of the disturbances (or in the time varying case $p \times p \times n$ array), where where $p$ = length(index). For trend component, list of length degree containing the $p \times p$ or $p \times p \times n$ covariance matrices. For a custom component, arbitrary covariance matrix or array of disturbance terms $\eta_t$

stationary

For arima component, logical value indicating whether a stationarity of the arima part is assumed. Defaults to TRUE.

index

A vector indicating for which series the corresponding components are constructed.

Length of the series, only used internally for dimensionality check.

state_names

A character vector giving the state names.

ynames

names of the times series, used internally.

For a custom component, system matrix or array of observation equation.

For a custom component, system matrix or array of transition equation.

For a custom and regression components, optional $m \times k$ system matrix or array of transition equation.

Optional $m \times 1$ matrix giving the expected value of the initial state vector $\alpha_1$.

Optional $m \times m$ matrix giving the covariance matrix of $\alpha_1$. In the diffuse case the non-diffuse part of $P_1$.

P1inf

Optional $m \times m$ matrix giving the diffuse part of $P_1$. Diagonal matrix with ones on diagonal elements which correspond to the diffuse initial states. If P1inf[i,i]>0, corresponding row and column of P1 should be zero.

period

For a cycle and seasonal components, the length of the cycle/seasonal pattern.

type

For cycle, seasonal, trend and regression components, character string defining if "distinct" or "common" states are used for different series.

formula

An object of class formula containing the symbolic description of the model. The intercept term can be removed with -1 as in lm. In case of trend or differenced arima component the intercept is removed automatically in order to keep the model identifiable. See package vignette and examples in KFAS for special functions used in model construction.

data

An optional data frame, list or environment containing the variables in the model.

Covariance matrix or array of disturbance terms $\epsilon_t$ of observation equation. Defaults to an identity matrix. Omitted in case of non-Gaussian distributions (augment the state vector if you want to add additional noise).

Additional parameters for non-Gaussian models. See details in KFAS.

distribution

A vector of distributions of the observations. Default is rep("gaussian", p), where p is the number of series.

tol

A tolerance parameter used in checking whether Finf or F is numerically zero. Defaults to .Machine$double.eps^0.5. If smoothing gives negative variances for smoothed states, try adjusting this.

rformula

For regression component, right hand side formula or list of of such formulas defining the custom regression part.

remove.intercept

Remove intercept term from regression model. Default is TRUE. This tries to ensure that there are no extra intercept terms in the model.

sea.type

For seasonal component, character string defining whether to use "dummy" or "trigonometric" form of the seasonal component.

harmonics

For univariate trigonometric seasonal, argument harmonics can be used to specify which subharmonics are added to the model. Note that for multivariate model you can call SSMseasonal multiple times with different values of index.

degree

For trend component, integer defining the degree of the polynomial trend. 1 corresponds to local level, 2 for local linear trend and so forth.

Value

Object of class SSModel, which is a list with the following components:

A n x p matrix containing the observations.

A p x m x 1 or p x m x n array corresponding to the system matrix of observation equation.

A p x p x 1 or p x p x n array corresponding to the covariance matrix of observational disturbances epsilon.

A m x m x 1 or m x m x n array corresponding to the first system matrix of state equation.

A m x k x 1 or m x k x n array corresponding to the second system matrix of state equation.

A k x k x 1 or k x k x n array corresponding to the covariance matrix of state disturbances eta

A m x 1 matrix containing the expected values of the initial states.

A m x m matrix containing the covariance matrix of the nondiffuse part of the initial state vector.

P1inf

A m x m matrix containing the covariance matrix of the diffuse part of the initial state vector. If P1[i,i] is non-zero then P1inf[i,i] is automatically set to zero.

A n x p matrix of an additional parameters in case of non-Gaussian model.

distribution

A vector of length p giving the distributions of the observations.

tol

A tolerance parameter for the diffuse phase.

call

Original call to the function.

In addition, object of class SSModel contains following attributes:

names

Names of the list components.

p, m, k, n

Integer valued scalars defining the dimensions of the model components.

state_types

Types of the states in the model.

eta_types

Types of the state disturbances in the model.

Integer vector stating whether Z,H,T,R or Q is time-varying (indicated by 1 in tv and 0 otherwise). If you manually change the dimensions of the matrices you must change this attribute also.

Details

Formula of the model can contain the usual regression part and additional functions defining different types of components of the model, named as SSMarima, SSMcustom, SSMcycle, SSMregression, SSMseasonal and SSMtrend.

For more details, see package vignette (the mathematical notation is somewhat non-readable in ASCII).

Examples

Run this code

# NOT RUN {
# add intercept to state equation by augmenting the state vector:
# diffuse initialization for the intercept, gets estimated like other states:
# for known fixed intercept, just set P1 = P1inf = 0 (default in SSMcustom).
intercept <- 0
model_int <- SSModel(Nile ~ SSMtrend(1, Q = 1469) +
SSMcustom(Z = 0, T = 1, Q = 0, a1 = intercept, P1inf = 1), H = 15099)

model_int$T
model_int$T[1, 2, 1] <- 1 # add the intercept value to level
out <- KFS(model_int)

# dynamic regression model

set.seed(1)
x1 <- rnorm(100)
x2 <- rnorm(100)
b1 <- 1 + cumsum(rnorm(100, sd = 1))
b2 <- 2 + cumsum(rnorm(100, sd = 0.1))
y <- 1 + b1 * x1 + b2 * x2 + rnorm(100, sd = 0.1)

model <- SSModel(y ~ SSMregression(~ x1 + x2, Q = diag(NA,2)), H = NA)

fit <- fitSSM(model, inits = c(0,0,0), method = "BFGS")

model <- fit$model
model$Q
model$H
out <- KFS(model)

ts.plot(out$alphahat[,-1], b1, b2, col = 1:4)


# example of using data argument
y <- x <- rep(1, 3)
data1 <- data.frame(x = rep(2, 3))
data2 <- data.frame(x = rep(3, 3))

f <- formula(~ -1 + x)
# With data missing the environment of formula is checked,
# and if not found in there a calling environment via parent.frame is checked.

c(SSModel(y ~ -1 + x)["Z"]) # 1
c(SSModel(y ~ -1 + x, data = data1)["Z"]) # 2

c(SSModel(y ~ -1 + SSMregression(~ -1 + x))["Z"]) # 1
c(SSModel(y ~ -1 + SSMregression(~ -1 + x, data = data1))["Z"]) # 2
c(SSModel(y ~ -1 + SSMregression(~ -1 + x), data = data1)["Z"]) # 2
SSModel(y ~ -1 + x + SSMregression(~ -1 + x, data = data1))["Z"] # 1 and 2
SSModel(y ~ -1 + x + SSMregression(~ -1 + x), data = data1)["Z"] # both are 2
SSModel(y ~ -1 + x + SSMregression(~ -1 + x, data = data1), data = data2)["Z"] # 3 and 2

SSModel(y ~ -1 + x + SSMregression(f))["Z"] # 1 and 1
SSModel(y ~ -1 + x + SSMregression(f), data = data1)["Z"] # 2 and 1
SSModel(y ~ -1 + x + SSMregression(f,data = data1))["Z"] # 1 and 2

rm(x)
c(SSModel(y ~ -1 + SSMregression(f, data = data1))$Z) # 2
# }
# NOT RUN {
# This fails as there is no x in the environment of f
try(c(SSModel(y ~ -1 + SSMregression(f), data = data1)$Z))
# }