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

A list of class `"StructTS"`

with components:

the estimated variances of the components.

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.

the maximized log-likelihood with the constant used prior to R 3.0.0, for backwards compatibility.

the time series `x`

.

the standardized residuals.

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

the matched call.

the name of the series `x`

.

the `convergence`

code returned by `optim`

.

Lists representing the Kalman Filter used in the
fitting. See `KalmanLike`

. `model0`

is the
initial state of the filter, `model`

its final state.

the `tsp`

attributes of `x`

.

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

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.

`KalmanLike`

, `tsSmooth`

;
`stl`

for different kind of (seasonal) decomposition.

# NOT RUN { ## 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)) # }