StructTS                package:stats                R Documentation

_F_i_t _S_t_r_u_c_t_u_r_a_l _T_i_m_e _S_e_r_i_e_s

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

       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 '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.

_D_e_t_a_i_l_s:

     _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], eps[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.)

_V_a_l_u_e:

     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'.

    code: the 'convergence' code 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'.

_N_o_t_e:

     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.

_R_e_f_e_r_e_n_c_e_s:

     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.

_S_e_e _A_l_s_o:

     'KalmanLike', 'tsSmooth'; 'stl' for different kind of (seasonal)
     decomposition.

_E_x_a_m_p_l_e_s:

     ## see also JohnsonJohnson, Nile and AirPassengers
     require(graphics)

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

     (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")

     ## keep some parameters fixed; trace optimizer:
     StructTS(log10(UKgas), type = "BSM", fixed = c(0.1,0.001,NA,NA),
              optim.control = list(trace=TRUE))