030-LocalLinearTrend-StructTS.Rmd

# Local Linear Trend Model: StructTS function {#localLinearTrend}
The *local linear trend model* builds on the [local level model](#localLevel).
It adds a time-varying trend, $\nu_{t}$, that follows a random walk.
As before, we observe _y_, which is the underlying level plus noise.

\begin{eqnarray*}
  y_{t} & = & \mu_{t} + \epsilon_{t}, \qquad \epsilon_{t} \sim N(0, \sigma_{\epsilon}^{2}) \\
  \mu_{t} & = & \mu_{t-1} + \nu_{t-1} + \xi_{t}, \qquad \xi_{t} \sim N(0, \sigma_{\xi}^{2}) \\
  \nu_{t} & = & \nu_{t-1} + \zeta_{t}, \qquad \zeta_{t} \sim N(0, \sigma_{\zeta}^{2})
\end{eqnarray*}

This model has five parameters.

---------------------------  --------------------------------------------
$\sigma_{\epsilon}^{2}$      Variance of observation errors, $\epsilon$
$\sigma_{\xi}^{2}$           Variance of transition errors, $\xi$
$\sigma_{\zeta}^{2}$         Variance of slope errors, $\zeta$
$\mu_{0}$                    Initial level of $\mu$
$\nu_{0}$                    Initial level of $\nu$
---------------------------  --------------------------------------------

## Fitting a Local Linear Trend Model

### Problem {-}
You want to build a local linear trend model of your data.

### Solution {-}
Estimate the parameters by calling `StructTS` with `type="trend"`.

```{r, eval=FALSE}
struct <- StructTS(y, type="trend")
if (struct$code != 0) stop("optimizer did not converge")
```

`StructTS` returns a list that contains these elements, among others.

----------------   -----------------------------------
`struct$coef`      Vector of estimated parameters
`struct$model0`    List of initial state and levels
----------------   -----------------------------------

### Discussion {-}

### Example {-}
This code constructs a local linear trend model for the Nile River data.

```{r, eval=TRUE}
y <- datasets::Nile

struct <- StructTS(y, type="trend")
if (struct$code != 0) stop("optimizer did not converge")

print(struct$coef)

cat("Transitional variance:", struct$coef["level"], "\n",
    "Slope variance:", struct$coef["slope"], "\n",
    "Observational variance:", struct$coef["epsilon"], "\n",
    "Initial level of mu:", struct$model0$a[1], "\n",
    "Initial level of nu:", struct$model0$a[2], "\n" )
```

Oh darn.
The slope component's variance is zero,
indicating that the slope is best held constant.
We can conclude that the local linear trend model is overkill
and the simpler local level model is sufficient.
That makes for a lousy example,
but its a good reminder so check and interpret the MLE parameters carefully.
They might be telling you a story.

### See Also {-}

(Ref: dlm implementation)

## Diagnosing a Local Linear Trend Model {#diagnoseLocalLinearTrend}

### Problem {-}
After fitting a local linear trend model using `StructTS`,
you want to assess the quality of the model.

### Solution {-}
The `tsdiag` function produces plots
that are useful for evaluating your StructTS model.

```{r, eval=FALSE}
tsdiag(struct)
```

### Discussion {-}

### Example {-}
This code constructs a local linear trend model for the Nile data,
then produces diagnostics plots.

```{r, eval=TRUE, fig.height=10.5}
y <- datasets::Nile

struct <- StructTS(y, type="trend")
if (struct$code != 0) stop("optimizer did not converge")

tsdiag(struct)
```

### See Also {-}

(Ref: dlm version)

## Smoothing With a Local Linear Trend Model

### Problem {-}
After building a local linear trend model using `StructTS`,
you want to smooth the data;
that is, remove the noise component.

### Solution {-}
The `tsSmooth` function can smooth your data.
based on a state-space model created by `StructTS`.

```{r, eval=FALSE}
smoothed <- tsSmooth(struct)
```

### Discussion {-}

### Example {-}
This code estimates a local linear trend model for the Nile data,
constructs the smoothed time series, and dumps the result.

```{r, eval=TRUE}
y <- datasets::Nile

struct <- StructTS(y, type="trend")
if (struct$code != 0) stop("optimizer did not converge")

smoothed <- tsSmooth(struct)
str(smoothed)
```

A plot below illustrates the effect of smoothing
based on a local linear trend model of the Nile River data.

```{r, eval=TRUE, echo=FALSE, fig.pos="h"}
both = cbind(y=Nile, smoothed=smoothed[,1])
plot(both, plot.type="single",
     col=c("black", ALT_COLOR), lty=c("solid", ALT_STYLE),
     main="Smoothing a Local Linear Trend Model",
     ylab="Annual Flow" )
legend("topright", c("original", "smoothed"),
       col=c("black", ALT_COLOR), lty=c("solid", ALT_STYLE) )
```

### See Also {-}

(Ref: dlm version)

For an example of diagnosing a model built with the `dlm` package,
see [Diagnosing a Regression Model, Fixed Coefficients](#diagnoseRegressionFixed).

For an example of smoothing with the `dlm` package,
see [Smoothing With a Regression Model, Fixed Coefficients](#smoothRegressionFixed).

## Filtering With a Local Linear Trend Model

### Problem {-}
You want to *filter* your time series data
(that is, remove the noise) using the local linear trend model
created by `StructTS`.

### Solution {-}

The `KalmanRun` function can filter your data
using the state-space model created by `StructTS`.

```{r, eval=FALSE}
filt <- KalmanRun(y, struct)
```

### Discussion {-}

### Example {-}
This code estimates a local linear trend model for the Nile data,
constructs the filtered result, and dumps the result.

```{r, eval=TRUE}
y <- datasets::Nile

struct <- StructTS(y, type="trend")
if (struct$code != 0) stop("optimizer did not converge")

filt <- KalmanRun(y, struct$model)
str(filt)
```

A plot below illustrates the effects of filtering the Nile River data.

```{r, eval=TRUE, echo=FALSE, fig.pos="h"}
## ALT_COLOR = "red"
## ALT_STYLE = "dashed"

both = cbind(y=y, filtered=filt$states[,1])
plot(both, plot.type="single",
     col=c("black", ALT_COLOR), lty=c("solid", ALT_STYLE),
     main="Filtering a Local Linear Trend Model",
     ylab="Annual Flow" )
legend("topright", c("original", "filtered"),
       col=c("black", ALT_COLOR), lty=c("solid", ALT_STYLE) )
```

### See Also {-}

## Forecasting with a Local Linear Trend Model

### Problem {-}
Using your local linear trend model,
you want to forecast the next values in your time series.

### Solution {-}

### Discussion {-}

### Example {-}

### See Also {-}