Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tidyverts/fasster

Forecasting with Additive Switching of Seasonality, Trend and Exogenous Regressors
https://github.com/tidyverts/fasster

Last synced: about 1 month ago
JSON representation

Forecasting with Additive Switching of Seasonality, Trend and Exogenous Regressors

Awesome Lists containing this project

README 

        
---

output:

  md_document:

    variant: markdown_github

---



```{r, echo = FALSE, message=FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#>",

  fig.path = "man/figure/"

)

```



# fasster 



[![R build status](https://github.com/tidyverts/fasster/workflows/R-CMD-check/badge.svg)](https://github.com/tidyverts/fasster)

[![lifecycle](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)

[![Coverage status](https://codecov.io/gh/tidyverts/fasster/branch/master/graph/badge.svg)](https://codecov.io/github/tidyverts/fasster?branch=master)



An implementation of the FASSTER (Forecasting with Additive Switching of Seasonality, Trend and Exogenous Regressors) model in R. This model is designed to capture patterns of multiple seasonality in a state space framework by using state switching. The *fasster* package prioritizes flexibility, computational speed and accuracy to provide convenient tools for modelling, predicting and understanding high frequency time-series.



## Development cycle



This package is early in development, and there are plans to make substantial changes in the future. 



The latest usage examples of using fasster can be found in my useR! 2018 talk: [slides](https://slides.mitchelloharawild.com/user2018/#1), [video](https://www.youtube.com/watch?v=6YlboftSalY), [source](https://github.com/mitchelloharawild/fasster_user2018).



There are further plans to improve the heuristic optimisation techniques and better use sparse matrix algebra (removing the dlm package dependency) to make fasster even faster. Implementing this will likely result in a revision of the model object structure, but user directed functionality should remain the same.



## Installation



The **development** version can be installed from GitHub using:



```{r, eval = FALSE}

# install.packages("devtools")

devtools::install_github("tidyverts/fasster")

```



## Usage



### Model specification



*fasster* allows flexible model specification by allowing the user to specify the model structure with standard formula conventions.



```{r xreg, message=FALSE}

library(fasster)

library(tidyverse)

library(lubridate)

library(tsibble)

library(fable)



lung_deaths <- as_tsibble(cbind(mdeaths, fdeaths), pivot_longer = FALSE)

fit <- lung_deaths %>%

  model(fasster = FASSTER(fdeaths ~ mdeaths))

fit %>% report()

```



Commonly used state space components can be added using the following convenience functions:



* `trend(n)` to include an n-th order polynomial

* `season(s)` to include a seasonal factor of frequency s

* `fourier(s, q)` to include seasonal fourier terms of frequency s with q harmonics

* `arma(ar, ma)` to include an ARMA term (where ar and ma are vectors of coefficients)

* Exogenous regressors can be added by referring to their name



For example, to create a model with trend and monthly seasonality, you can use:

```{r component}

fit <- as_tsibble(USAccDeaths) %>% 

  model(fasster = FASSTER(value ~ trend(1) + fourier(12)))

fit %>% report()

```



The interface for creating a FASSTER model introduces a new formula construct, `%S%`, known as the switch operator. This allows modelling of more complex patterns such as multiple seasonality by modelling the components for each group separately and switching between them.



```{r complex}

elec_tr <- tsibbledata::vic_elec %>%

  filter(

    Time < lubridate::ymd("2012-03-01")

  ) %>% 

  mutate(WorkDay = wday(Time) %in% 2:6 & !Holiday)



elec_fit <- elec_tr %>%

  model(

    fasster = fasster(log(Demand) ~ 

      WorkDay %S% (fourier(48, 16) + trend(1)) + Temperature + I(Temperature^2)

    )

  )

```



### Decomposing



Fitted FASSTER models can be decomposed to provide a description of how the underlying states function. Decomposing a FASSTER model provides aggregates of its components such as trends and seasonalities.



These components can accessed from a fitted model using the `components()` function:

```{r decompose}

fit %>% 

  components()

```



```{r decompose-complex}

elec_fit %>%

  components()

```



The tools made available by *fasster* are designed to integrate seamlessly with the tidyverse of packages, enabling familiar data manipulation and visualisation capabilities.



### Forecasting

  

*fasster* conforms to the object structure from the *fable* package, allowing common visualisation and analysis tools to be applied on FASSTER models.

```{r forecast}

fit %>% 

  forecast(h=24) %>%

  autoplot(as_tsibble(USAccDeaths))

```



Future index values are automatically produced and used where necessary in the model specification. If additional information is required by the model (such as `WorkDay` and `Temperature`) they must be included in a `tsibble` of future values passed to `new_data`.



```{r complex_fc}

elec_ts <- tsibbledata::vic_elec %>%

  filter(

    yearmonth(Time) == yearmonth("2012 Mar")

  ) %>% 

  mutate(WorkDay = wday(Time) %in% 2:6 & !Holiday) %>% 

  select(-Demand)

elec_fit %>% 

  forecast(new_data = elec_ts) %>% 

  autoplot(elec_tr)

```



---

Please note that this project is released with a [Contributor Code of Conduct](.github/CODE_OF_CONDUCT.md).

By participating in this project you agree to abide by its terms.