NeuralProphet Documentation

NeuralProphet is a time series forecasting library built on PyTorch that fuses traditional algorithms with deep learning. Key features include:

• Global Modeling: Support for modeling many time series simultaneously.
• Automated Hyperparameters: Automatic selection of training-related hyperparameters.
• Visualization: Plotting utilities for forecast components, model coefficients, and final predictions.
• Local Context: Support for Autoregression and lagged covariates.
• Trend & Seasonality: Support for changing trends and smooth seasonality at different periods.
• Exogenous Effects: Modeling of events, holidays, and future regressor effects.
• Customization: Extensive options such as regularization.

NeuralProphet uses a modular component system based on a BaseComponent class. Components are organized into several main categories: Trend, FutureRegressors, and Seasonality.

Key inheritance paths include:

• Trend: Includes LinearTrend (which branches into GlobalLinearTrend and LocalLinearTrend), StaticTrend, and PiecewiseLinearTrend (which branches into GlobalPiecewiseLinearTrend and LocalPiecewiseLinearTrend).
• FutureRegressors: Includes LinearFutureRegressors.
• Seasonality: Includes FourierSeasonality (which branches into GlobalFourierSeasonality and LocalFourierSeasonality).

NeuralProphet is a decomposable time series model built on PyTorch. It decomposes a time series into several distinct components that can be modeled independently:

• Trend: Can be modeled as a linear or piece-wise linear trend using changepoints.
• Seasonality: Modeled using Fourier terms, supporting multiple seasonalities for high-frequency data.
• Auto-regression: Implemented via AR-Net (an Auto-Regressive Feed-Forward Neural Network).
• Special Events: Modeled as covariates with dedicated coefficients.
• Future Regressors: External variables where future values are known for the forecast period.
• Lagged Regressors: External variables where only observed period values are available; these are modeled using separate Feed-Forward Neural Networks.

If you are working in a Jupyter notebook and want to use the plot_live_loss feature during the fit process to see real-time training and validation loss, install the [live] extra.

pip install neuralprophet[live]

NeuralProphet provides detailed guides for implementing specific advanced features. Use these guides for deep dives into functionality beyond basic tutorials. Key topics include:

• Predictions & Validation: Collecting predictions, testing, and cross-validation.
• Modeling Techniques: Global-Local modeling, Uncertainty Quantification, Conditional Seasonality, Multiplicative Seasonality, Sparse Autoregression, and Subdaily data handling.
• Optimization & Monitoring: Hyperparameter selection, MLflow integration, and live plotting during training.
• Visualization: Plotting with Plotly and visualizing network architectures.

NeuralProphet is suitable for practitioners who need:

• Flexible Forecasting: Support for both single-step and multi-step-ahead forecasts.
• Global Forecasting: The ability to build models based on a group of time series (global forecasting models).
• External Drivers: Scenarios where external factors (regressors) drive the target series behavior.
• Interpretability: Users can visualize forecasts, individual components, and underlying coefficients.
• Control: Ability to control coefficients via regularization (sparsity) and combine components either additively or multiplicatively.

NeuralProphet provides several learning paths for users:

• Quickstart: A foundational tutorial located in the source folder to get you up and running immediately.
• Basic Tutorials: Found in the /docs/source/tutorials/ directory, these cover fundamental concepts.
• How-to Guides: Found in the /docs/source/how-to-guides/ directory, these contain advanced notebooks covering specific features and practical application examples.

NeuralProphet performs imputation for missing values, but the behavior depends on whether auto-regression is enabled:

• With Auto-regression enabled:
  • Imputation is performed.
  • For numeric data (including y), a two-step process is used: small gaps are filled with linear imputation, and larger gaps are filled with rolling averages.
  • Users can choose to skip imputation or drop missing values (use caution as this may affect performance).
• Without Auto-regression:
  • Missing values are less critical for the regression model.
• Binary Data: Missing values for binary data are treated as 0.