Package {fable.prophet}

fable.prophet: Prophet Modelling Interface for 'fable'

Description

Allows prophet models from the 'prophet' package to be used in a tidy workflow with the modelling interface of 'fabletools'. This extends 'prophet' to provide enhanced model specification and management, performance evaluation methods, and model combination tools.

Author(s)

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

Authors:

• Mitchell O'Hara-Wild mail@mitchelloharawild.com

Other contributors:

• Sean Taylor (Prophet library, https://facebook.github.io/prophet/) [contributor]

• Ben Letham (Prophet library, https://facebook.github.io/prophet/) [contributor]

See Also

Useful links:

• https://pkg.mitchelloharawild.com/fable.prophet/

• https://github.com/mitchelloharawild/fable.prophet

• Report bugs at https://github.com/mitchelloharawild/fable.prophet/issues

Extract meaningful components

Description

A prophet model consists of terms which are additively or multiplicatively included in the model. Multiplicative terms are scaled proportionally to the estimated trend, while additive terms are not.

Usage

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

Arguments

Details

Holiday effects (holidays) and exogenous regressor effects (extra_regressors_additive and extra_regressors_multiplicative) are included when they are part of the model. Like the seasonal terms, these are contained within the model's additive_terms or multiplicative_terms.

Extracting a prophet model's components using this function allows you to visualise the components in a similar way to prophet::prophet_plot_components().

Value

A fabletools::dable() containing estimated states.

Examples

if (requireNamespace("tsibbledata")) {
library(tsibble)
beer_components <- tsibbledata::aus_production %>%
  model(
    prophet = prophet(Beer ~ season("year", 4, type = "multiplicative"))
  ) %>%
  components()

beer_components

autoplot(beer_components)

library(ggplot2)
library(lubridate)
beer_components %>%
  ggplot(aes(x = quarter(Quarter), y = year, group = year(Quarter))) +
  geom_line()
}

Extract fitted values

Description

Extracts the fitted values from an estimated Prophet model.

Usage

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

Arguments

Value

A vector of fitted values.

Produce forecasts from the prophet model

Description

If additional future information is required (such as exogenous variables or carrying capacities) by the model, then they should be included as variables of the new_data argument.

Usage

## S3 method for class 'fbl_prophet'
forecast(object, new_data, specials = NULL, times = 1000, ...)

Arguments

Value

A list of forecasts.

See Also

prophet::predict.prophet()

Examples

if (requireNamespace("tsibbledata")) {
library(tsibble)
tsibbledata::aus_production %>%
  model(
    prophet = prophet(Beer ~ season("year", 4, type = "multiplicative"))
  ) %>%
  forecast()
}

Generate responses from a prophet model

Description

Simulates future (or in-sample) sample paths from a prophet model. Each path consists of a simulated trend (including future trend changes), the model's seasonal, holiday and regressor effects, and observation noise.

Usage

## S3 method for class 'fbl_prophet'
generate(x, new_data = NULL, bootstrap = FALSE, specials = NULL, ...)

Arguments

Details

By default the observation noise is normally distributed with the estimated standard deviation of the model (sigma_obs). If bootstrap = TRUE, the noise is instead resampled from the model's (mean-centred) residuals. When used via fabletools::generate(), the bootstrap argument of that function takes precedence and times sets the number of paths.

As with forecast.fbl_prophet(), any variables required by the model (regressors, carrying capacities and conditions) must be included in new_data. Estimated models using MCMC simulate each path using one (randomly selected) posterior draw of the parameters.

Value

A tsibble with the index and key of new_data, and the simulated values in .sim.

Examples

library(tsibble)
fit <- as_tsibble(USAccDeaths) %>%
  model(prophet(value ~ season("year", 4)))

generate(fit, h = 12, times = 5)

Glance a prophet model

Description

A glance of a prophet provides the residual's standard deviation (sigma), and a tibble containing the selected changepoints with their trend adjustments.

Usage

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

Arguments

Value

A one row tibble summarising the model's fit.

Examples

if (requireNamespace("tsibbledata")) {
library(tsibble)
library(dplyr)
fit <- tsibbledata::aus_production %>%
  model(
    prophet = prophet(Beer ~ season("year", 4, type = "multiplicative"))
  )

glance(fit)
}

Prophet procedure modelling

Description

Prepares a prophet model specification for use within the fable package.

Usage

prophet(formula, ...)

Arguments

Details

The prophet modelling interface uses a formula based model specification (y ~ x), where the left of the formula specifies the response variable, and the right specifies the model's predictive terms. Like any model in the fable framework, it is possible to specify transformations on the response.

A prophet model supports piecewise linear or exponential growth (trend), additive or multiplicative seasonality, holiday effects and exogenous regressors. These can be specified using the 'specials' functions detailed below. The introduction vignette provides more details on how to model data using this interface to prophet: vignette("intro", package="fable.prophet").

Estimation

By default the model is estimated by maximum a posteriori (MAP) optimisation. Two arguments of prophet::prophet() can be given in ... of prophet():

• mcmc.samples: If greater than 0, the model is estimated using this many MCMC (Hamiltonian Monte Carlo) iterations, which is slower. Parameters are then summarised by their posterior means in tidy() and glance(), and forecast sample paths include parameter uncertainty.

• backend: The Stan backend, either "rstan" or "cmdstanr" (which requires the cmdstanr package). If NULL (the default), the backend is chosen by prophet::prophet(), using "rstan" unless the environment variable R_STAN_BACKEND is set to "CMDSTANR".

Specials

growth

The growth special is used to specify the trend parameters.

growth(type = c("linear", "logistic", "flat"), capacity = NULL, floor = NULL,
       changepoints = NULL, n_changepoints = 25, changepoint_range = 0.8,
       changepoint_prior_scale = 0.05)

season

The season special is used to specify a seasonal component. This special can be used multiple times for different seasonalities.

Warning: The inputs controlling the seasonal period is specified is different than prophet::prophet(). Numeric inputs are treated as the number of observations in each seasonal period, not the number of days.

season(period = NULL, order = NULL, prior_scale = 10,
       type = c("additive", "multiplicative"), name = NULL, condition = NULL)

holiday

The holiday special is used to specify a tsibble containing holidays for the model, and/or a country whose built-in holidays are included.

holiday(holidays = NULL, prior_scale = 10L, country = NULL)

xreg

The xreg special is used to include exogenous regressors in the model. This special can be used multiple times for different regressors with different arguments. Exogenous regressors can also be used in the formula without explicitly using the xreg() special, which will then use the default arguments.

xreg(..., prior_scale = NULL, standardize = "auto", type = NULL)

Non-daily data

A model without any terms (prophet(y), a bare response with no right hand side) enables prophet's yearly, weekly and daily seasonalities, as in prophet::prophet(). Unlike prophet's default ("auto"), these are switched on regardless of the data's frequency or length, so for monthly or quarterly data (or any data coarser than daily) the weekly and daily seasonal terms are not meaningful and prophet(y) is not recommended. Instead, specify the seasonality explicitly with season(). Any formula (such as prophet(y ~ season(...))) uses only the seasonalities that you specify, with no automatic seasonalities. For example, use prophet(y ~ season(period = "year", order = 4)) for quarterly data, or order = 6 for monthly data. A season() period given as a string is converted using the data's interval, and a number is the count of observations per period. A Fourier order is required for periods other than a year, week or day.

Performance and memory

Fitting prophet models is relatively slow, and each forecast stores times simulated sample paths (see forecast.fbl_prophet()). When modelling many series, consider the following:

• Reduce times in forecast() (for example times = 100), or use times = 0 for point forecasts only. This reduces time and the size of the forecast object.

• Fitted models drop the raw Stan output, but keep the data used to fit the model, so very large mables can be made smaller by forecasting then discarding the models.

• Models are independent, so series can be fit and forecast in parallel using the future package, for example with future::plan(future::multisession).

• MCMC estimation (mcmc.samples) is much slower than the default optimisation.

Model evaluation

Prophet's cross_validation() and performance_metrics() are not needed for this interface. Use tsibble::stretch_tsibble() to create cross-validation folds, fit models on them and fabletools::accuracy() to evaluate the forecasts.

See Also

• prophet::prophet()

• Prophet homepage

• Prophet R package

• Prophet Python package

Examples

library(tsibble)
as_tsibble(USAccDeaths) %>%
  model(
    prophet = prophet(value ~ season("year", 4, type = "multiplicative"))
  )

Refit a prophet model

Description

Applies a prophet model to a new dataset. By default (reestimate = FALSE) the estimated parameters (including the trend changepoints and the scaling of the data) are kept, and only the fitted values, residuals and components are recomputed for new_data. If reestimate = TRUE, the model is instead estimated again on new_data, using the same specification and estimation arguments (such as mcmc.samples, backend and any others given to prophet()) as the original model.

Usage

## S3 method for class 'fbl_prophet'
refit(object, new_data, specials = NULL, reestimate = FALSE, ...)

Arguments

Details

Prophet does not support updating a fitted model with new observations, so re-estimating is a fresh fit (the previous parameters are not used to initialise it), and no stream() method is defined.

With reestimate = FALSE, the data should span the time period that the model is to be evaluated over, and any variables required by the model (regressors, carrying capacities and conditions) must be in new_data.

Value

A refitted model.

Examples

library(tsibble)
fit <- as_tsibble(USAccDeaths) %>%
  dplyr::filter(index < yearmonth("1977 Jan")) %>%
  model(prophet(value ~ season("year", 4)))

# Evaluate the estimated model on the full series
refit(fit, as_tsibble(USAccDeaths))

# Estimate the model again on the full series
refit(fit, as_tsibble(USAccDeaths), reestimate = TRUE)

Extract model residuals

Description

Extracts the residuals from an estimated Prophet model.

Usage

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

Arguments

Value

A vector of residuals.

Extract estimated coefficients from a prophet model

Description

Extract estimated coefficients from a prophet model

Usage

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

Arguments

Details

The estimate of the growth (base_growth, trend_offset), seasonal and holiday terms are the model's parameters on prophet's internal (scaled) scale. For extra regressors, the estimate is instead the coefficient on the scale of the original data: additive regressors are reported in units of the response per unit of the regressor, and multiplicative regressors as the proportional change in the trend per unit of the regressor. This is the same quantity described by prophet::regressor_coefficients() (whose returned coef, in prophet 1.1.7, is not yet rescaled).

Value

A tibble containing the model's estimated parameters.

Examples

if (requireNamespace("tsibbledata")) {
library(tsibble)
library(dplyr)
fit <- tsibbledata::aus_production %>%
  model(
    prophet = prophet(Beer ~ season("year", 4, type = "multiplicative"))
  )

tidy(fit) # coef(fit) or coefficients(fit) can also be used
}