vignette_01_baseR.Rmd

---
title: "Base R"
author: "Alexander Häußer"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Base R}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.height = 5,
  fig.width = 7
)
```

## Load package

```{r packages}
library(echos)
```

## Prepare dataset

In a first example, we want to model the well-known `AirPassenger` time series (`ts` object). The dataset contains monthly totals of international airline passengers (in thousands) from January 1949 to December 1960 with 144 observations in total. The first 132 observations are used for model training (`n_train`) and last 12 observations are used for testing (`n_ahead`). `xtrain` and `xtest` are numeric vectors containing the training and testing data.

```{r data}
# Forecast horizon
n_ahead <- 12
# Number of observations (total)
n_obs <- length(AirPassengers)
# Number of observations (training data)
n_train <- n_obs - n_ahead

# Prepare train and test data as numeric vectors
xtrain <- AirPassengers[(1:n_train)]
xtest <- AirPassengers[((n_train+1):n_obs)]

xtrain
xtest

```


## Train ESN model

The function `train_esn()` is used to automatically train an ESN to the input data `xtrain`, where the output `xmodel` is an object of class `esn`. The object `xmodel` is a list containing the `actual` and `fitted` values, `residuals`, the internal states `states_train`, estimated coefficients from the ridge regression estimation, hyperparameters, etc. We can summarize the model by using the generic S3 method `summary()` to get detailed information on the trained model.

```{r model}
# Train ESN model
xmodel <- train_esn(y = xtrain)

# Plot actual and fitted values
plot(xmodel$actual, type = "l")
lines(xmodel$fitted, col = "steelblue", lwd = 2)

# Summarize model
summary(xmodel)

```

From the output above, we get the following information about the trained model:

* Layers
  * `n_inputs`: Number of input variables
  * `n_states`: Number of internal states (i.e., the reservoir size). The internal states are the actual predictor variables in the model.
  * `n_outputs`: Number of output variables (i.e., response variables)
* Meta
  * `lags`: Lags of the output variable, which are used as model input
  * `n_diff`: Number of differences required to achieve (weak-) stationarity of the input training data
  * `n_models`: Number of models evaluated during the random search optimization to find the regularization parameter `lambda`
* Scaling
  * `scale_inputs`: Input training data are scaled to the interval `(-0.5, 0.5)`
  * `scale_win`: Input weights matrix is drawn from a random uniform distribution with interval `(-0.5, 0.5)`
  * `scale_wres`: Reservoir weight matrix is drawn from a random uniform distribution with interval `(-0.5, 0.5)`
* Hyperparameters:
  * `alpha`: Leakage rate (smoothing parameter)
  * `rho`: Spectral radius for scaling the reservoir weight matrix
  * `lambda`: Regularization parameter for the ridge regression estimation
  * `density`: The density of the reservoir weight matrix


## Forecast ESN model

The function `forecast_esn()` is used to forecast the trained model `xmodel` for `n_ahead` steps into the future. The output `xfcst` is a list of class `forecast_esn` containing the `point` forecasts, `actual` and `fitted` values, the forecast horizon `n_ahead` and the model specification `model_spec`. We can use the generic S3 method `plot()` to visualize the point forecast within `xfcst` and add the holdout test data `xtest`.

```{r forecast}
# Forecast ESN model
xfcst <- forecast_esn(xmodel, n_ahead = n_ahead)
xfcst

# Plot forecast and test data
plot(xfcst, test = xtest)

```