# 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

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

nor different types of structural models.loglik0 the maximized log-likelihood with the constant used prior to R3.0.0, for backwards compatibility. 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`

.

##### 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, License: Part of R 3.3*