stsm-methods-transPars: Parameterization of Models Defined in the Class 'stsm'

Description Usage Arguments Details Value See Also Examples

Description

This method provides different transformations of the parameters of a structural time series model.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
## S4 method for signature 'generic'
transPars(x, 
    type = c("square", "StructTS", "exp", "exp10sq"),
    gradient = FALSE, hessian = FALSE, 
    rp, sclrho = 1.7, sclomega = 1.7, ftrans = NULL, ...)
## S4 method for signature 'numeric'
transPars(x, 
    type = eval(formals(transPars)$type),
    gradient = FALSE, hessian = FALSE, 
    rp, sclrho = 1.7, sclomega = 1.7, ftrans = NULL, ...)
## S4 method for signature 'stsm'
transPars(x, type = NULL,
    gradient = FALSE, hessian = FALSE, 
    rp, sclrho = 1.7, sclomega = 1.7, ftrans = NULL, ...)

Arguments

x

an object of class stsm.

type

a character string indicating the type of transformation. Ignored if x is of class stsm. See details.

gradient

logical. If TRUE, first order derivatives of the transformation function with respect to the parameters in the slot pars are returned.

hessian

logical. If TRUE, second order derivatives of the transformation function with respect to the parameters in the slot pars is returned.

rp

numeric value. Regularization parameter used with type = StrucTS. By default it is the variance of the data x@y divided by 100.

sclrho

numeric value. Currently ignored.

sclomega

numeric value. Currently ignored.

ftrans

a function defining an alternative transformation of the parameters. Ignored if x is of class stsm. See example below.

...

additional arguments to be passed to ftrans.

Details

Rather than using the standard parameterization of the model (in terms of variances and autoregressive coefficients if they are part of the model), it can be parameterized in terms of an auxiliary set of parameters θ. This may be useful for example when the parameters of the model are selected by means of a numerical optimization algorithm. Choosing a suitable parameterization ensures that the solution returned by the algorithm meets some constraints such as positive variances or autoregressive coefficients within the region of stationarity.

The method transPars can be applied both on a named vector of parameters, e.g. x@pars or on a model of class stsm.

When the slot transPars is not null, the model is parameterized in terms of θ. The following transformation of parameters can be considered:

In the model trend+ar2 defined in stsm.model, the autoregressive coefficients, φ, are transformed to lie in the region of stationarity: given z1 = φ_1 / (1 + |φ_1|), z2 = φ_2 / (1 + |φ_2|), the transformed coefficients are φ_1^* = z1 + z2 and φ_2 = - z1 \cdot z2.

Other transformations can be defined through the argument ftrans, which can also be defined in the slot transPars of a stsm object. ftrans must be a function returning a list containing an element called pars and two other optional elements called gradient and hessian. The parameters to be transformed are identified by their names. The variances follow the naming convention of the regular expression “^var\d{1,2}$”, e.g. var1, var2,... The variances of the initial state vector may also be transformed if they are included in the slot pars; their names follow a similar naming convention, P01, P02,... An example of ftrans is given below.

Note: If a transformation is defined by means of ftrans the user may need to update the slots lower and upper if some bounds are still applied to the auxiliary parameters. For example, transPars="StructTS" does not always yield positive variances and hence lower bounds equal to 0 are needed. By default lower and upper bounds are not considered if ftrans is used.

The output of get.pars is given in terms of the actual parameters of the model. For example, if the model is parameterized so that θ^2 are the variances of the model and θ are the auxiliary parameters then, the slot pars contains the values of θ and ger.pars returns θ^2.

The transformation transPars is applied to the parameters included in the slot pars. The transformation does not affect nopars and cpar. The former slot is considered fixed while the latter will in practice be set equal to a particular value, for example the value that maximizes the concentrated likelihood function, for which a specific expression can be obtained.

Value

A list containing a named numeric vector with the values of the transformed parameters. If requested, the gradient and Hessian of the transformation function with respect to the parameters are returned.

See Also

stsm, get.pars.

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
54
55
56
57
58
59
60
61
62
63
64
65
# sample models with arbitrary parameter values

# model in standard parameterization
# ower bounds imposed on the variance parameters
m <- stsm.model(model = "llm+seas", y = JohnsonJohnson, 
  pars = c("var1" = 2, "var2" = 15, "var3" = 30), transPars = NULL)
get.pars(m)
m@lower

# square transformation
# negative values are allowed in 'pars' since 
# the square will yield positive variances
# in fact no lower bounds need to be imposed on the auxiliary parameters
m <- stsm.model(model = "llm+seas", y = JohnsonJohnson, 
  pars = c("var1" = -2, "var2" = -5, "var3" = 10), transPars = "square")
validObject(m)
m@lower
m@pars
get.pars(m)

# 'ftrans', alternative transformation of parameters;
# the following parameterization is sometimes found:
# variance = exp(-theta) / 10
# the function 'ftrans' following the rules given in the details 
# above can be defined as follows:

ftrans <- function(x, gradient = FALSE, hessian = FALSE)
{
  tpars <- x
  p <- length(x)
  nmspars <- names(x)
  idvar <- grep("^var|P0\\d{1,2}$", nmspars, value = FALSE)

  if (gradient) {
    d1 <- rep(NA, p)
    names(d1) <- nmspars
  } else d1 <- NULL
  if (hessian) {
    d2 <- matrix(0, p, p)
    rownames(d2) <- colnames(d2) <- nmspars
  } else d2 <- NULL

  if (length(idvar) > 0) {
    tpars[idvar] <- exp(-x[idvar]) / 10
  } else warning("No changes done by 'transPars'.")

  if (gradient)
  {
    if (length(idvar) > 0)
      d1[idvar] <- -tpars[idvar]
  }
  if (hessian) {
    diag(d2)[idvar] <- tpars[idvar]
  }
  
  list(pars = tpars, gradient = d1, hessian = d2)
}

# now 'ftrans' can be passed to 'transPars' and be applied
# on a named vector of parameters or on a 'stsm' object
transPars(c("var1" = 2, "var2" = 15, "var3" = 30), 
  ftrans = ftrans, gradient = TRUE, hessian = TRUE)
m <- stsm.model(model = "llm+seas", y = JohnsonJohnson, 
  pars = c("var1" = 2, "var2" = 15, "var3" = 30), transPars = ftrans)
get.pars(m)

stsm documentation built on May 2, 2019, 7:39 a.m.