02-model-accessors.Rmd

# Accessing model elements

## Display

The `print` and `summary` methods are standard displays for fitted models. The `print` method typically displays a limited amount of key information, such as the model that was fit, and the estimated coefficients. The `summary` function extends the `print` method with a more detailed summary of fit, which may include measures for goodness of fit, and significance of model terms.

As fable naturally supports batch/multiple forecasting, the print method is standardised for any number of models. A very short model specific display can be defined using the `model_sum` generic, which is shown in the mable.

```{r ets-fit}
library(tsibbledata)
UKLungDeaths <- as_tsibble(cbind(mdeaths, fdeaths), gather = FALSE)
ets_fit <- UKLungDeaths %>% 
  model(ETS(mdeaths))
```
```{r mable-print, echo = FALSE}
ets_fit
```

The summary method can then be used to reveal more information about this model, such as fitted parameters and goodness of fit. Ideally this information would also be standardised into a tabular form for batch modelling, although this is currently not the case.
```{r ets-summary}
ets_fit %>% 
  summary
```

## Fitted values and residuals

Accessors for fitted values and residuals return a tsibble containing the index from the original data, with a measured variables for `.fitted` values and `.resids`. If the mable contains more than one model, the resulting object maintains and respects the key structure.

```{r ets-fitted}
ets_fit %>% 
  fitted
```

```{r ets-resid}
ets_fit %>% 
  residuals
```

## Broom functionality

Common features from a model can also be accessed using verbs from the [broom package](https://github.com/tidymodels/broom). Again, key structures that exist within the mable are respected.

```{r ets-augment}
ets_fit %>% 
  augment
```
```{r ets-tidy, eval = FALSE}
ets_fit %>% 
  tidy
```
```{r ets-glance}
ets_fit %>% 
  glance
```

## Components

In many cases, a model can be used to extract features or components from data in a similar way to decomposition methods. We use the `components` verb to extract a tsibble of data features that have been extracted via modelling or decomposition.

State space models such as `ETS` are well suited to this functionality as the states often represent features of interest.
```{r components, eval = FALSE}
UKLungDeaths %>% 
  model(ETS(mdeaths)) %>% 
  components
```
```{r components-display, echo = FALSE}
mdeaths_components <- ets_fit %>% 
  components
mdeaths_components
mdeaths_components %>% 
  gather(state, value, -.model, -index) %>% 
  ggplot(aes(x = index, y = value)) + 
  geom_line() + 
  facet_grid(state ~ ., scales = "free_y", switch = "y") + 
  theme_minimal() + 
  ylab(NULL)
```

It may also be worth storing how these components can be used to produce the response, which can be used for [decomposition modelling](https://mitchelloharawild.github.io/tidy-forecasting-principles/advanced.html#decomposition).