stsm-set-methods: Setter Methods for Class `stsm`

Description

Setter or modifier methods for objects of class stsm.

Usage

"set.cpar"(x, value, check = TRUE, inplace = FALSE)
"set.nopars"(x, v, check = TRUE, inplace = FALSE)
"set.pars"(x, v, check = TRUE, inplace = FALSE)
"set.sgfc"(x, inplace = FALSE)
"set.xreg"(x, xreg, coefs = NULL)

Arguments

an object of class stsm.

value

a numeric value.

a numeric vector.

check

logical. If TRUE, the resulting model is checked for consistency with the definition of the stsm object.

inplace

logical. If TRUE, the input object x is modified in place instead of returning the whole object.

xreg

a matrix or numeric vector of external regressors. The number of rows or length of the vector must be equal to the length of x@y. If column names are specified they are used to name the parameters in the slot pars.

coefs

an optional vector containing the value of the coefficients related to the regressors xreg. If the elements of the vector do not contain names they are assumed to be defined in the same order as the columns in the matrix xreg.

Value

If the slot is modified in place, inplace=TRUE, nothing is returned, the corresponding slot of the object m passed as argument is modified in place.If inplace=FALSE, a new stsm object is returned. It contains the same information as the input object m except for the slot that has been modified.

Details

Models parameterized with non-null transPars. If the model is parameterized according to a non-null value of the slot transPars, the argument v must contain the values of the auxiliar set of parameters $\theta$ rather than the actual parameters (variances and autoregressive coefficients). For example, with x@transPars = "square" the variances are $\theta^2$. Although this design may seem to disagree with the getter methods stsm-get-methods, the relevant input for the setter methods is actually the auxiliar values $\theta$. Be aware that if transPars is not null the parameters are transformed by get.pars according to the selected parameterization. Therefore, v must be referred to the non-transformed parameters.

The previous comment does not apply to the argument value since cpar is not affected by transPars.

Setter methods are safer. For those users that are not familiar with the design and internal structure of the class stsm, it is safer to use setter methods rather than modifying the contents of the slots through the @<- operator. See the examples below.

Modifying the input object in-place. Instead of returning the whole object and create a new one or overwrite the original, it is possible to modify just the desired slot in the original object that is passed as input. In the former case the stsm object returned by the method must be assigned to another object using the usual operator <-. In the latter approach, the stsm object that is passed as argument is modified in-place. See the example below. The solution to modify an object in-place is taken from this post. This option is not a customary solution in R, however, it seems suitable in this context. The real benefit of this approach would depend on how R deals with objects that are returned from functions. If assigning the output to a new object involves making copies of all the slots, then modifying the object in-place would most likely be more efficient since the desired slot is directly modified avoiding copying the whole object.

After R version 3.1 this issue may become less critical. One of the new features reported in the release of R 3.1 states: Avoid duplicating the right hand side values in complex assignments when possible. This reduces copying of replacement values in expressions such as Z$a <- a0. A related discussion for S4 classes can be found in this post.

Constant terms in the spectral generating function. In pure variance models, some elements of the spectral generating function (s.g.f.) do not depend on the parameters and can be stored as constants. The method set.sgfc computes and stores those elements as a matrix in the slot sgfc. This is useful for example when working with maximum likelihood methods in the frequency domain. In that context, the spectral generating function has to be updated several times for different parameter values. Having the information about the constant terms in the slot sgfc saves several computations whenever the s.g.f. is requested. For details about the s.g.f see stsm.sgf.

Further setter methods. Future versions may include additional setter methods, for example to change the slot model or to modify the time series x@y. The latter would also require updating the slots diffy and ssd if requested. Additional methods are not available in the current version because defining a new object by means of stsm.model will often be better than modifying one of those slots that do not have a setter method.

Examples

Run this code

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

# correct modification
m1 <- set.pars(m, c(1, 2, 3))
get.pars(m1)
m1 <- set.pars(m, c(var1 = 11))
get.pars(m1)

# correct but error prone
m1@pars[] <- c(4, 22, 33)
get.pars(m1)
m1@pars <- c(var1 = 1, var2 = 2, var3 = 3)
get.pars(m1)

# inconsistent assignment (error returned)
# 'var4' is not a parameter of model 'llm+seas'
try(m1 <- set.pars(m, c(var4 = 4)))
# inconsistent assignment (no error returned)
# the error is not noticed at this point
# unless 'validObject' is called
m1 <- m
m1@pars["var4"] <- 4
get.pars(m1)
try(validObject(m1))

# modify only one element
m1 <- set.pars(m, v=c(var1=22))
get.pars(m1)
# wrong assignment, the whole vector in the slot is overwritten 
# no error returned at the time of doing the assignment
m1@pars <- c(var1 = 1)
get.pars(m1)
try(validObject(m1))

# consistent assignment but maybe not really intended
# all the elements are set equal to 12
m1 <- m
m1@pars[] <- 12
get.pars(m1)
# warning returned by 'set.pars'
m2 <- set.pars(m, 12)
get.pars(m2)

# wrong value unnoticed (negative variance)
m1 <- m
m1@pars[] <- c(-11, 22, 33)
get.pars(m1)
# negative sign detected by 'set.pars'
try(m1 <- set.pars(m, c(-11, 22, 33)))

# inplace = FALSE
# the whole object 'm' is assigned to a new object, 
# which will probably involve making a copy of all the slots
m <- set.pars(m, c(1,2,3), inplace = FALSE)
get.pars(m)

# inplace = TRUE
# the output is not assigned to a new object 
# the only operation is the modification of the slot 'pars'
# no apparent additional internal operations such as copying unmodified slots
get.pars(m)
set.pars(m, c(11,22,33), inplace = TRUE)
get.pars(m)

# set a matrix of regressors
xreg <- cbind(xreg1 = seq_len(84), xreg2 = c(rep(0, 40), rep(1, 44)))
m <- stsm.model(model = "llm+seas", y = JohnsonJohnson, xreg = xreg)
m
# set a new matrix of regressors to an existing
xreg3 <- seq(length(m@y))
m2 <- set.xreg(m, xreg3)
m2
# remove the external regressors
m3 <- set.xreg(m, NULL)
m3
m3@xreg
# initialize the coefficients to some values
m <- stsm.model(model = "llm+seas", y = JohnsonJohnson,
  pars = c("xreg1" = 10), xreg = xreg)
m
m <- stsm.model(model = "llm+seas", y = JohnsonJohnson,
  pars = c("xreg2" = 20, "xreg1" = 10), xreg = xreg)
m