Title:	Core Tools for Packages in the 'fable' Framework
Version:	0.5.0
Description:	Provides tools, helpers and data structures for developing models and time series functions for 'fable' and extension packages. These tools support a consistent and tidy interface for time series modelling and analysis.
License:	GPL-3
URL:	https://fabletools.tidyverts.org/, https://github.com/tidyverts/fabletools
BugReports:	https://github.com/tidyverts/fabletools/issues
Depends:	R (≥ 3.1.3)
Imports:	tsibble (≥ 0.9.0), tibble (≥ 1.4.1), ggplot2 (≥ 3.0.0), tidyselect, rlang (≥ 0.4.5), stats, dplyr (≥ 1.0.0), tidyr (≥ 1.1.0), generics, R6, utils, vctrs (≥ 0.2.2), distributional (≥ 0.3.0.9000), progressr, lifecycle, ggdist, scales
Suggests:	covr, crayon, fable (≥ 0.2.0), future, future.apply, knitr, pillar (≥ 1.0.1), feasts (≥ 0.1.2), rmarkdown, spelling, testthat, tsibbledata (≥ 0.2.0), lubridate, urca, mvtnorm, Matrix
VignetteBuilder:	knitr
RdMacros:	lifecycle
ByteCompile:	true
Encoding:	UTF-8
Language:	en-GB
RoxygenNote:	7.3.1
NeedsCompilation:	no
Packaged:	2024-09-17 03:49:23 UTC; mitchell
Author:	Mitchell O'Hara-Wild [aut, cre], Rob Hyndman [aut], Earo Wang [aut], Di Cook [ctb], George Athanasopoulos [ctb], David Holt [ctb]
Maintainer:	Mitchell O'Hara-Wild <mail@mitchelloharawild.com>
Repository:	CRAN
Date/Publication:	2024-09-17 07:30:02 UTC

fabletools: Core Tools for Packages in the 'fable' Framework

Description

Provides tools, helpers and data structures for developing models and time series functions for 'fable' and extension packages. These tools support a consistent and tidy interface for time series modelling and analysis.

Author(s)

Maintainer: Mitchell O'Hara-Wild mail@mitchelloharawild.com (ORCID)

Authors:

• Rob Hyndman

• Earo Wang (ORCID)

Other contributors:

• Di Cook [contributor]

• George Athanasopoulos [contributor]

• David Holt [contributor]

See Also

Useful links:

• https://fabletools.tidyverts.org/

• https://github.com/tidyverts/fabletools

• Report bugs at https://github.com/tidyverts/fabletools/issues

Compute Impulse Response Function (IRF)

Description

This function calculates the impulse response function (IRF) of a time series model. The IRF describes how a model's variables react to external shocks over time.

Usage

IRF(x, ...)

Arguments

Details

If new_data contains the .impulse column, those values will be treated as impulses for the calculated impulse responses.

The impulse response function provides insight into the dynamic behaviour of a system in response to external shocks. It traces the effect of a one-unit change in the impulse variable on the response variable over a specified number of periods.

Mean Arctangent Absolute Percentage Error

Description

Mean Arctangent Absolute Percentage Error

Usage

MAAPE(.resid, .actual, na.rm = TRUE, ...)

Arguments

References

Kim, Sungil and Heeyoung Kim (2016) "A new metric of absolute percentage error for intermittent demand forecasts". International Journal of Forecasting, 32(3), 669-679.

Directional accuracy measures

Description

A collection of accuracy measures based on the accuracy of the prediction's direction (say, increasing or decreasing).

Usage

MDA(.resid, .actual, na.rm = TRUE, reward = 1, penalty = 0, ...)

MDV(.resid, .actual, na.rm = TRUE, ...)

MDPV(.resid, .actual, na.rm = TRUE, ...)

directional_accuracy_measures

Arguments

Format

An object of class list of length 3.

Details

MDA(): Mean Directional Accuracy MDV(): Mean Directional Value MDPV(): Mean Directional Percentage Value

References

Blaskowitz and H. Herwartz (2011) "On economic evaluation of directional forecasts". International Journal of Forecasting, 27(4), 1058-1065.

Point estimate accuracy measures

Description

Point estimate accuracy measures

Usage

ME(.resid, na.rm = TRUE, ...)

MSE(.resid, na.rm = TRUE, ...)

RMSE(.resid, na.rm = TRUE, ...)

MAE(.resid, na.rm = TRUE, ...)

MPE(.resid, .actual, na.rm = TRUE, ...)

MAPE(.resid, .actual, na.rm = TRUE, ...)

MASE(
  .resid,
  .train,
  demean = FALSE,
  na.rm = TRUE,
  .period,
  d = .period == 1,
  D = .period > 1,
  ...
)

RMSSE(
  .resid,
  .train,
  demean = FALSE,
  na.rm = TRUE,
  .period,
  d = .period == 1,
  D = .period > 1,
  ...
)

ACF1(.resid, na.action = stats::na.pass, demean = TRUE, ...)

point_accuracy_measures

Arguments

Format

An object of class list of length 8.

Evaluate accuracy of a forecast or model

Description

Summarise the performance of the model using accuracy measures. Accuracy measures can be computed directly from models as the one-step-ahead fitted residuals are available. When evaluating accuracy on forecasts, you will need to provide a complete dataset that includes the future data and data used to train the model.

Usage

## S3 method for class 'mdl_df'
accuracy(object, measures = point_accuracy_measures, ...)

## S3 method for class 'mdl_ts'
accuracy(object, measures = point_accuracy_measures, ...)

## S3 method for class 'fbl_ts'
accuracy(object, data, measures = point_accuracy_measures, ..., by = NULL)

Arguments

See Also

Evaluating forecast accuracy

Examples

library(fable)
library(tsibble)
library(tsibbledata)
library(dplyr)

fit <- aus_production %>%
  filter(Quarter < yearquarter("2006 Q1")) %>% 
  model(ets = ETS(log(Beer) ~ error("M") + trend("Ad") + season("A")))

# In-sample training accuracy does not require extra data provided.
accuracy(fit)

# Out-of-sample forecast accuracy requires the future values to compare with.
# All available future data will be used, and a warning will be given if some
# data for the forecast window is unavailable.
fc <- fit %>% 
  forecast(h = "5 years")
fc %>% 
  accuracy(aus_production)
  
# It is also possible to compute interval and distributional measures of
# accuracy for models and forecasts which give forecast distributions.
fc %>% 
  accuracy(
    aus_production,
    measures = list(interval_accuracy_measures, distribution_accuracy_measures)
  )

Create an aggregation vector

Description

Usage

agg_vec(x = character(), aggregated = logical(vec_size(x)))

Arguments

Details

An aggregation vector extends usual vectors by adding ⁠<aggregated>⁠ values. These vectors are typically produced via the aggregate_key() function, however it can be useful to create them manually to produce more complicated hierarchies (such as unbalanced hierarchies).

Examples

agg_vec(
  x = c(NA, "A", "B"),
  aggregated = c(TRUE, FALSE, FALSE)
)

Expand a dataset to include temporal aggregates

Description

Usage

aggregate_index(.data, .window, ..., .offset = "end", .bin_size = NULL)

Arguments

Details

This feature is very experimental. It currently allows for temporal aggregation of daily data as a proof of concept.

The aggregation .window can be specified in several ways:

• A character string, containing one of "day", "week", "month", "quarter" or "year". This can optionally be preceded by a (positive or negative) integer and a space, or followed by "s".

• A number, taken to be in days.

• A difftime object.

Examples

library(tsibble)
pedestrian %>%
  # Currently only supports daily data
  index_by(Date) %>% 
  dplyr::summarise(Count = sum(Count)) %>% 
  # Compute weekly aggregates
  fabletools:::aggregate_index("1 week", Count = sum(Count))

Expand a dataset to include other levels of aggregation

Description

Uses the structural specification given in .spec to aggregate a time series. A grouped structure is specified using grp1 * grp2, and a nested structure is specified via parent / child. Aggregating the key structure is commonly used with forecast reconciliation to produce coherent forecasts over some hierarchy.

Usage

aggregate_key(.data, .spec, ...)

Arguments

Details

This function is experimental, and is subject to change in the future.

The way in which the measured variables are aggregated is specified in a similar way to how ⁠[dplyr::summarise()]⁠ is used.

See Also

reconcile(), is_aggregated()

Examples

library(tsibble)
tourism %>% 
  aggregate_key(Purpose * (State / Region), Trips = sum(Trips))

Internal vctrs methods

Description

These methods are the extensions that allow aggregation vectors to work with vctrs.

Usage

## S3 method for class 'agg_vec'
vec_ptype2(x, y, ...)

## S3 method for class 'agg_vec.agg_vec'
vec_ptype2(x, y, ...)

## S3 method for class 'agg_vec.default'
vec_ptype2(x, y, ...)

## S3 method for class 'agg_vec.character'
vec_ptype2(x, y, ...)

## S3 method for class 'character.agg_vec'
vec_ptype2(x, y, ...)

## S3 method for class 'agg_vec'
vec_ptype_abbr(x, ...)

## S3 method for class 'agg_vec'
vec_cast(x, to, ...)

## S3 method for class 'agg_vec.agg_vec'
vec_cast(x, to, ...)

## S3 method for class 'agg_vec.default'
vec_cast(x, to, ...)

## S3 method for class 'character.agg_vec'
vec_cast(x, to, ...)

## S3 method for class 'agg_vec'
vec_proxy_compare(x, ...)

Coerce to a dable object

Description

Coerce to a dable object

Usage

as_dable(x, ...)

## S3 method for class 'tbl_df'
as_dable(x, response, method = NULL, seasons = list(), aliases = list(), ...)

## S3 method for class 'tbl_ts'
as_dable(x, response, method = NULL, seasons = list(), aliases = list(), ...)

Arguments

Coerce to a fable object

Description

Coerce to a fable object

Usage

as_fable(x, ...)

## S3 method for class 'tbl_ts'
as_fable(x, response, distribution, ...)

## S3 method for class 'grouped_ts'
as_fable(x, response, distribution, ...)

## S3 method for class 'tbl_df'
as_fable(x, response, distribution, ...)

## S3 method for class 'fbl_ts'
as_fable(x, response, distribution, ...)

## S3 method for class 'grouped_df'
as_fable(x, response, distribution, ...)

## S3 method for class 'forecast'
as_fable(x, ..., point_forecast = list(.mean = mean))

Arguments

Coerce a dataset to a mable

Description

Coerce a dataset to a mable

Usage

as_mable(x, ...)

## S3 method for class 'data.frame'
as_mable(x, key = NULL, model = NULL, ...)

Arguments

Augment a mable

Description

Uses a fitted model to augment the response variable with fitted values and residuals. Response residuals (back-transformed) are stored in the .resid column, while innovation residuals (transformed) are stored in the .innov column.

Usage

## S3 method for class 'mdl_df'
augment(x, ...)

## S3 method for class 'mdl_ts'
augment(x, type = NULL, ...)

Arguments

Examples

library(fable)
library(tsibbledata)

# Forecasting with an ETS(M,Ad,A) model to Australian beer production
aus_production %>%
  model(ets = ETS(log(Beer) ~ error("M") + trend("Ad") + season("A"))) %>% 
  augment()

Decomposition plots

Description

Produces a faceted plot of the components used to build the response variable of the dable. Useful for visualising how the components contribute in a decomposition or model.

Usage

## S3 method for class 'dcmp_ts'
autoplot(object, .vars = NULL, scale_bars = TRUE, level = c(80, 95), ...)

Arguments

Examples

library(feasts)
library(tsibbledata)
aus_production %>% 
  model(STL(Beer)) %>%
  components() %>%  
  autoplot()

Plot a set of forecasts

Description

Produces a forecast plot from a fable. As the original data is not included in the fable object, it will need to be specified via the data argument. The data argument can be used to specify a shorter period of data, which is useful to focus on the more recent observations.

Usage

## S3 method for class 'fbl_ts'
autoplot(object, data = NULL, level = c(80, 95), show_gap = TRUE, ...)

## S3 method for class 'fbl_ts'
autolayer(
  object,
  data = NULL,
  level = c(80, 95),
  point_forecast = list(mean = mean),
  show_gap = TRUE,
  ...
)

Arguments

Examples

library(fable)
library(tsibbledata)

fc <- aus_production %>%
  model(ets = ETS(log(Beer) ~ error("M") + trend("Ad") + season("A"))) %>% 
  forecast(h = "3 years") 

fc %>% 
  autoplot(aus_production)


aus_production %>% 
  autoplot(Beer) + 
  autolayer(fc)

Plot time series from a tsibble

Description

Produces a time series plot of one or more variables from a tsibble. If the tsibble contains a multiple keys, separate time series will be identified by colour.

Usage

## S3 method for class 'tbl_ts'
autoplot(object, .vars = NULL, ...)

## S3 method for class 'tbl_ts'
autolayer(object, .vars = NULL, ...)

Arguments

Examples

library(fable)
library(tsibbledata)
library(tsibble)

tsibbledata::gafa_stock %>%
 autoplot(vars(Close, log(Close)))

Bias adjust back-transformation functions

Description

To produce forecast means (instead of forecast medians) it is necessary to adjust the back-transformation function relative to the forecast variance.

Usage

bias_adjust(bt, sd)

Arguments

Details

More details about bias adjustment can be found in the transformations vignette: read the vignette: vignette("transformations", package = "fable")

Examples

adj_fn <- bias_adjust(function(x) exp(x), 1:10)
y <- rnorm(10)
exp(y)
adj_fn(y)

Bottom up forecast reconciliation

Description

Usage

bottom_up(models)

Arguments

Details

Reconciles a hierarchy using the bottom up reconciliation method. The response variable of the hierarchy must be aggregated using sums. The forecasted time points must match for all series in the hierarchy.

See Also

reconcile(), aggregate_key()

Box Cox Transformation

Description

box_cox() returns a transformation of the input variable using a Box-Cox transformation. inv_box_cox() reverses the transformation.

Usage

box_cox(x, lambda)

inv_box_cox(x, lambda)

Arguments

Details

The Box-Cox transformation is given by

f_\lambda(x) =\frac{x^\lambda - 1}{\lambda}

if \lambda\ne0. For \lambda=0,

f_0(x)=\log(x)

.

Value

a transformed numeric vector of the same length as x.

Author(s)

Rob J Hyndman & Mitchell O'Hara-Wild

References

Box, G. E. P. and Cox, D. R. (1964) An analysis of transformations. JRSS B 26 211–246.

Examples

library(tsibble)
library(dplyr)
airmiles %>% 
  as_tsibble() %>% 
  mutate(box_cox = box_cox(value, lambda = 0.3))

Ensemble combination

Description

Ensemble combination

Usage

combination_ensemble(..., weights = c("equal", "inv_var"))

Arguments

See Also

combination_weighted()

Combination modelling

Description

Combines multiple model definitions (passed via ...) to produce a model combination definition using some combination function (cmbn_fn). Currently distributional forecasts are only supported for models producing normally distributed forecasts.

Usage

combination_model(..., cmbn_fn = combination_ensemble, cmbn_args = list())

Arguments

Details

A combination model can also be produced using mathematical operations.

Examples

library(fable)
library(tsibble)
library(tsibbledata)

# cmbn1 and cmbn2 are equivalent and equally weighted.
aus_production %>%
  model(
    cmbn1 = combination_model(SNAIVE(Beer), TSLM(Beer ~ trend() + season())),
    cmbn2 = (SNAIVE(Beer) + TSLM(Beer ~ trend() + season()))/2
  )

# An inverse variance weighted ensemble.
aus_production %>%
  model(
    cmbn1 = combination_model(
      SNAIVE(Beer), TSLM(Beer ~ trend() + season()), 
      cmbn_args = list(weights = "inv_var")
    )
  )

Weighted combination

Description

Weighted combination

Usage

combination_weighted(..., weights = NULL)

Arguments

See Also

combination_ensemble()

Extract frequencies for common seasonal periods

Description

Extract frequencies for common seasonal periods

Usage

common_periods(x)

## Default S3 method:
common_periods(x)

## S3 method for class 'tbl_ts'
common_periods(x)

## S3 method for class 'interval'
common_periods(x)

get_frequencies(period, ...)

## S3 method for class 'numeric'
get_frequencies(period, ...)

## S3 method for class ''NULL''
get_frequencies(period, data, ..., .auto = c("smallest", "largest", "all"))

## S3 method for class 'character'
get_frequencies(period, data, ...)

## S3 method for class 'Period'
get_frequencies(period, data, ...)

Arguments

Value

A named vector of frequencies appropriate for the provided data.

References

https://robjhyndman.com/hyndsight/seasonal-periods/

Examples

common_periods(tsibble::pedestrian)

Common exogenous regressors

Description

These special functions provide interfaces to more complicated functions within the model formulae interface.

Usage

common_xregs

Specials

trend

The trend special includes common linear trend regressors in the model. It also supports piecewise linear trend via the knots argument.

trend(knots = NULL, origin = NULL)

season

The season special includes seasonal dummy variables in the model.

season(period = NULL)

fourier

The fourier special includes seasonal fourier terms in the model. The maximum order of the fourier terms must be specified using K.

fourier(period = NULL, K, origin = NULL)

Extract components from a fitted model

Description

Allows you to extract elements of interest from the model which can be useful in understanding how they contribute towards the overall fitted values.

Usage

## S3 method for class 'mdl_df'
components(object, ...)

## S3 method for class 'mdl_ts'
components(object, ...)

Arguments

Details

A dable will be returned, which will allow you to easily plot the components and see the way in which components are combined to give forecasts.

Examples

library(fable)
library(tsibbledata)

# Forecasting with an ETS(M,Ad,A) model to Australian beer production
aus_production %>%
  model(ets = ETS(log(Beer) ~ error("M") + trend("Ad") + season("A"))) %>% 
  components() %>% 
  autoplot()

Construct a new set of forecasts

Description

This function is deprecated. forecast() methods for a model should return a vector of distributions using the distributional package.

Backtransformations are automatically handled, and so no transformations should be specified here.

Usage

construct_fc(point, sd, dist)

Arguments

Create a dable object

Description

A dable (decomposition table) data class (dcmp_ts) which is a tsibble-like data structure for representing decompositions. This data class is useful for representing decompositions, as its print method describes how its columns can be combined to produce the original data, and has a more appropriate autoplot() method for displaying decompositions. Beyond this, a dable (dcmp_ts) behaves very similarly to a tsibble (tbl_ts).

Usage

dable(..., response, method = NULL, seasons = list(), aliases = list())

Arguments

Internal vctrs methods

Description

These methods are the extensions that allow dable objects to work with vctrs.

Usage

## S3 method for class 'dcmp_ts'
vec_ptype2(x, y, ...)

## S3 method for class 'dcmp_ts'
vec_cast(x, to, ...)

Decomposition modelling

Description

This function allows you to specify a decomposition combination model using any additive decomposition. It works by first decomposing the data using the decomposition method provided to dcmp_fn with the given formula. Secondary models are used to fit each of the components from the resulting decomposition. These models are specified after the decomposition formula. All non-seasonal decomposition components must be specified, and any unspecified seasonal components will be forecasted using seasonal naive. These component models will be combined according to the decomposition method, giving a combination model for the response of the decomposition.

Usage

decomposition_model(dcmp, ...)

Arguments

See Also

Forecasting: Principles and Practice - Forecasting Decomposition

Examples

library(fable)
library(feasts)
library(tsibble)
library(dplyr)

vic_food <- tsibbledata::aus_retail %>% 
  filter(State == "Victoria", Industry == "Food retailing")
  
# Identify an appropriate decomposition
vic_food %>% 
  model(STL(log(Turnover) ~ season(window = Inf))) %>% 
  components() %>% 
  autoplot()
  
# Use an ETS model to seasonally adjusted data, and SNAIVE to season_year
# Any model can be used, and seasonal components will default to use SNAIVE.
my_dcmp_spec <- decomposition_model(
  STL(log(Turnover) ~ season(window = Inf)),
  ETS(season_adjust ~ season("N")), SNAIVE(season_year)
)

vic_food %>%
  model(my_dcmp_spec) %>% 
  forecast(h="5 years") %>% 
  autoplot(vic_food)

Return distribution variable

Description

distribution_var() returns a character vector of the distribution variable in the data.

Usage

distribution_var(x)

Arguments

Estimate a model

Description

Estimate a model

Usage

estimate(.data, ...)

## S3 method for class 'tbl_ts'
estimate(.data, .model, ...)

Arguments

Create a fable object

Description

A fable (forecast table) data class (fbl_ts) which is a tsibble-like data structure for representing forecasts. In extension to the key and index from the tsibble (tbl_ts) class, a fable (fbl_ts) must also contain a single distribution column that uses values from the distributional package.

Usage

fable(..., response, distribution)

Arguments

Internal vctrs methods

Description

These methods are the extensions that allow fable objects to work with vctrs.

Usage

## S3 method for class 'fbl_ts'
vec_ptype2(x, y, ...)

## S3 method for class 'fbl_ts'
vec_cast(x, to, ...)

Create a feature set from tags

Description

Construct a feature set from features available in currently loaded packages. Lists of available features can be found in the following pages:

• Features by package

• Features by tag

Usage

feature_set(pkgs = NULL, tags = NULL)

Arguments

Registering features

Features can be registered for use with the feature_set() function using register_feature(). This function allows you to register a feature along with the tags associated with it. If the features are being registered from within a package, this feature registration should happen at load time using ⁠[.onLoad()]⁠.

Extract features from a dataset

Description

Create scalar valued summary features for a dataset from feature functions.

Usage

features(.tbl, .var, features, ...)

features_at(.tbl, .vars, features, ...)

features_all(.tbl, features, ...)

features_if(.tbl, .predicate, features, ...)

Arguments

Details

Lists of available features can be found in the following pages:

• Features by package

• Features by tag

See Also

feature_set()

Examples

# Provide a set of functions as a named list to features.
library(tsibble)
tourism %>% 
  features(Trips, features = list(mean = mean, sd = sd))

# Search and use useful features with `feature_set()`. 


library(feasts)

tourism %>% 
  features(Trips, features = feature_set(tags = "autocorrelation"))

# Best practice is to use anonymous functions for additional arguments
tourism %>% 
  features(Trips, list(~ quantile(., probs=seq(0,1,by=0.2))))

Features by package

Description

This documentation lists all available in currently loaded packages. This is a useful reference for making a feature_set() from particular package(s).

Details

No features found in currently loaded packages.

See Also

features_by_tag

Features by tag

Description

This documentation lists all available in currently loaded packages. This is a useful reference for making a feature_set() from particular tag(s).

Details

No features found in currently loaded packages.

See Also

features_by_pkg

Extract fitted values from models

Description

Extracts the fitted values from each of the models in a mable. A tsibble will be returned containing these fitted values. Fitted values will be automatically back-transformed if a transformation was specified.

Usage

## S3 method for class 'mdl_df'
fitted(object, ...)

## S3 method for class 'mdl_ts'
fitted(object, h = 1, ...)

Arguments

Produce forecasts

Description

The forecast function allows you to produce future predictions of a time series from fitted models. If the response variable has been transformed in the model formula, the transformation will be automatically back-transformed (and bias adjusted if bias_adjust is TRUE). More details about transformations in the fable framework can be found in vignette("transformations", package = "fable").

Usage

## S3 method for class 'mdl_df'
forecast(
  object,
  new_data = NULL,
  h = NULL,
  point_forecast = list(.mean = mean),
  ...
)

## S3 method for class 'mdl_ts'
forecast(
  object,
  new_data = NULL,
  h = NULL,
  bias_adjust = NULL,
  simulate = FALSE,
  bootstrap = FALSE,
  times = 5000,
  point_forecast = list(.mean = mean),
  ...
)

Arguments

Details

The forecasts returned contain both point forecasts and their distribution. A specific forecast interval can be extracted from the distribution using the hilo() function, and multiple intervals can be obtained using report(). These intervals are stored in a single column using the hilo class, to extract the numerical upper and lower bounds you can use unpack_hilo().

Value

A fable containing the following columns:

• .model: The name of the model used to obtain the forecast. Taken from the column names of models in the provided mable.

• The forecast distribution. The name of this column will be the same as the dependent variable in the model(s). If multiple dependent variables exist, it will be named .distribution.

• Point forecasts computed from the distribution using the functions in the point_forecast argument.

• All columns in new_data, excluding those whose names conflict with the above.

Examples

library(fable)
library(tsibble)
library(tsibbledata)
library(dplyr)
library(tidyr)

# Forecasting with an ETS(M,Ad,A) model to Australian beer production
beer_fc <- aus_production %>%
  model(ets = ETS(log(Beer) ~ error("M") + trend("Ad") + season("A"))) %>% 
  forecast(h = "3 years")

# Compute 80% and 95% forecast intervals
beer_fc %>% 
  hilo(level = c(80, 95))

beer_fc %>% 
  autoplot(aus_production)

# Forecasting with a seasonal naive and linear model to the monthly 
# "Food retailing" turnover for each Australian state/territory.
library(dplyr)
aus_retail %>% 
  filter(Industry == "Food retailing") %>% 
  model(
    snaive = SNAIVE(Turnover),
    ets = TSLM(log(Turnover) ~ trend() + season()),
  ) %>% 
  forecast(h = "2 years 6 months") %>% 
  autoplot(filter(aus_retail, Month >= yearmonth("2000 Jan")), level = 90)
  
# Forecast GDP with a dynamic regression model on log(GDP) using population and
# an automatically chosen ARIMA error structure. Assume that population is fixed
# in the future.
aus_economy <- global_economy %>% 
  filter(Country == "Australia")
fit <- aus_economy %>% 
  model(lm = ARIMA(log(GDP) ~ Population))

future_aus <- new_data(aus_economy, n = 10) %>% 
  mutate(Population = last(aus_economy$Population))

fit %>% 
  forecast(new_data = future_aus) %>% 
  autoplot(aus_economy)

Generate responses from a mable

Description

Use a model's fitted distribution to simulate additional data with similar behaviour to the response. This is a tidy implementation of stats::simulate().

Usage

## S3 method for class 'mdl_df'
generate(x, new_data = NULL, h = NULL, times = 1, seed = NULL, ...)

## S3 method for class 'mdl_ts'
generate(
  x,
  new_data = NULL,
  h = NULL,
  times = 1,
  seed = NULL,
  bootstrap = FALSE,
  bootstrap_block_size = 1,
  ...
)

Arguments

Details

Innovations are sampled by the model's assumed error distribution. If bootstrap is TRUE, innovations will be sampled from the model's residuals. If new_data contains the .innov column, those values will be treated as innovations for the simulated paths.

Examples

library(fable)
library(dplyr)
UKLungDeaths <- as_tsibble(cbind(mdeaths, fdeaths), pivot_longer = FALSE)
UKLungDeaths %>% 
  model(lm = TSLM(mdeaths ~ fourier("year", K = 4) + fdeaths)) %>% 
  generate(UKLungDeaths, times = 5)

Glance a mable

Description

Uses the models within a mable to produce a one row summary of their fits. This typically contains information about the residual variance, information criterion, and other relevant summary statistics. Each model will be represented with a row of output.

Usage

## S3 method for class 'mdl_df'
glance(x, ...)

## S3 method for class 'mdl_ts'
glance(x, ...)

Arguments

Examples

library(fable)
library(tsibbledata)

olympic_running %>%
  model(lm = TSLM(log(Time) ~ trend())) %>% 
  glance()

Run a hypothesis test from a mable

Description

This function will return the results of a hypothesis test for each model in the mable.

Usage

## S3 method for class 'mdl_df'
hypothesize(x, ...)

## S3 method for class 'mdl_ts'
hypothesize(x, tests = list(), ...)

Arguments

Examples

library(fable)
library(tsibbledata)

olympic_running %>%
  model(lm = TSLM(log(Time) ~ trend())) %>% 
  hypothesize()

Interpolate missing values

Description

Uses a fitted model to interpolate missing values from a dataset.

Usage

## S3 method for class 'mdl_df'
interpolate(object, new_data, ...)

## S3 method for class 'mdl_ts'
interpolate(object, new_data, ...)

Arguments

Examples

library(fable)
library(tsibbledata)

# The fastest running times for the olympics are missing for years during 
# world wars as the olympics were not held.
olympic_running

olympic_running %>% 
  model(TSLM(Time ~ trend())) %>% 
  interpolate(olympic_running)

Is the element an aggregation of smaller data

Description

Is the element an aggregation of smaller data

Usage

is_aggregated(x)

Arguments

See Also

aggregate_key

Is the object a dable

Description

Is the object a dable

Usage

is_dable(x)

Arguments

Is the object a fable

Description

Is the object a fable

Usage

is_fable(x)

Arguments

Is the object a mable

Description

Is the object a mable

Usage

is_mable(x)

Arguments

Is the object a model

Description

Is the object a model

Usage

is_model(x)

Arguments

Create a new mable

Description

A mable (model table) data class (mdl_df) is a tibble-like data structure for applying multiple models to a dataset. Each row of the mable refers to a different time series from the data (identified by the key columns). A mable must contain at least one column of time series models (mdl_ts), where the list column itself (lst_mdl) describes how these models are related.

Usage

mable(..., key = NULL, model = NULL)

Arguments

Internal vctrs methods

Description

These methods are the extensions that allow mable objects to work with vctrs.

Usage

## S3 method for class 'mdl_df'
vec_ptype2(x, y, ...)

## S3 method for class 'mdl_df'
vec_cast(x, to, ...)

Return model column variables

Description

mable_vars() returns a character vector of the model variables in the object.

Usage

mable_vars(x)

Arguments

Middle out forecast reconciliation

Description

Usage

middle_out(models, split = 1)

Arguments

Details

Reconciles a hierarchy using the middle out reconciliation method. The response variable of the hierarchy must be aggregated using sums. The forecasted time points must match for all series in the hierarchy.

See Also

reconcile(), aggregate_key() Forecasting: Principles and Practice - Middle-out approach

Minimum trace forecast reconciliation

Description

Reconciles a hierarchy using the minimum trace combination method. The response variable of the hierarchy must be aggregated using sums. The forecasted time points must match for all series in the hierarchy (caution: this is not yet tested for beyond the series length).

Usage

min_trace(
  models,
  method = c("wls_var", "ols", "wls_struct", "mint_cov", "mint_shrink"),
  sparse = NULL
)

Arguments

References

Wickramasuriya, S. L., Athanasopoulos, G., & Hyndman, R. J. (2019). Optimal forecast reconciliation for hierarchical and grouped time series through trace minimization. Journal of the American Statistical Association, 1-45. https://doi.org/10.1080/01621459.2018.1448825

See Also

reconcile(), aggregate_key()

Estimate models

Description

Trains specified model definition(s) to a dataset. This function will estimate the a set of model definitions (passed via ...) to each series within .data (as identified by the key structure). The result will be a mable (a model table), which neatly stores the estimated models in a tabular structure. Rows of the data identify different series within the data, and each model column contains all models from that model definition. Each cell in the mable identifies a single model.

Usage

model(.data, ...)

## S3 method for class 'tbl_ts'
model(.data, ..., .safely = TRUE)

Arguments

Parallel

It is possible to estimate models in parallel using the future package. By specifying a future::plan() before estimating the models, they will be computed according to that plan.

Progress

Progress on model estimation can be obtained by wrapping the code with progressr::with_progress(). Further customisation on how progress is reported can be controlled using the progressr package.

Examples

library(fable)
library(tsibbledata)

# Training an ETS(M,Ad,A) model to Australian beer production
aus_production %>%
  model(ets = ETS(log(Beer) ~ error("M") + trend("Ad") + season("A")))

# Training a seasonal naive and ETS(A,A,A) model to the monthly 
# "Food retailing" turnover for selected Australian states.
library(dplyr)
progressr::with_progress(
aus_retail %>% 
  filter(
    Industry == "Food retailing",
    State %in% c("Victoria", "New South Wales", "Queensland")
  ) %>% 
  model(
    snaive = SNAIVE(Turnover),
    ets = ETS(log(Turnover) ~ error("A") + trend("A") + season("A")),
  )
)

Extract the left hand side of a model

Description

Extract the left hand side of a model

Usage

model_lhs(model)

Arguments

Extract the right hand side of a model

Description

Extract the right hand side of a model

Usage

model_rhs(model)

Arguments

Provide a succinct summary of a model

Description

Similarly to pillar's type_sum and obj_sum, model_sum is used to provide brief model summaries.

Usage

model_sum(x)

Arguments

Create a new class of models

Description

Suitable for extension packages to create new models for fable.

Usage

new_model_class(
  model = "Unknown model",
  train = function(.data, formula, specials, ...)
    abort("This model has not defined a training method."),
  specials = new_specials(),
  check = function(.data) {
 },
  prepare = function(...) {
 },
  ...,
  .env = caller_env(),
  .inherit = model_definition
)

new_model_definition(.class, formula, ..., .env = caller_env(n = 2))

Arguments

Details

This function produces a new R6 model definition. An understanding of R6 is not required, however could be useful to provide more sophisticated model interfaces. All functions have access to self, allowing the functions for training the model and evaluating specials to access the model class itself. This can be useful to obtain elements set in the %TODO

Create evaluation environment for specials

Description

Allows extension packages to make use of the formula parsing of specials.

Usage

new_specials(..., .required_specials = NULL, .xreg_specials = NULL)

Arguments

Create a new modelling transformation

Description

Produces a new transformation for fable modelling functions which will be used to transform, back-transform, and adjust forecasts.

Usage

new_transformation(transformation, inverse)

invert_transformation(x, ...)

Arguments

Details

For more details about transformations, read the vignette: vignette("transformations", package = "fable")

Examples

scaled_logit <- function(x, lower=0, upper=1){
  log((x-lower)/(upper-x))
}
inv_scaled_logit <- function(x, lower=0, upper=1){
  (upper-lower)*exp(x)/(1+exp(x)) + lower
}
my_scaled_logit <- new_transformation(scaled_logit, inv_scaled_logit)

t_vals <- my_scaled_logit(1:10, 0, 100)
t_vals

NULL model

Description

Create a NULL model definition. This model produces NA forecasts and does not require any estimation of the data. It is generally used as a placeholder for models which have encountered an error (see .safely in model()).

Usage

null_model(formula, ...)

is_null_model(x)

Arguments

Identify outliers

Description

Return a table of outlying observations using a fitted model.

Usage

outliers(object, ...)

## S3 method for class 'mdl_df'
outliers(object, ...)

## S3 method for class 'mdl_ts'
outliers(object, ...)

Arguments

Parse the model specification for specials

Description

Using a list of defined special functions, the user's formula specification and data is parsed to extract important modelling components.

Usage

parse_model(model)

Arguments

Parse the RHS of the model formula for transformations

Description

Parse the RHS of the model formula for transformations

Usage

parse_model_lhs(model)

Arguments

Parse the RHS of the model formula for specials

Description

Parse the RHS of the model formula for specials

Usage

parse_model_rhs(model)

Arguments

Distribution accuracy measures

Description

These accuracy measures can be used to evaluate how accurately a forecast distribution predicts a given actual value.

Usage

percentile_score(.dist, .actual, na.rm = TRUE, ...)

quantile_score(
  .dist,
  .actual,
  probs = c(0.05, 0.25, 0.5, 0.75, 0.95),
  na.rm = TRUE,
  ...
)

CRPS(.dist, .actual, n_quantiles = 1000, na.rm = TRUE, ...)

distribution_accuracy_measures

Arguments

Format

An object of class list of length 2.

Quantile/percentile score (pinball loss)

A quantile (or percentile) score evaluates how accurately a set of quantiles (or percentiles) from the distribution match the given actual value. This score uses a pinball loss function, and can be calculated via the average of the score function given below:

The score function s_p(q_p,y) is given by (1-p)(q_p-y) if y < q_p, and p(y-q_p) if y \ge q_p. Where p is the quantile probability, q_p = F^{-1}(p) is the quantile with probability p, and y is the actual value.

The resulting accuracy measure will average this score over all predicted points at all desired quantiles (defined via the probs argument).

The percentile score is uses the same method with probs set to all percentiles probs = seq(0.01, 0.99, 0.01).

Continuous ranked probability score (CRPS)

The continuous ranked probability score (CRPS) is the continuous analogue of the pinball loss quantile score defined above. Its value is twice the integral of the quantile score over all possible quantiles:

CRPS(F,y) = 2 \int_0^1 s_p(q_p,y) dp

It can be computed directly from the distribution via:

CRPS(F,y) = \int_{-\infty}^\infty (F(x) - 1{y\leq x})^2 dx

For some forecast distribution F and actual value y.

Calculating the CRPS accuracy measure is computationally difficult for many distributions, however it can be computed quickly and exactly for Normal and emperical (sample) distributions. For other distributions the CRPS is approximated using the quantile score of many quantiles (using the number of quantiles specified in the n_quantiles argument).

Forecast reconciliation

Description

This function allows you to specify the method used to reconcile forecasts in accordance with its key structure.

Usage

reconcile(.data, ...)

## S3 method for class 'mdl_df'
reconcile(.data, ...)

Arguments

Examples

library(fable)
lung_deaths_agg <- as_tsibble(cbind(mdeaths, fdeaths)) %>%
  aggregate_key(key, value = sum(value))

lung_deaths_agg %>%
  model(lm = TSLM(value ~ trend() + season())) %>%
  reconcile(lm = min_trace(lm)) %>% 
  forecast()

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

distributional

hilo

dplyr

%>%, vars

generics

accuracy, augment, components, equation, forecast, generate, glance, hypothesize, interpolate, refit, tidy

ggplot2

autolayer, autoplot

tsibble

as_tsibble

Refit a mable to a new dataset

Description

Applies a fitted model to a new dataset. For most methods this can be done with or without re-estimation of the parameters.

Usage

## S3 method for class 'mdl_df'
refit(object, new_data, ...)

## S3 method for class 'mdl_ts'
refit(object, new_data, ...)

Arguments

Examples

library(fable)

fit <- as_tsibble(mdeaths) %>% 
  model(ETS(value ~ error("M") + trend("A") + season("A")))
fit %>% report()

fit %>% 
  refit(as_tsibble(fdeaths)) %>% 
  report(reinitialise = TRUE)

Register a feature function

Description

Allows users to find and use features from your package using feature_set(). If the features are being registered from within a package, this feature registration should happen at load time using ⁠[.onLoad()]⁠.

Usage

register_feature(fn, tags)

Arguments

Examples

## Not run: 
tukey_five <- function(x){
  setNames(fivenum(x), c("min", "hinge_lwr", "med", "hinge_upr", "max"))
}

register_feature(tukey_five, tags = c("boxplot", "simple"))


## End(Not run)

Report information about an object

Description

Displays the object in a suitable format for reporting.

Usage

report(object, ...)

Arguments

Extract residuals values from models

Description

Extracts the residuals from each of the models in a mable. A tsibble will be returned containing these residuals.

Usage

## S3 method for class 'mdl_df'
residuals(object, ...)

## S3 method for class 'mdl_ts'
residuals(object, type = "innovation", ...)

Arguments

Extract the response variable from a model

Description

Returns a tsibble containing only the response variable used in the fitting of a model.

Usage

response(object, ...)

Arguments

Return response variables

Description

response_vars() returns a character vector of the response variables in the object.

Usage

response_vars(x)

Arguments

A set of future scenarios for forecasting

Description

A set of future scenarios for forecasting

Usage

scenarios(..., names_to = ".scenario")

Arguments

Forecast skill score measure

Description

This function converts other error metrics such as MSE into a skill score. The reference or benchmark forecasting method is the Naive method for non-seasonal data, and the seasonal naive method for seasonal data. When used within accuracy.fbl_ts, it is important that the data contains both the training and test data, as the training data is used to compute the benchmark forecasts.

Usage

skill_score(measure)

Arguments

Examples

skill_score(MSE)


library(fable)
library(tsibble)

lung_deaths <- as_tsibble(cbind(mdeaths, fdeaths))
lung_deaths %>% 
  dplyr::filter(index < yearmonth("1979 Jan")) %>%
  model(
    ets = ETS(value ~ error("M") + trend("A") + season("A")),
    lm = TSLM(value ~ trend() + season())
  ) %>%
  forecast(h = "1 year") %>%
  accuracy(lung_deaths, measures = list(skill = skill_score(MSE)))

Helper special for producing a model matrix of exogenous regressors

Description

Helper special for producing a model matrix of exogenous regressors

Usage

special_xreg(...)

Arguments

Details

Currently the fable_xreg_matrix helper supports a single argument named default_intercept. If this argument is TRUE (passed via ... above), then the intercept will be returned in the matrix if not specified (much like the behaviour of lm()). If FALSE, then the intercept will only be included if explicitly requested via 1 in the formula.

Extend a fitted model with new data

Description

Extend the length of data used to fit a model and update the parameters to suit this new data.

Usage

stream(object, ...)

## S3 method for class 'mdl_df'
stream(object, new_data, ...)

Arguments

Extract model coefficients from a mable

Description

This function will obtain the coefficients (and associated statistics) for each model in the mable.

Usage

## S3 method for class 'mdl_df'
tidy(x, ...)

## S3 method for class 'mdl_df'
coef(object, ...)

## S3 method for class 'mdl_ts'
tidy(x, ...)

## S3 method for class 'mdl_ts'
coef(object, ...)

Arguments

Examples

library(fable)
library(tsibbledata)

olympic_running %>%
  model(lm = TSLM(log(Time) ~ trend())) %>% 
  tidy()

Top down forecast reconciliation

Description

Usage

top_down(
  models,
  method = c("forecast_proportions", "average_proportions", "proportion_averages")
)

Arguments

Details

Reconciles a hierarchy using the top down reconciliation method. The response variable of the hierarchy must be aggregated using sums. The forecasted time points must match for all series in the hierarchy.

See Also

reconcile(), aggregate_key()

Recursively traverse an object

Description

Recursively traverse an object

Usage

traverse(
  x,
  .f = list,
  .g = identity,
  .h = identity,
  base = function(.x) is_syntactic_literal(.x) || is_symbol(.x)
)

Arguments

Unpack a hilo column

Description

This function is superceded. It is recommended that you use the functionality from the distributional package to extract elements from a ⁠<hilo>⁠ object. For example, you can access the lower bound with ⁠<hilo>$lower⁠.

Allows a hilo column to be unpacked into its component columns: "lower", "upper", and "level".

Usage

unpack_hilo(data, cols, names_sep = "_", names_repair = "check_unique")

Arguments

See Also

tidyr::unpack()

Validate the user provided model

Description

Appropriately format the user's model for evaluation. Typically ran as one of the first steps in a model function.

Usage

validate_formula(model, data = NULL)

Arguments

Interval estimate accuracy measures

Description

Interval estimate accuracy measures

Usage

winkler_score(.dist, .actual, level = 95, na.rm = TRUE, ...)

pinball_loss(.dist, .actual, level = 95, na.rm = TRUE, ...)

scaled_pinball_loss(
  .dist,
  .actual,
  .train,
  level = 95,
  na.rm = TRUE,
  demean = FALSE,
  .period,
  d = .period == 1,
  D = .period > 1,
  ...
)

interval_accuracy_measures

Arguments

Format

An object of class list of length 3.