---
title: "gum() - Generalised Univariate Model"
author: "Ivan Svetunkov"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{gum() - Generalised Univariate Model}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r global_options, include=FALSE}
knitr::opts_chunk$set(fig.width=6, fig.height=4, fig.path='Figs/', fig.show='hold',
                      warning=FALSE, message=FALSE)
```

`gum()` constructs Generalised Exponential Smoothing - pure additive state-space model. It is a part of [smooth package](smooth.html).

Let's load the necessary packages:
```{r load_libraries, message=FALSE, warning=FALSE}
require(smooth)
```

Generalised Exponential Smoothing is a next step from CES. It is a state-space model in which all the matrices and vectors are estimated. It is very demanding in sample size, but is also insanely flexible.

A simple call by default constructs GUM$(1^1,1^m)$, where $m$ is frequency of the data. So for our example with `AirPassengers` data, we will have GUM$(1^1,1^{12})$:

```{r gum_N2457}
gum(AirPassengers, h=18, holdout=TRUE)
```

But some different orders and lags can be specified. For example:
```{r gum_N2457_2[1]_1[12]}
gum(AirPassengers, h=18, holdout=TRUE, orders=c(2,1), lags=c(1,12))
```

Function `auto.gum()` is now implemented in `smooth`, but it works slowly as it needs to check a large number of models:
```{r Autogum_N2457_1[1]}
auto.gum(AirPassengers, silent=FALSE)
```

In addition to standard values that other functions accept, GUM accepts predefined values for transition matrix, measurement and persistence vectors. For example, something more common can be passed to the function:
```{r gum_N2457_predefined}
	transition <- matrix(c(1,0,0,1,1,0,0,0,1),3,3)
	measurement <- c(1,1,1)
	gum(AirPassengers, h=18, holdout=TRUE, orders=c(2,1), lags=c(1,12), transition=transition, measurement=measurement)
```

The resulting model will be equivalent to ETS(A,A,A). However due to different initialisation of optimisers and different method of number of parameters calculation, `gum()` above and `es(y, "AAA", h=h, holdout=TRUE)` will lead to different models.