---
title: "Forecasting pools"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Forecasting pools}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(MFF)
has_forecast <- requireNamespace("forecast", quietly = TRUE)
has_fable <- all(vapply(c("fable", "fabletools", "tsibble"), requireNamespace,
                        logical(1), quietly = TRUE))
```

## Rolling-origin pools

MFF aggregates point forecasts. For forecasting, the validation forecasts
must be produced the way the test forecasts will be: from origins that move
through time, using only the observations available at each origin.
`rolling_train()` builds such a pool for a univariate series. For every target
month \(t\) of the validation and test blocks, each model is fitted to the
observations up to \(t - h\) and its \(h\)-step-ahead forecast becomes the
candidate prediction for \(t\).

The models below are seasonal specifications for the log of the monthly
`AirPassengers` series, written with the forecast package. Each model is a
function of the training window `y` and the horizon `h`; it may return a
numeric vector or a `forecast` object.

```{r models, eval = has_forecast}
y <- log(datasets::AirPassengers)
models <- list(
  ets_aaa = function(y, h) forecast::forecast(forecast::ets(y, model = "AAA"), h = h),
  airline = function(y, h) {
    forecast::forecast(forecast::Arima(y, order = c(0, 1, 1),
                                       seasonal = c(0, 1, 1)), h = h)
  },
  stl_ets = function(y, h) forecast::stlf(y, h = h),
  seasonal_naive = function(y, h) forecast::snaive(y, h = h)
)
pool <- rolling_train(y, models, horizon = 1, n_validation = 24, n_test = 24)
pool
```

The last 24 months are test targets and the 24 months before them are
validation targets. Origins and settings are recorded with the pool.

```{r inspect, eval = has_forecast}
info <- pool_info(pool)
range(info$metadata$validation_origins)
range(info$metadata$test_origins)
```

Weights are learned on the validation forecasts only.

```{r fit, eval = has_forecast}
fit <- tune_mff(pool, clusters = 2:3, method = "fcm", m = c(1.5, 2),
                control = mff_control(seed = 21))
selected_configuration(fit)[c("clusters", "m")]
weights(fit)
evaluate(predict(fit, pool), test_observed(pool))
```

```{r series, eval = has_forecast, fig.width = 7, fig.height = 4}
plot(fit, type = "series", newdata = pool)
```

Different horizons are different forecasting tasks, so each horizon has its
own pool, for example `rolling_train(y, models, horizon = 3, ...)`. For
\(h > 1\) the validation block ends at the origin of the first test target,
\(h\) months before it, and the \(h - 1\) months in between are left out:
otherwise validation outcomes observed after a test origin would influence
the selected aggregation.
`window = "sliding"` with `window_size` fits every model to a fixed number of
recent observations instead of an expanding window. With
`mff_control(seed = )` each origin receives its own seed, and
`parallel = TRUE` distributes origins over socket workers.

## Forecasts from fable

Rolling-origin forecasts produced with fable on a stretched tsibble can be
converted directly. `horizon` selects the forecast step taken from every
origin and the last `n_test` target times form the test block; validation
targets end at the first test origin, as above. The observed tsibble must
contain only the forecast series.

```{r fable, eval = has_fable}
ap <- tsibble::as_tsibble(datasets::AirPassengers)
stretched <- tsibble::stretch_tsibble(ap, .init = 108, .step = 1)
fable_fc <- fabletools::forecast(
  fabletools::model(stretched,
                    snaive = fable::SNAIVE(log(value)),
                    ets = fable::ETS(log(value) ~ error("A") + trend("A") +
                                       season("A")),
                    drift = fable::RW(log(value) ~ drift())),
  h = 1)
fable_pool <- as_mff_pool(fable_fc, data = ap, horizon = 1, n_test = 12)
fable_pool
```

## Externally produced forecasts

Forecasts from other software enter through `mff_pool()` with
`task = "forecasting"` and time indexes. The constructor checks that the
indexes are strictly increasing and that validation precedes test; it cannot
verify how the external forecasts were produced, so they should come from a
rolling-origin scheme like the one above.
