020-LocalLevel.Rmd

# Local Level Model {#localLevel}

## Fitting a Local Level Model

The *local level model* assumes that we observe a time series, $y_{t}$,
and that time series is the sum of another time series, $\mu_{t}$,
and random, corrupting noise, $\epsilon_{t}$.
We would prefer to directly observe $\mu_{t}$,
a *latent* variable,
but cannot due to the noise.

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

In this model, the $\mu_{t}$ follow a random walk,
so this is sometimes called the *random walk with noise* model.
(The `dlm` package uses that name.)

The model has only three parameters.

------------------------- -----------------------------------
 $\sigma_{\epsilon}^{2}$  Variance of the observation errors
 $\sigma_{\xi}^{2}$       Variance of the state transitions
 $\mu_{0}$                Initial level of $\mu$.
------------------------- -----------------------------------

### Problem {-}
You want to fit your time series data to a local level model.

### Solution {-}
The `StructTS` function can estimate the parameters of a local level model
by setting `type="level"`.
(Here, I assume your time series data is $y$.)

```{r, eval=FALSE}
struct <- StructTS(y, type="level")
```

The function returns a list that includes these elements.

----------------- -------------------------------------------------------------------------------
`struct$coef`     2-element vector of estimated variances, labeled `level` and `epsilon`
`struct$model0`   Initial state; in particular `model0$a` is the initial level
`struct$model`    Final model
`struct$code`     Convergence code from optimizer, zero is good, non-zero is bad
----------------- -----------------------------------------------------------------------------

### Discussion {-}

### Example {-}
This example constructs a local level model for the Nile data.
```{r, eval=TRUE}
y <- datasets::Nile

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

print(struct$coef)

cat("Transitional variance:", struct$coef["level"], "\n",
    "Observational variance:", struct$coef["epsilon"], "\n",
    "Initial level:", struct$model0$a, "\n")
```

### See Also {-}

## Diagnosing a Local Level Model

### Problem {-}
After fitting a local level model, you want to assess the quality of the fit.

### Solution {-}

### Discussion {-}

### Example {-}

### See Also {-}

## Smoothing With a Local Level Model

### Problem {-}
After fitting a local level model,
you want to [smooth](#smoothingVersusFiltering) your data.

### Solution {-}

### Discussion {-}

### Example {-}

### See Also {-}

## Filtering With a Local Level Model

### Problem {-}
Using a local level model, you want to [filter](#smoothingVersusFiltering)
the time series data.

### Solution {-}

### Discussion {-}

### Example {-}

### See Also {-}


## Forecasting with a Local Level Model

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

### Solution {-}

### Discussion {-}

### Example {-}

### See Also {-}