---
title: "smooth: forecasting using state-space models"
author: "Ivan Svetunkov"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{smooth: forecasting using state-space models}
  %\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)
```

This vignette explains how to use functions in `smooth` package, what they produce, what each field in outputs and what returned values mean. Underlying statistical models are not discussed here, but if you want to know more about them, then there is a working paper "[Smooth forecasting with the smooth package in R](https://doi.org/10.48550/arXiv.2301.01790)". Some of the features of the package are also explained in my [blog](https://openforecast.org/category/r-en/smooth/). Finally, I have a monograph [Forecasting and Analytics with the Augmented Dynamic Adaptive Model (ADAM)](https://openforecast.org/adam/), which explains the model underlying the majority of forecasting functions in the package.

The package includes the following functions:

1. [adam() - ADAM - Advanced Dynamic Adaptive Model](adam.html), the model that encompasses both ETS and ARIMA;
1. [es() - Exponential Smoothing](es.html);
2. [ssarima() - State-Space ARIMA](ssarima.html), also known as Several Seasonalities ARIMA and `msarima()`, aka Multiple Seasonal ARIMA;
3. [ces() - Complex Exponential Smoothing](ces.html);
4. [gum() - Generalised Univariate Model](gum.html);
5. [sma() - Simple Moving Average in state-space form](sma.html);
6. [Simulate functions of the package](simulate.html).
7. `smoothCombine()` - function that combines forecasts of the main univariate functions of smooth package based on information criteria.
8. [oes() - Occurrence part of iETS model](oes.html) -- function that estimates probability of occurrence of variable using one of the following model types: 1. Fixed probability; 2. Odds ratio probability; 3. Inverse odds ratio probability; 4. Direct probability; 5. General. It can also select the most appropriate model among these five. The model produced by `oes()` can then be used in any forecasting function as input variable for `occurrence` parameter. This is the new function introduced in smooth v2.5.0, substituting the old `iss()` function.

The functions (1) - (4) and (6) return object of class `smooth`, (5) returns the object of class `vsmooth`, (7) returns `smooth.sim` class and finally (8) returns `oes` or `viss` (depending on the function used). There are several methods for these classes in the package.

Some other functions, which are not considered as core and important:

1. `cma()` - Centred Moving Average based on `sma()` and `msarima()`
2. `msdecompose` - Multiple Seasonal Decomposition based on centred moving averages. Useful if a series with several frequencies need to be decomposed. The frequencies are specified separately in the `lags` parameter. Given that this function does not rely on any state space model, it might be moved to a different package at some point.

## Methods for the class `smooth`

There are several methods that can be used together with the forecasting functions of the package. When a model is saved to some object `ourModel`, these function will do some magic. Here's the list of all the available methods with brief explanations:

1. `print(ourModel)` -- function prints brief output with explanation of what was fitted, with what parameters and errors;
2. `summary(ourModel)` -- returns an output with parameters, standard errors and confidence intervals in case of `adam()` function. For the other functions it is equivalent to `print(ourModel)`;
3. `actuals(ourModel)` -- returns actual values;
4. `fitted(ourModel)` -- fitted values of the model;
5. `residuals(ourModel)` -- residuals of constructed model;
6. `rstandard(ourModel)` -- standardised residuals of the model;
7. `rstudent(ourModel)` -- studentised residuals of the model;
8. `rmultistep(ourModel)` -- returns in sample multiple steps ahead forecast errors;
9. `AIC(ourModel)`, `BIC(ourModel)`, `AICc(ourModel)` and `BICc(ourModel)` -- information criteria of the constructed model. `AICc()` and `BICc()` functions are not standard `stats` functions and are imported from `greybox` package and modified in `smooth` for the specific models;
10. `plot(ourModel)` -- produces plots for the diagnostics of the constructed model. There are 9 options of what to produce, see `?plot.smooth()` for more details. Note that if the number of states is higher than 10, then several graphs are produced for the option `which=9`.
11. `forecast(ourModel)` -- point and interval forecasts. Returns object of class `smooth.forecast`;
12. `plot(forecast(ourModel))` -- produces graph with actuals, forecast, fitted and prediction interval using `graphmaker()` function from `greybox` package.
13. `simulate(ourModel)` -- produces data simulated from provided model (not supported by `adam()` yet);
14. `logLik(ourModel)` -- returns log-likelihood of the model;
15. `nobs(ourModel)` -- returns number of observations in-sample we had;
16. `nparam(ourModel)` -- number of estimated parameters (originally from `greybox` package);
17. `pointLik(ourModel)` -- likelihood values for each separate observation;
18. `sigma(ourModel)` -- variance of the residuals of the model;
19. `lags(ourModel)` -- lags of the model (used with `ssarima()` and `gum()`);
20. `orders(ourModel)` -- orders of the model (can be used with `ssarima()`, `gum()` and `sma()`);
21. `modelType(ourModel)` -- returns the type of the model. Returns something like "MMM" for ETS(MMM). Can be used with `es()`, `ces()` and `ets()`;
22. `errorType(ourModel)` -- the type of the error of a model (additive or multiplicative);
23. `coef(ourModel)` -- returns the vector of all the estimated coefficients of the model;
24. `confint(ourModel)` -- returns confidence intervals for parameters of the model. Only works with `adam()`;
25. `vcov(ourModel)` -- returns the covariance matrix of parameters. Only works with `adam()`;
26. `coefbootstrap(ourModel)` -- returns the bootstrapped coefficients of model (imported from `greybox` package). Only works with `adam()`;
27. `formula(ourModel)` -- returns the formula for the measurement equation. This is a proper formula in case of `adam()` and only decorative one for all the other functions;
28. `multicov(ourModel)` -- covariance matrix of multiple steps ahead forecast errors;
29. `refit(ourModel)` -- produces bootstrapped trajectories from `adam()` model. Only works with `adam()`;
30. `reforecast(ourModel)` -- produces forecasts based on bootstrapped trajectories from a model. Only works with `adam()`;