neural_prophet: General Interface for Neural Prophet Time Series Models
In AlbertoAlmuinha/neuralprophet: 'Neural Prophet' Algorithm

Description Usage Arguments Details Engine Details See Also Examples

neural_prophet() is a way to generate a specification of a NEURAL PROPHET model before fitting and allows the model to be created using different packages. Currently the only package is neuralprophet from Python through reticulate.

neural_prophet(
  mode = "regression",
  growth = NULL,
  user_changepoints = NULL,
  changepoint_num = NULL,
  changepoint_range = NULL,
  seasonality_yearly = NULL,
  seasonality_weekly = NULL,
  seasonality_daily = NULL,
  season = NULL,
  trend_reg = NULL,
  trend_reg_threshold = NULL,
  seasonality_mode = NULL,
  num_hidden_layers = NULL,
  d_hidden = NULL,
  ar_sparsity = NULL,
  learn_rate = NULL,
  epochs = NULL,
  batch_size = NULL,
  loss_func = NULL,
  train_speed = NULL,
  normalize_y = NULL,
  impute_missing = NULL,
  n_forecasts = NULL,
  n_lags = NULL,
  freq = NULL
)

`mode`	A single character string for the type of model. The only possible value for this model is "regression".
`growth`	String 'linear' or 'logistic' to specify a linear or logistic trend.
`user_changepoints`	If a list of changepoints is supplied, n_changepoints and changepoints_range are ignored. This list is instead used to set the dates at which the trend rate is allowed to change.
`changepoint_num`	Number of potential changepoints to include for modeling trend.
`changepoint_range`	Adjusts the flexibility of the trend component by limiting to a percentage of data before the end of the time series. 0.80 means that a changepoint cannot exist after the first 80% of the data.
`seasonality_yearly`	One of "auto", TRUE or FALSE. Toggles on/off a seasonal component that models year-over-year seasonality.
`seasonality_weekly`	One of "auto", TRUE or FALSE. Toggles on/off a seasonal component that models week-over-week seasonality.
`seasonality_daily`	One of "auto", TRUE or FALSE. Toggles on/off a seasonal componet that models day-over-day seasonality.
`season`	'additive' (default) or 'multiplicative'.
`trend_reg`	the trend rate changes can be regularized by setting trend_reg to a value greater zero. This is a useful feature that can be used to automatically detect relevant changepoints.
`trend_reg_threshold`	Threshold for the trend regularization
`seasonality_mode`	The default seasonality_mode is additive. This means that no heteroscedasticity is expected in the series in terms of the seasonality. However, if the series contains clear variance, where the seasonal fluctuations become larger proportional to the trend, the seasonality_mode can be set to multiplicative.
`num_hidden_layers`	num_hidden_layers defines the number of hidden layers of the FFNNs used in the overall model. This includes the AR-Net and the FFNN of the lagged regressors. The default is 0, meaning that the FFNNs will have only one final layer of size n_forecasts. Adding more layers results in increased complexity and also increased computational time, consequently. However, the added number of hidden layers can help build more complex relationships especially useful for the lagged regressors. To tradeoff between the computational complexity and the improved accuracy the num_hidden_layers is recommended to be set in between 1-2. Nevertheless, in most cases a good enough performance can be achieved by having no hidden layers at all.
`d_hidden`	d_hidden is the number of units in the hidden layers. This is only considered if num_hidden_layers is specified, otherwise ignored. The default value for d_hidden if not specified is (n_lags + n_forecasts). If tuned manually, the recommended practice is to set a value in between n_lags and n_forecasts for d_hidden. It is also important to note that with the current implementation, NeuralProphet sets the same d_hidden for the all the hidden layers.
`ar_sparsity`	NeuralProphet also contains a number of regularization parameters to control the model coefficients and introduce sparsity into the model. This also helps avoid overfitting of the model to the training data.For ar_sparsity values in the range 0-1 are expected with 0 inducing complete sparsity and 1 imposing no regularization at all. ar_sparsity along with n_lags can be used for data exploration and feature selection. You can use a larger number of lags thanks to the scalability of AR-Net and use the scarcity to identify important influence of past time steps on the prediction accuracy.
`learn_rate`	NeuralProphet is fit with stochastic gradient descent - more precisely, with an AdamW optimizer and a One-Cycle policy. If the parameter learning_rate is not specified, a learning rate range test is conducted to determine the optimal learning rate. A number for the rate at which the algorithm adapts from iteration-to-iteration.
`epochs`	The epochs and the loss_func are two other parameters that directly affect the model training process. If not defined, both are automatically set based on the dataset size. They are set in a manner that controls the total number training steps to be around 1000 to 4000.
`batch_size`	number of samples that will be propagated through the network
`loss_func`	The default loss function is the 'Huber' loss, which is considered to be robust to outliers. However, you are free to choose the standard MSE or any other PyTorch torch.nn.modules.loss loss function.
`train_speed`	Number indicating the speed at which training of the network occurs.
`normalize_y`	is about scaling the time series before modelling. By default, NeuralProphet performs a (soft) min-max normalization of the time series. Normalization can help the model training process if the series values fluctuate heavily. However, if the series does not such scaling, users can turn this off or select another normalization.
`impute_missing`	is about imputing the missing values in a given series. S imilar to Prophet, NeuralProphet too can work with missing values when it is in the regression mode without the AR-Net. However, when the autocorrelation needs to be captured, it is necessary for the missing values to be imputed, since then the modelling becomes an ordered problem. Letting this parameter at its default can get the job done perfectly in most cases.
`n_forecasts`	is the size of the forecast horizon. The default value of 1 means that the model forecasts one step into the future.
`n_lags`	defines whether the AR-Net is enabled (if n_lags > 0) or not. The value for n_lags is usually recommended to be greater than n_forecasts, if possible since it is preferable for the FFNNs to encounter at least n_forecasts length of the past in order to predict n_forecasts into the future. Thus, n_lags determine how far into the past the auto-regressive dependencies should be considered. This could be a value chosen based on either domain expertise or an empirical analysis.
`freq`	A pandas timeseries frequency such as "5min" for 5-minutes or "D" for daily. Refer to Pandas Offset Aliases

The data given to the function are not saved and are only used to determine the mode of the model. For neural_prophet(), the mode will always be "regression".

The model can be created using the fit() function using the following engines:

"prophet" (default) - Connects to neuralprophet.NeuralProphet() (Python)

Main Arguments

The main arguments (tuning parameters) for the NEURAL PROPHET model are:

growth: String 'linear' or 'logistic' to specify a linear or logistic trend.
changepoint_num: Number of potential changepoints to include for modeling trend.
changepoint_range: Range changepoints that adjusts how close to the end the last changepoint can be located.
season: 'additive' (default) or 'multiplicative'.
ar_sparsity: For ar_sparsity values in the range 0-1 are expected with 0 inducing complete sparsity and 1 imposing no regularization at all
num_hidden_layers: num_hidden_layers defines the number of hidden layers of the FFNNs used in the overall model.
d_hidden: d_hidden is the number of units in the hidden layers.
trend_reg: the trend rate changes can be regularized by setting trend_reg to a value greater zero. This is a useful feature that can be used to automatically detect relevant changepoints.

These arguments are converted to their specific names at the time that the model is fit.

Other options and argument can be set using set_engine() (See Engine Details below).

If parameters need to be modified, update() can be used in lieu of recreating the object from scratch.

The standardized parameter names in neuralprophet can be mapped to their original names in each engine. Other options can be set using set_engine().

prophet

Limitations:

prophet::add_seasonality() is not currently implemented. It's used to specify non-standard seasonalities using fourier series. An alternative is to use step_fourier() and supply custom seasonalities as Extra Regressors. Date and Date-Time Variable

It's a requirement to have a date or date-time variable as a predictor. The fit() interface accepts date and date-time features and handles them internally.

fit(y ~ date)

Univariate (No Extra Regressors):

For univariate analysis, you must include a date or date-time feature. Simply use:

Formula Interface (recommended): fit(y ~ date) will ignore xreg's.

Events

To include events correctly, the following conditions must be met:

Event variable names must contain events in their name. For example: "events_one", "events_two".
Pass a list called add_events through set_engine(). This list will define the characteristics of our events. It should contain the elements contained in the add_events method in Python.
Include events in the formula as external regressors

Example:

neural_prophet(freq = "D") %>% set_engine(add_events = list(events = c("events_1", "events_2"), regularization = 0.5)) %>% fit(y ~ date + events_1 + events_2, data = df)

Future Regressor

To include Future Regressors correctly, the following conditions must be met:

Future Regressors variable names must contain future_ in their name. For example: "future_one", "future_two".
Any columns that aren't labeled "event_" or "lagged_" are added as Future Regressors (except date one).
Pass a list called add_future_regressor through set_engine(). This list will define the characteristics of our future_regressors It should contain the elements contained in the add_future_regressor method in Python.
Include future_regressors in the formula as external regressors

Example:

neural_prophet(freq = "D") %>% set_engine(add_future_regressor = list(name = c("future_1", "future_2"), regularization = 0.5)) %>% fit(y ~ date + future_1 + future_2, data = df)

Lagged Regressor

To include Lagged Regressors correctly, the following conditions must be met:

Lagged Regressors variable names must contain lagged in their names. For example: "lagged_one", "lagged_two".
Pass a list called add_lagged_regressor through set_engine(). This list will define the characteristics of our lagged_regressor It should contain the elements contained in the add_lagged_regressor method in Python.
Include lagged regressors in the formula as external regressors

Example:

neural_prophet(freq = "D") %>% set_engine(add_lagged_regressor = list(name = c("lagged_1", "lagged_2"), regularization = 0.5)) %>% fit(y ~ date + lagged_1 + lagged_2, data = df)

fit.model_spec(), set_engine()

library(dplyr)
library(lubridate)
library(parsnip)
library(rsample)
library(timetk)

# Data
md10 <- m4_daily %>% filter(id == "D10")
md10

# Split Data 80/20
splits <- initial_time_split(md10, prop = 0.8)

# ---- NEURAL PROPHET ----

# Model Spec
model_spec <- neural_prophet(
    freq = "D"
) %>%
    set_engine("prophet")

# Fit Spec
model_fit <- model_spec %>%
    fit(log(value) ~ date,
        data = training(splits))
model_fit