# 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

1 2 3 4 5 |

### Arguments

`model` |
a character selecting the structural time series model. |

`y` |
a univariate time series, |

`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 |

`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 |

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

`transPars` |
optional character choosing one of the parameterizations
defined in |

`ssd` |
logical. If |

`sgfc` |
logical. If |

### 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`

.

### 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, σ^2_1)*

The state equation is:

*m[t+1] = m[t] + v[t], v[t] \sim N(0, σ^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, σ^2_1)*

The state equations are:

*m[t+1] = m[t] + n[t] + v[t], v[t] \sim N(0, σ^2_2)*

*n[t+1] = n[t] + w[t], w[t] \sim N(0, σ^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, σ^2_1)*

The state equations are the same as the local trend model plus a seasonal component:

*s[t+1] = -s[t] - … - s[t-freq+2] + w[t],
w[t] \sim N(0, σ^2_4)*

The restriction *σ^2_4 = 0* yields a deterministic seasonal pattern.

According to the labelling convention used in the package,
the variance parameters *σ^2_1*, *σ^2_2*, *σ^2_3*
and *σ^2_4* are respectively denoted
`"var1"`

, `"var2"`

, `"var3"`

and `"var4"`

.

### See Also

`stsm-class`

.

### Examples

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 | ```
# 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'
# the remaining are defined by default to '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 'npars'
# '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
# default 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
``` |