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

Description

Setter or modifier methods for objects of class stsm.

Usage

## S3 method for class 'stsm':
set.cpar(x, value, check = TRUE, inplace = FALSE)
## S3 method for class 'stsm':
set.nopars(x, v, check = TRUE, inplace = FALSE)
## S3 method for class 'stsm':
set.pars(x, v, check = TRUE, inplace = FALSE)
## S3 method for class 'stsm':
set.sgfc(x, inplace = FALSE)

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.

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 stsm.class package, 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 http://tolstoy.newcastle.edu.au/R/help/04/02/0966.html{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 Rdeals 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.

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)