StructTS                package:stats                R Documentation

Fit Structural Time Series

Description:

     Fit a structural model for a time series by maximum likelihood.

Usage:

     StructTS(x, type = c("level", "trend", "BSM"), init = NULL,
              fixed = NULL, optim.control = NULL)

Arguments:

       x: a univariate numeric time series. Missing values are allowed.

    type: the class of structural model.  If omitted, a BSM is used for
          a time series with 'frequency(x) > 1', and a local trend
          model otherwise.

    init: initial values of the variance parameters.

   fixed: optional numeric vector of the same length as the total
          number of parameters.  If supplied, only non-'NA' entries in
          'fixed' will be varied.  Probably most useful for setting
          variances to zero.

optim.control: List of control parameters for 'optim'.  Method
          '"L-BFGS-B"' is used.

Details:

     _Structural time series_ models are (linear Gaussian) state-space
     models for (univariate) time series based on a decomposition of
     the series into a number of components. They are specified by a
     set of error variances, some of which may be zero.

     The simplest model is the _local level_ model specified by 'type =
     "level"'.  This has an underlying level m[t] which evolves by

           m[t+1] = m[t] + xi[t], xi[t] ~ N(0, sigma^2_xi)

     The observations are

          x[t] = m[t] + eps[t], eps[t] ~  N(0, sigma^2_eps)

     There are two parameters, sigma^2_xi and sigma^2_eps.  It is an
     ARIMA(0,1,1) model, but with restrictions on the parameter set.

     The _local linear trend model_, 'type = "trend"', has the same
     measurement equation, but with a time-varying slope in the
     dynamics for m[t], given by

        m[t+1] = m[t] + n[t] + xi[t], xi[t] ~ N(0, sigma^2_xi)


        n[t+1] = n[t] + zeta[t],  zeta[t] ~ N(0, sigma^2_zeta)

     with three variance parameters.  It is not uncommon to find
     sigma^2_zeta = 0 (which reduces to the local level model) or
     sigma^2_xi = 0, which ensures a smooth trend.  This is a
     restricted ARIMA(0,2,2) model.

     The _basic structural model_, 'type = "BSM"', is a local trend
     model with an additional seasonal component. Thus the measurement
     equation is

       x[t] = m[t] + s[t] + eps[t], exp[t] ~  N(0, sigma^2_eps)

     where s[t] is a seasonal component with dynamics

 s[t+1] = -s[t] - ... - s[t - s + 2] + w[t],  w[t] ~ N(0, sigma^2_w)

     The boundary case sigma^2_w = 0 corresponds to a deterministic
     (but arbitrary) seasonal pattern.  (This is sometimes known as the
     'dummy variable' version of the BSM.)

Value:

     A list of class '"StructTS"' with components:

    coef: the estimated variances of the components.

  loglik: the maximized log-likelihood.  Note that as all these models
          are non-stationary this includes a diffuse prior for some
          observations and hence is not comparable with 'arima' nor
          different types of structural models.

    data: the time series 'x'.

residuals: the standardized residuals.

  fitted: a multiple time series with one component for the level,
          slope and seasonal components, estimated contemporaneously
          (that is at time t and not at the end of the series.

    call: the matched call.

  series: the name of the series 'x'.

convergence: the value returned by 'optim'.

model, model0: Lists representing the Kalman Filter used in the
          fitting.  See 'KalmanLike'.  'model0' is the initial state of
          the filter, 'model' its final state.

    xtsp: the 'tsp' attributes of 'x'.

Note:

     Optimization of structural models is a lot harder than many of the
     references admit. For example, the 'AirPassengers' data are
     considered in Brockwell & Davis (1996): their solution appears to
     be a local maximum, but nowhere near as good a fit as that
     produced by 'StructTS'.  It is quite common to find fits with one
     or more variances zero, and this can include sigma^2_eps.

References:

     Brockwell, P. J. & Davis, R. A. (1996). _Introduction to Time
     Series and Forecasting_. Springer, New York. Sections 8.2 and 8.5.

     Durbin, J. and Koopman, S. J. (2001) _Time Series Analysis by
     State Space Methods._  Oxford University Press.

     Harvey, A. C. (1989) _Forecasting, Structural Time Series Models
     and the Kalman Filter_. Cambridge University Press.

     Harvey, A. C. (1993) _Time Series Models_. 2nd Edition, Harvester
     Wheatsheaf.

See Also:

     'KalmanLike', 'tsSmooth'

Examples:

     ## see also JohnsonJohnson, Nile and AirPassengers

     data(treering)
     trees <- window(treering, start=0)
     (fit <- StructTS(trees, type = "level"))
     plot(trees)
     lines(fitted(fit), col = "green")
     tsdiag(fit)

     data(UKgas)
     (fit <- StructTS(log10(UKgas), type = "BSM"))
     par(mfrow = c(4, 1))
     plot(log10(UKgas))
     plot(cbind(fitted(fit), resids=resid(fit)), main = "UK gas consumption")

