ourownstory/neural_prophet

NeuralProphet: A simple forecasting package

Please note that the project is still in beta phase. Please report any issues you encounter or suggestions you have. We will do our best to address them quickly. Contributions are very welcome!

NeuralProphet: human-centered forecasting

NeuralProphet is an easy to learn framework for interpretable time series forecasting. NeuralProphet is built on PyTorch and combines Neural Networks and traditional time-series algorithms, inspired by Facebook Prophet and AR-Net.

• With a few lines of code, you can define, customize, visualize, and evaluate your own forecasting models.
• It is designed for iterative human-in-the-loop model building. That means that you can build a first model quickly, interpret the results, improve, repeat. Due to the focus on interpretability and customization-ability, NeuralProphet may not be the most accurate model out-of-the-box; so, don't hesitate to adjust and iterate until you like your results.
• NeuralProphet is best suited for time series data that is of higher-frequency (sub-daily) and longer duration (at least two full periods/years).

Documentation

The documentation page may not be entirely up to date. Docstrings should be reliable, please refer to those when in doubt. We are working on an improved documentation. We appreciate any help to improve and update the docs.

For a visual introduction to NeuralProphet, view this presentation.

Contribute

We compiled a Contributing to NeuralProphet page with practical instructions and further resources to help you become part of the family.

Community

Discussion and Help

If you have any questions or suggestion, you can participate in our community right here on Github

Slack Chat

We also have an active Slack community. Come and join the conversation!

Tutorials

There are several example notebooks to help you get started.

You can find the datasets used in the tutorials, including data preprocessing examples, in our neuralprophet-data repository.

Please refer to our documentation page for more resources.

Minimal example

from neuralprophet import NeuralProphet

After importing the package, you can use NeuralProphet in your code:

m = NeuralProphet()
metrics = m.fit(df)
forecast = m.predict(df)

You can visualize your results with the inbuilt plotting functions:

fig_forecast = m.plot(forecast)
fig_components = m.plot_components(forecast)
fig_model = m.plot_parameters()

If you want to forecast into the unknown future, extend the dataframe before predicting:

m = NeuralProphet().fit(df, freq="D")
df_future = m.make_future_dataframe(df, periods=30)
forecast = m.predict(df_future)
fig_forecast = m.plot(forecast)

Install

You can now install neuralprophet directly with pip:

pip install neuralprophet

Install options

If you plan to use the package in a Jupyter notebook, we recommended to install the 'live' version:

pip install neuralprophet[live]

This will allow you to enable plot_live_loss in the fit function to get a live plot of train (and validation) loss.

If you would like the most up to date version, you can instead install directly from github:

git clone <copied link from github>
cd neural_prophet
pip install .

Note for Windows users: Please use WSL2.

Features

Model components

• Autoregression: Autocorrelation modelling - linear or NN (AR-Net).
• Trend: Piecewise linear trend with optional automatic changepoint detection.
• Seasonality: Fourier terms at different periods such as yearly, daily, weekly, hourly.
• Lagged regressors: Lagged observations (e.g temperature sensor) - linear or NN.
• Future regressors: In advance known features (e.g. temperature forecast) - linear or NN.
• Events: Country holidays & recurring custom events.
• Global Modeling: Components can be local, global or 'glocal' (global + regularized local)

Framework features

• Multiple time series: Fit a global/glocal model with (partially) shared model parameters.
• Uncertainty: Estimate values of specific quantiles - Quantile Regression.
• Regularize modelling components.
• Plotting of forecast components, model coefficients and more.
• Time series crossvalidation utility.
• Model checkpointing and validation.

Coming soon^™️

• Cross-relation of lagged regressors.
• Static metadata regression for multiple series
• Logistic growth for trend component.

For a list of past changes, please refer to the releases page.

Cite

Please cite NeuralProphet in your publications if it helps your research:

@misc{triebe2021neuralprophet,
      title={NeuralProphet: Explainable Forecasting at Scale}, 
      author={Oskar Triebe and Hansika Hewamalage and Polina Pilyugina and Nikolay Laptev and Christoph Bergmeir and Ram Rajagopal},
      year={2021},
      eprint={2111.15397},
      archivePrefix={arXiv},
      primaryClass={cs.LG}
}

Many Thanks To Our Contributors:

About

NeuralProphet is an open-source community project, supported by awesome people like you. If you are interested in joining the project, please feel free to reach out to me (Oskar) - you can find my email on the NeuralProphet Paper.

neural_prophet's Issues

Trend: make possible for user to set specific changepoint times.

implement Learning-rate range test

implement add_seasonality() custom seasonality

add scalar regressor (known in advance)

do not call prep_data when plotting seasonality

plot_components - add documentation for default value for figsize

figsize parameter for plot_components has default value of None.

Add documentation for default behaviour.

separate plotting of components and weights

Standardize `figsize` parameter across plot functions

plot_components defaults to None
plot defaults to (10,6)

implement basic uncertainty estimation via Quantile Regression

plot_parameters: plot multiplicative and additive event weights separately

document current model formulation in math (latex document)

predict: receive two df 1) values up to present 2) future values.

implement one-cycle learning rate schedule

Trend: visualize important changepoints.

prettify train-eval printing

inspiration https://github.com/cs230-stanford/cs230-code-examples/tree/master/pytorch

Non-date data: Support equidistant data without datestamps

Currently, the best approach is to simply map it to some random series of datestamps.
A helper function to do this might be useful, as dealing with datetimes can be messy.

However, proper support for such data should be implemented eventually. It is not complex, but somewhat complicated as there are many touch points with datetime stamps.
This will entail:

• data checks and missing data imputation
• trend and seasonality computation
• plotting support

plot_components: plot events as sum of events instead of a plot per event

redact trend and seasonality from AR-inputs

move verbose print statements to a logger

Events and Holidays

Prophet documentation: https://facebook.github.io/prophet/docs/seasonality,_holiday_effects,_and_regressors.html

Train-Eval functions

add missing forecast components to df returned by predict() and change plot() to use those directly.

Trend: Make changepoint thresholding optional.

Logging references prophet when auto disabling seasonality

Update logging to mention NeuralProphet.

Current behaviour logs "Disabling daily seasonality. Run prophet with daily_seasonality=True to override this."

neural_prophet/neuralprophet/utils.py

Line 153 in af943a2

'Disabling {name} seasonality. Run prophet with '

plot_parameters: remove "delim" from event name

fix events breaking when n_lags==0

connect hidden layers of AR and Covar and potentially add other inputs.

covariates as lagged extra regressors

feature: model saving and loading functions using torch

inspiration
https://github.com/cs230-stanford/cs230-code-examples/tree/master/pytorch

Can simply save/load NeuralProphet.model
https://pytorch.org/tutorials/beginner/saving_loading_models.html

Issue:
must also store hyperparameter settings and any settings for events, regressors, etc.
may need a change in how configurations are stored/initialized

How:
We should implement this using torch.save() and torch.load()
with the recommended way of storing pytorch models
https://stackoverflow.com/questions/42703500/best-way-to-save-a-trained-model-in-pytorch

Metrics: Basic metrics to evaluate Forecasting Performance

Data: fail with specific error message when data contains duplicate date entries.

Add the values of different components such as seasonalities, holidays into the forecast object returned to the user.

Collection of Time-Series Datasets

We are looking to release a collection of example datasets that are ready to use with NeuralProphet. Of course they must be openly available without conflicting copyrights.

Sources may include:

• http://www.ercot.com/gridinfo/load/load_hist
• https://www.kaggle.com/robikscube/hourly-energy-consumption

test intra-day seasonality

fix bug when using get_last_forecasts(1) with n_lags=1

might be good to make all inputs 3D, including time.

plot components from forecast object columns instead of calling predict_component_x

crop_last_n parameter of plot_components not working with residuals plot

Title is descriptive.

When using the parameter crop_last_n from plot_components, the Residuals plot is empty and not aligned with other plots.

make plotting more efficient for high-resolution/long time series

regularize covariates

plot_components: error when hist=0

regularize seasonality

Data: raise error or handle if certain periodic data is missing (e.g. no Sundays) because fourier terms would be random there.

de-normalize metrics

m.plot_components plots seasonality for all available history

m.plot_components plots the seasonality for all of the available history.

This can make some plots - like the weekly seasonality - not so easy to understand. See attachment.

According to documentation, crop_last_n, which would help alleviate this issue, should be ignored for seasonality.

predict: remove implicit history pass.

make metric a class

Measure computation times, Find bottlenecks and speed up.

Trend Regularization: Find better way to regularize

Needed for better learning of trend deltas without gradient bleedover to older trend delta parameters. This is important if we want to achieve proper automatic trend-changepoint detection.

Data: implement other frequency handling than daily. (Monthly, yearly and sub-daily data handling)

add scalar regressor (lagged)