1% File src/library/stats/man/StructTS.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2009 R Core Team
4% Distributed under GPL 2 or later
5
6\name{StructTS}
7\alias{StructTS}
8\alias{print.StructTS}
9\alias{predict.StructTS}
10\title{Fit Structural Time Series}
11\description{
12  Fit a structural model for a time series by maximum likelihood.
13}
14\usage{
15StructTS(x, type = c("level", "trend", "BSM"), init = NULL,
16         fixed = NULL, optim.control = NULL)
17}
18\arguments{
19  \item{x}{a univariate numeric time series. Missing values are allowed.}
20
21  \item{type}{the class of structural model.  If omitted, a BSM is used
22    for a time series with \code{frequency(x) > 1}, and a local trend
23    model otherwise.  Can be abbreviated.}
24
25  \item{init}{initial values of the variance parameters.}
26
27  \item{fixed}{optional numeric vector of the same length as the total
28    number of parameters.  If supplied, only \code{NA} entries in
29    \code{fixed} will be varied.  Probably most useful for setting
30    variances to zero.}
31
32  \item{optim.control}{List of control parameters for
33    \code{\link{optim}}.  Method \code{"L-BFGS-B"} is used.}
34}
35\details{
36 \emph{Structural time series} models are (linear Gaussian) state-space
37 models for (univariate) time series based on a decomposition of the
38 series into a number of components. They are specified by a set of
39 error variances, some of which may be zero.
40
41 The simplest model is the \emph{local level} model specified by
42 \code{type = "level"}.  This has an underlying level \eqn{\mu_t}{m[t]} which
43 evolves by
44 \deqn{\mu_{t+1} = \mu_t + \xi_t,  \qquad \xi_t \sim N(0, \sigma^2_\xi)}{m[t+1] = m[t] + xi[t], xi[t] ~ N(0, \sigma^2_\xi)}
45 The observations are
46 \deqn{x_t = \mu_t + \epsilon_t, \qquad \epsilon_t \sim  N(0, \sigma^2_\epsilon)}{x[t] = m[t] + eps[t], eps[t] ~  N(0, \sigma^2_\eps)}
47 There are two parameters, \eqn{\sigma^2_\xi}
48 and \eqn{\sigma^2_\epsilon}{\sigma^2_eps}.  It is an ARIMA(0,1,1) model,
49 but with restrictions on the parameter set.
50
51 The \emph{local linear trend model}, \code{type = "trend"}, has the same
52 measurement equation, but with a time-varying slope in the dynamics for
53 \eqn{\mu_t}{m[t]}, given by
54 \deqn{
55   \mu_{t+1} = \mu_t + \nu_t + \xi_t, \qquad  \xi_t \sim N(0, \sigma^2_\xi)
56 }{m[t+1] = m[t] + n[t] + xi[t], xi[t] ~ N(0, \sigma^2_\xi)}
57 \deqn{
58   \nu_{t+1} = \nu_t + \zeta_t, \qquad \zeta_t \sim N(0, \sigma^2_\zeta)
59 }{n[t+1] = n[t] + \zeta[t],  \zeta[t] ~ N(0, \sigma^2_\zeta)}
60 with three variance parameters.  It is not uncommon to find
61 \eqn{\sigma^2_\zeta = 0} (which reduces to the local
62 level model) or \eqn{\sigma^2_\xi = 0}, which ensures a
63 smooth trend.  This is a restricted ARIMA(0,2,2) model.
64
65 The \emph{basic structural model}, \code{type = "BSM"}, is a local
66 trend model with an additional seasonal component. Thus the measurement
67 equation is
68 \deqn{x_t = \mu_t + \gamma_t + \epsilon_t, \qquad \epsilon_t \sim  N(0, \sigma^2_\epsilon)}{x[t] = m[t] + s[t] + eps[t], eps[t] ~  N(0, \sigma^2_eps)}
69 where \eqn{\gamma_t}{s[t]} is a seasonal component with dynamics
70 \deqn{
71   \gamma_{t+1} = -\gamma_t + \cdots + \gamma_{t-s+2} + \omega_t, \qquad
72   \omega_t \sim N(0, \sigma^2_\omega)
73 }{s[t+1] = -s[t] - \dots - s[t - s + 2] + w[t],  w[t] ~ N(0, \sigma^2_w)}
74 The boundary case \eqn{\sigma^2_\omega = 0}{\sigma^2_w = 0} corresponds
75 to a deterministic (but arbitrary) seasonal pattern.  (This is
76 sometimes known as the \sQuote{dummy variable} version of the BSM.)
77}
78\value{
79  A list of class \code{"StructTS"} with components:
80
81  \item{coef}{the estimated variances of the components.}
82  \item{loglik}{the maximized log-likelihood.  Note that as all these
83    models are non-stationary this includes a diffuse prior for some
84    observations and hence is not comparable to \code{\link{arima}}
85    nor different types of structural models.}
86  \item{loglik0}{the maximized log-likelihood with the constant used
87    prior to \R 3.0.0, for backwards compatibility.}
88  \item{data}{the time series \code{x}.}
89  \item{residuals}{the standardized residuals.}
90  \item{fitted}{a multiple time series with one component for the level,
91    slope and seasonal components, estimated contemporaneously (that is
92    at time \eqn{t} and not at the end of the series).}
93  \item{call}{the matched call.}
94  \item{series}{the name of the series \code{x}.}
95  \item{code}{the \code{convergence} code returned by \code{\link{optim}}.}
96  \item{model, model0}{Lists representing the Kalman Filter used in the
97    fitting.  See \code{\link{KalmanLike}}.  \code{model0} is the
98    initial state of the filter, \code{model} its final state.}
99  \item{xtsp}{the \code{tsp} attributes of \code{x}.}
100}
101\references{
102  Brockwell, P. J. & Davis, R. A. (1996).
103  \emph{Introduction to Time Series and Forecasting}.
104  Springer, New York.
105  Sections 8.2 and 8.5.
106
107  Durbin, J. and Koopman, S. J. (2001) \emph{Time Series Analysis by
108    State Space Methods.}  Oxford University Press.
109
110  Harvey, A. C. (1989)
111  \emph{Forecasting, Structural Time Series Models and the Kalman Filter}.
112  Cambridge University Press.
113
114  Harvey, A. C. (1993) \emph{Time Series Models}.
115  2nd Edition, Harvester Wheatsheaf.
116}
117\note{
118  Optimization of structural models is a lot harder than many of the
119  references admit.  For example, the \code{\link{AirPassengers}} data
120  are considered in Brockwell & Davis (1996): their solution appears to
121  be a local maximum, but nowhere near as good a fit as that produced by
122  \code{StructTS}.  It is quite common to find fits with one or more
123  variances zero, and this can include \eqn{\sigma^2_\epsilon}{sigma^2_eps}.
124}
125
126\seealso{
127  \code{\link{KalmanLike}}, \code{\link{tsSmooth}};
128  \code{\link{stl}} for different kind of (seasonal) decomposition.
129}
130
131\examples{
132## see also JohnsonJohnson, Nile and AirPassengers
133require(graphics)
134
135trees <- window(treering, start = 0)
136(fit <- StructTS(trees, type = "level"))
137plot(trees)
138lines(fitted(fit), col = "green")
139tsdiag(fit)
140
141(fit <- StructTS(log10(UKgas), type = "BSM"))
142par(mfrow = c(4, 1)) # to give appropriate aspect ratio for next plot.
143plot(log10(UKgas))
144plot(cbind(fitted(fit), resids=resid(fit)), main = "UK gas consumption")
145
146## keep some parameters fixed; trace optimizer:
147StructTS(log10(UKgas), type = "BSM", fixed = c(0.1,0.001,NA,NA),
148         optim.control = list(trace = TRUE))
149}
150\keyword{ts}
151