Core Module Documentation

class neuralprophet.forecaster.NeuralProphet(growth='linear', changepoints=None, n_changepoints=10, changepoints_range=0.9, trend_reg=0, trend_reg_threshold=False, yearly_seasonality='auto', weekly_seasonality='auto', daily_seasonality='auto', seasonality_mode='additive', seasonality_reg=0, n_forecasts=1, n_lags=0, num_hidden_layers=0, d_hidden=None, ar_sparsity=None, learning_rate=None, epochs=None, batch_size=None, loss_func='Huber', optimizer='AdamW', train_speed=None, normalize='auto', impute_missing=True, collect_metrics=True)

NeuralProphet forecaster.

A simple yet powerful forecaster that models: Trend, seasonality, events, holidays, auto-regression, lagged covariates, and future-known regressors. Can be regualrized and configured to model nonlinear relationships.

add_country_holidays(country_name, lower_window=0, upper_window=0, regularization=None, mode='additive')

Add a country into the NeuralProphet object to include country specific holidays and create the corresponding configs such as lower, upper windows and the regularization parameters :param country_name: name of the country :type country_name: string :param lower_window: the lower window for all the country holidays :type lower_window: int :param upper_window: the upper window for all the country holidays :type upper_window: int :param regularization: optional scale for regularization strength :type regularization: float :param mode: ‘additive’ (default) or ‘multiplicative’. :type mode: str

Returns

NeuralProphet object

add_events(events, lower_window=0, upper_window=0, regularization=None, mode='additive')

Add user specified events and their corresponding lower, upper windows and the regularization parameters into the NeuralProphet object

Parameters
  • events (str, list) – name or list of names of user specified events

  • lower_window (int) – the lower window for the events in the list of events

  • upper_window (int) – the upper window for the events in the list of events

  • regularization (float) – optional scale for regularization strength

  • mode (str) – ‘additive’ (default) or ‘multiplicative’.

Returns

NeuralProphet object

add_future_regressor(name, regularization=None, normalize='auto', mode='additive')

Add a regressor as lagged covariate with order 1 (scalar) or as known in advance (also scalar).

The dataframe passed to fit and predict will have a column with the specified name to be used as a regressor. When normalize=True, the regressor will be normalized unless it is binary.

Parameters
  • name (string) – name of the regressor.

  • regularization (float) – optional scale for regularization strength

  • normalize (bool) – optional, specify whether this regressor will be normalized prior to fitting. if ‘auto’, binary regressors will not be normalized.

  • mode (str) – ‘additive’ (default) or ‘multiplicative’.

Returns

NeuralProphet object

add_lagged_regressor(names, regularization=None, normalize='auto', only_last_value=False)

Add a covariate or list of covariate time series as additional lagged regressors to be used for fitting and predicting. The dataframe passed to fit and predict will have the column with the specified name to be used as lagged regressor. When normalize=True, the covariate will be normalized unless it is binary. :param names: name of the regressor/list of regressors. :type names: string or list :param regularization: optional scale for regularization strength :type regularization: float :param normalize: optional, specify whether this regressor will be

normalized prior to fitting. if ‘auto’, binary regressors will not be normalized.

Parameters

only_last_value (bool) – False (default) use same number of lags as auto-regression True: only use last known value as input

Returns

NeuralProphet object

add_seasonality(name, period, fourier_order)

Add a seasonal component with specified period, number of Fourier components, and regularization.

Increasing the number of Fourier components allows the seasonality to change more quickly (at risk of overfitting). Note: regularization and mode (additive/multiplicative) are set in the main init.

Parameters
  • name – string name of the seasonality component.

  • period – float number of days in one period.

  • fourier_order – int number of Fourier components to use.

Returns

The NeuralProphet object.

create_df_with_events(df, events_df)

Create a concatenated dataframe with the time series data along with the events data expanded.

Parameters
  • df (pd.DataFrame) – containing column ‘ds’ and ‘y’

  • events_df (pd.DataFrame) – containing column ‘ds’ and ‘event’

Returns

pd.DataFrame with columns ‘y’, ‘ds’ and other user specified events

crossvalidation_split_df(df, freq, k=5, fold_pct=0.1, fold_overlap_pct=0.5)

Splits timeseries data in k folds for crossvalidation.

Parameters
  • df (pd.DataFrame) – data

  • freq (str) – Data step sizes. Frequency of data recording, Any valid frequency for pd.date_range, such as ‘5min’, ‘D’ or ‘MS’

  • k – number of CV folds

  • fold_pct – percentage of overall samples to be in each fold

  • fold_overlap_pct – percentage of overlap between the validation folds.

Returns

df_train (pd.DataFrame): training data df_val (pd.DataFrame): validation data

Return type

list of k tuples [(df_train, df_val), …] where

double_crossvalidation_split_df(df, freq, k=5, valid_pct=0.1, test_pct=0.1)

Splits timeseries data in two sets of k folds for crossvalidation on training and testing data.

Parameters
  • df (pd.DataFrame) – data

  • freq (str) – Data step sizes. Frequency of data recording, Any valid frequency for pd.date_range, such as ‘5min’, ‘D’ or ‘MS’

  • k (int) – number of CV folds

  • valid_pct (float) – percentage of overall samples to be in validation

  • test_pct (float) – percentage of overall samples to be in test

Returns

tuple of folds_val, folds_test, where each are same as crossvalidation_split_df returns

fit(df, freq, validation_df=None, epochs=None, local_modeling=False, progress_bar=True, plot_live_loss=False, progress_print=True, minimal=False)

Train, and potentially evaluate model.

Parameters
  • df (pd.DataFrame) – containing column ‘ds’, ‘y’ with all data

  • freq (str) – Data step sizes. Frequency of data recording, Any valid frequency for pd.date_range, such as ‘5min’, ‘D’ or ‘MS’

  • epochs (int) – number of epochs to train. default: if not specified, uses self.epochs

  • validation_df (pd.DataFrame) – if provided, model with performance will be evaluated after each training epoch over this data.

  • local_modeling (bool) – when set to true each episode from list of dataframes will be considered locally (i.e. seasonality, data_params, normalization) - not fully implemented yet. (only related to Global Modeling)

  • progress_bar (bool) – display updating progress bar (tqdm)

  • plot_live_loss (bool) – plot live training loss, requires [live] install or livelossplot package installed.

  • progress_print (bool) – if no progress_bar, whether to print out progress

  • minimal (bool) – whether to train without any printouts or metrics collection

Returns

metrics with training and potentially evaluation metrics

handle_missing_data(df, freq, predicting=False)

Checks, auto-imputes and normalizes new data

Parameters
  • df (pd.DataFrame or list of pd.Dataframes) – raw data with columns ‘ds’ and ‘y’

  • freq (str) – data frequency

  • predicting (bool) – when no lags, allow NA values in ‘y’ of forecast series or ‘y’ to miss completely

Returns

pre-processed df

highlight_nth_step_ahead_of_each_forecast(step_number=None)

Set which forecast step to focus on for metrics evaluation and plotting.

Parameters

step_number (int) – i-th step ahead forecast to use for statistics and plotting. default: None.

plot(fcst, ax=None, xlabel='ds', ylabel='y', figsize=(10, 6))

Plot the NeuralProphet forecast, including history. :param fcst: output of self.predict. :type fcst: pd.DataFrame :param ax: Optional, matplotlib axes on which to plot. :type ax: matplotlib axes :param xlabel: label name on X-axis :type xlabel: string :param ylabel: label name on Y-axis :type ylabel: string :param figsize: width, height in inches. default: (10, 6) :type figsize: tuple

Returns

A matplotlib figure.

plot_components(fcst, figsize=None, residuals=False)

Plot the NeuralProphet forecast components.

Parameters
  • fcst (pd.DataFrame) – output of self.predict

  • figsize (tuple) – width, height in inches. None (default): automatic (10, 3 * npanel)

Returns

A matplotlib figure.

plot_last_forecast(fcst, ax=None, xlabel='ds', ylabel='y', figsize=(10, 6), include_previous_forecasts=0, plot_history_data=None)

Plot the NeuralProphet forecast, including history.

Parameters
  • fcst (pd.DataFrame) – output of self.predict.

  • ax (matplotlib axes) – Optional, matplotlib axes on which to plot.

  • xlabel (string) – label name on X-axis

  • ylabel (string) – label name on Y-axis

  • figsize (tuple) – width, height in inches. default: (10, 6)

  • include_previous_forecasts (int) – number of previous forecasts to include in plot

  • plot_history_data

Returns

A matplotlib figure.

plot_parameters(weekly_start=0, yearly_start=0, figsize=None)

Plot the NeuralProphet forecast components.

Parameters
  • weekly_start (int) – specifying the start day of the weekly seasonality plot. 0 (default) starts the week on Sunday. 1 shifts by 1 day to Monday, and so on.

  • yearly_start (int) – specifying the start day of the yearly seasonality plot. 0 (default) starts the year on Jan 1. 1 shifts by 1 day to Jan 2, and so on.

  • figsize (tuple) – width, height in inches. None (default): automatic (10, 3 * npanel)

Returns

A matplotlib figure.

predict(df, decompose=True, raw=False)

Runs the model to make predictions.

Expects all data needed to be present in dataframe. If you are predicting into the unknown future and need to add future regressors or events, please prepare data with make_future_dataframe.

Parameters
  • df (pandas DataFrame or list of Dataframes) – Dataframe with columns ‘ds’ datestamps, ‘y’ time series values and other external variables

  • decompose (bool) – Whether to add individual components of forecast to the dataframe

  • raw (bool) – Whether return the raw forecasts sorted by forecast start date False (default): returns forecasts sorted by target (highlighting forecast age)

Returns

df_raw (pandas DataFrame): columns ‘ds’, ‘y’, and [‘step<i>’]

where step<i> refers to the i-step-ahead prediction made at this row’s datetime. e.g. step3 is the prediction for 3 steps into the future, predicted using information up to (excluding) this datetime.

else:
df_forecast (pandas DataFrame or list of Dataframes): columns ‘ds’, ‘y’, ‘trend’ and [‘yhat<i>’]

where yhat<i> refers to the i-step-ahead prediction for this row’s datetime. e.g. yhat3 is the prediction for this datetime, predicted 3 steps ago, “3 steps old”.

Return type

if raw

predict_seasonal_components(df)

Predict seasonality components

Parameters

df (pd.DataFrame) – containing column ‘ds’, prediction dates

Returns

pd.Dataframe or list of pd.Dataframe with seasonal components. with columns of name <seasonality component name>

predict_trend(df)

Predict only trend component of the model.

Parameters

df (pd.DataFrame) – containing column ‘ds’, prediction dates

Returns

pd.Dataframe or list of pd.Dataframe with trend on prediction dates.

set_true_ar_for_eval(true_ar_weights)

configures model to evaluate closeness of AR weights to true weights.

Parameters

true_ar_weights (np.array) – True AR-parameters, if known.

split_df(df, freq, valid_p=0.2, local_modeling=False)

Splits timeseries df into train and validation sets.

Prevents overbleed of targets. Overbleed of inputs can be configured. Also performs basic data checks and fills in missing data.

Parameters
  • df (pd.DataFrame) – data

  • freq (str) – Data step sizes. Frequency of data recording, Any valid frequency for pd.date_range, such as ‘5min’, ‘D’ or ‘MS’

  • valid_p (float) – fraction of data to use for holdout validation set Targets will still never be shared.

Returns

training data df_val (pd.DataFrame): validation data

Return type

df_train (pd.DataFrame)

test(df)

Evaluate model on holdout data.

Parameters

df (pd.DataFrame) – containing column ‘ds’, ‘y’ with holdout data

Returns

df with evaluation metrics