-
Notifications
You must be signed in to change notification settings - Fork 16
Expand file tree
/
Copy pathREADME.Rmd
More file actions
139 lines (105 loc) · 5.27 KB
/
README.Rmd
File metadata and controls
139 lines (105 loc) · 5.27 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
---
output:
md_document:
variant: gfm
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE, message=FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figure/"
)
```
# fasster <a href="https://fasster.tidyverts.org"><img src="man/figures/logo.png" align="right" height="139" alt="fasster website" /></a>
<!-- badges: start -->
[](https://github.com/tidyverts/fasster/actions/workflows/R-CMD-check.yaml)
[](https://lifecycle.r-lib.org/articles/stages.html#stable)
[](https://github.com/tidyverts/fasster)
[](https://github.com/tidyverts/fasster)
<!-- badges: end -->
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.
## Model information
This model was developed in 2017 for an honours thesis, and the clearest description with examples of using fasster can be found in my useR! 2018 talk: [slides](https://slides.mitchelloharawild.com/user2018/), [video](https://www.youtube.com/watch?v=6YlboftSalY), [source](https://github.com/mitchelloharawild/talk-user2018-fasster).
The model uses a forward filtering backward smoothing heuristic for estimating the initial states in the model. It is essentially an opinionated wrapper of the `{dlm}` package aimed at making it easier to specify a sophisticated model suitable for forecasting complex seasonal patterns.
## Installation
The **stable** version can be installed from CRAN:
```{r, eval = FALSE}
install.packages("fasster")
```
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)
```