StructTS {ts} | R Documentation |

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

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

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

*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], exp[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.)

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

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

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