stsm (version 1.7)

stsm.model: Wrapper for Constructor of Objects of Class stsm

Description

Interface to define an object of class stsm. This is a wrapper function to constructor new.

Usage

stsm.model(model = c("local-level", "local-trend", "BSM", 
  "llm+seas", "trend+ar2"),
  y, pars = NULL, nopars = NULL, cpar = NULL, xreg = NULL, 
  lower = NULL, upper = NULL, transPars = NULL,
  ssd = FALSE, sgfc = FALSE)

Arguments

model

a character selecting the structural time series model.

y

a univariate time series, ts.

pars

initial values for the parameters of the model. It must be a named vector.

nopars

optional named numeric containing the remaining parameters of the model not included in pars and cpar.

cpar

optional named numeric of length one. See details.

xreg

optional matrix or numeric vector of external regressors.

lower

optional named vector setting lower bounds to some parameters of the model. The names must follow the same same labelling as pars.

upper

optional named vector setting upper bounds to some parameters of the model. The names must follow the same same labelling as pars.

transPars

optional character choosing one of the parameterizations defined in transPars or a function defining an alternative parameterization.

ssd

logical. If TRUE, the sample spectral density (periodogram) of the stationary transformation of the data is computed and stored in the slot ssd. Otherwise, it is ignored.

sgfc

logical. If TRUE, constants terms of the spectral generating function related to the chosen model are computed and stored in the slot sgfc. Otherwise, it is ignored.

Value

• An object of class stsm.

Available models

The local level model consists of a random walk plus a Gaussian disturbance term.

The measurement equation is: $$y[t] = m[t] + e[t], e[t] \sim N(0, \sigma^2_1)$$

The state equation is: $$m[t+1] = m[t] + v[t], v[t] \sim N(0, \sigma^2_2)$$

The local trend model consists of a trend where the slope evolves as a random walk.

The measurement equation is: $$y[t] = m[t] + e[t], e[t] \sim N(0, \sigma^2_1)$$

The state equations are: $$m[t+1] = m[t] + n[t] + v[t], v[t] \sim N(0, \sigma^2_2)$$ $$n[t+1] = n[t] + w[t], w[t] \sim N(0, \sigma^2_3)$$

Setting $var3 = 0$ yields the local level model. The constraint $var2 = 0$ involves a smooth trend.

The basic structural model consists of a local trend model plus a seasonal component.

The measurement equation is: $$y[t] = m[t] + s[t] + e[t], e[t] \sim N(0, \sigma^2_1)$$

The state equations are the same as the local trend model plus a seasonal component: $$s[t+1] = -s[t] - \dots - s[t-freq+2] + w[t], w[t] \sim N(0, \sigma^2_4)$$

The restriction $\sigma^2_4 = 0$ yields a deterministic seasonal pattern.

According to the labelling convention used in the package, the variance parameters $\sigma^2_1$, $\sigma^2_2$, $\sigma^2_3$ and $\sigma^2_4$ are respectively denoted "var1", "var2", "var3" and "var4".

Details

Slot pars and nopars. In some situations it is convenient to split the vector of parameters in two vectors, the slot pars and the slot nopars. For example, when the parameters are to be estimated by an optimization algorithm, only the parameters in pars are allowed to change while the parameters in nopars are considered fixed.

Scaling parameter cpar. The model can be defined in terms of relative variances. In this case, the variance that acts as a scaling parameter is stored in the slot cpar. Otherwise, cpar is null and ignored. Typically, the scaling parameter will be chosen to be the variance parameter that is concentrated out of the likelihood function.

Naming convention of parameters. The parameters defined in the slots pars, nopars and cpar must be labelled according to the following naming convention. The variance parameters abide by the regular expression ^var\d{1,2}$, e.g. var1, var2,... The variances of the initial state vector, $P0$, follow a similar naming convention, P01, P02,... The elements of the initial state vector, $a0$, are similarly denoted as a01, a02,...

Default values. Default values are assigned to the slots pars, nopars and cpar if they are no defined in their corresponding arguments passed to stsm.model. By default, the variance parameters are defined in the slot pars with value $1$. The initial state vector is assigned by default to nopars, it takes on zero values except for the first element that takes the value of the first observation in the data. The variance of the initial state vector is assigned by default to nopars as well. By default it takes on the value $10000$ times the variance of the data.

If the argument pars is not NULL, no other parameters are stored in the slot pars. If the argument nopars is not NULL, the parameters in that argument are added to the other default parameters. This is more convenient in practice. See the examples below.

Alternative parameterizations. See transPars for available parameterizations of the model. The definition of a function to be defined in the slot transPars is also explained there.

Stationary transformation of the data. The sample spectral density is computed for the differenced time series y. The differencing filter is chosen so that the data are rendered stationary according to the selected model. The stationary form of each model is given in stsm.sgf.

See Also

stsm.

Examples

# sample model with arbitrary parameter values
m <- stsm.model(model = "llm+seas", y = JohnsonJohnson, 
  pars = c("var1" = 2, "var2" = 6), nopars = c("var3" = 12))
m

# parameter values
v <- c("var1" = 2, "var2" = 6, "var3" = 3, "var4" = 12)

# define the parameter 'cpar' and let the the remaining parameters 
# be defined by default in the slots 'pars' and 'nopars'
m <- stsm.model(model = "BSM", y = JohnsonJohnson, 
  pars = NULL, nopars = NULL, cpar = v[1])
m@pars
m@nopars
m@cpar

# define the slot 'pars', only 'v[1]' is stored in 'pars'
# the remaining variances are moved to 'nopars' along
# with the initial state vector and its variances
m <- stsm.model(model = "BSM", y = JohnsonJohnson, 
  pars = v[1])
m@pars
m@nopars
m@cpar

# define some of the parameters to be stored in the slot 'nopars' 
# 'only 'v[1:2]' is added to the remaining elements in 'nopars'; 
# by default the variances not defined in 'nopars' are assigned to 
# 'pars' with value 1
m <- stsm.model(model = "BSM", y = JohnsonJohnson, 
  nopars = v[1:2])
m@pars
m@nopars
m@cpar

# define the slot 'pars' and set a particular value to 
# some variances stored in 'nopars', 'v[2:3]'
# 'var4' takes the default value 1 and is stored in 'nopars' 
# since the definition 'pars = v[1]' excludes it form 'pars'
m <- stsm.model(model = "BSM", y = JohnsonJohnson, 
  pars = v[1], nopars = v[2:3])
m@pars
m@nopars
m@cpar

# define the slots 'pars' and 'cpar'
# the remaining parameters are stored in 'nopars' with the 
# values by default
m <- stsm.model(model = "BSM", y = JohnsonJohnson, 
  pars = v[2:4], nopars = NULL, cpar = v[1])
m@pars
m@nopars
m@cpar