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