# StructTS

##### Fit Structural Time Series

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

- Keywords
- ts

##### 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. Can be abbreviated. - 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.

##### 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 \(\mu_t\) which
evolves by
$$\mu_{t+1} = \mu_t + \xi_t, \qquad \xi_t \sim N(0, \sigma^2_\xi)$$
The observations are
$$x_t = \mu_t + \epsilon_t, \qquad \epsilon_t \sim N(0, \sigma^2_\epsilon)$$
There are two parameters, \(\sigma^2_\xi\)
and \(\sigma^2_\epsilon\). 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
\(\mu_t\), given by
$$
\mu_{t+1} = \mu_t + \nu_t + \xi_t, \qquad \xi_t \sim N(0, \sigma^2_\xi)
$$
$$
\nu_{t+1} = \nu_t + \zeta_t, \qquad \zeta_t \sim 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 = \mu_t + \gamma_t + \epsilon_t, \qquad \epsilon_t \sim N(0, \sigma^2_\epsilon)$$
where \(\gamma_t\) is a seasonal component with dynamics
$$
\gamma_{t+1} = -\gamma_t + \cdots + \gamma_{t-s+2} + \omega_t, \qquad
\omega_t \sim N(0, \sigma^2_\omega)
$$
The boundary case \(\sigma^2_\omega = 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:

`arima`

nor different types of structural models.`x`

.`x`

.`convergence`

code returned by `optim`

.`KalmanLike`

. `model0`

is the
initial state of the filter, `model`

its final state.`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_\epsilon\).

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

;
`stl`

for different kind of (seasonal) decomposition.

##### Examples

`library(stats)`

```
## 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)) # to give appropriate aspect ratio for next plot.
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))
```

*Documentation reproduced from package stats, version 3.3.3, License: Part of R 3.3.3*