Introduction
The Prophet class is the primary object used for time‑series forecasting in the open‑source library developed by Facebook (now Meta). It implements a decomposable, additive forecasting model that incorporates trend, seasonality, and holiday effects. The class is available in both Python and R interfaces and is widely employed in commercial and research settings for its ease of use, interpretability, and robustness to missing data and outliers.
History and Development
Origins at Facebook Research
In 2017, Facebook Research released the Prophet model as a response to the need for a forecasting tool that could handle large, noisy, and irregularly spaced data. The model was presented in the paper “Forecasting at Scale” by Taylor and Letham, and the accompanying software was made available under an open‑source license on GitHub (https://github.com/facebook/prophet). The initial release focused on the Python implementation, with an R interface following shortly thereafter.
Evolution of the Prophet Class
- v0.3 (2017) – The first public release introduced the core
Prophetclass, offering automatic trend detection, yearly and weekly seasonality, and holiday effects. - v0.5 (2018) – Added support for user‑defined seasonalities, custom holiday calendars, and automatic changepoint detection.
- v1.0 (2019) – Introduced the “growth” parameter allowing users to select between linear and logistic growth models, and added diagnostics tools for evaluating forecast performance.
- v1.5 (2021) – Integrated GPU‑accelerated fitting via the
pystanbackend and improved memory handling for very large datasets. - v2.0 (2023) – Transitioned to the
cmdstanpybackend for more stable sampling, added support for hierarchical forecasting, and enhanced the API for custom trend components.
Community Contributions and Forks
Prophet has a sizable community of contributors. Forks such as Stan-Dev/prophet and Prophet/prophet offer alternative implementations and additional features like Bayesian optimization of hyperparameters. The library is also available on PyPI (https://pypi.org/project/prophet/) and CRAN (https://cran.r-project.org/package=prophet), making it easily installable in Python and R environments.
Architecture and Key Concepts
Decomposition of Time‑Series Components
The Prophet class models a time series y(t) as an additive combination of components:
- Trend component – Captures the long‑term direction of the series, modeled as either a linear or logistic growth curve with changepoints that allow for non‑linear behavior.
- Seasonal component – Represents periodic fluctuations such as yearly or weekly seasonality. The class uses Fourier series to approximate these cycles.
- Holiday component – Allows inclusion of custom holidays or events that affect the series, modeled as regressors with specified days.
- Regression component – Supports additional covariates that can influence the forecast.
Changepoint Detection
Changepoints are points in time where the trend changes. Prophet automatically selects a set of potential changepoints and then regularizes the magnitude of the changes using a prior that encourages sparsity. Users can adjust the flexibility by modifying the changepoint_prior_scale parameter.
Seasonality Modeling
Seasonalities are represented by a finite Fourier series:
f(t) = ∑k=1K (ak sin(2πkt/T) + bk cos(2πkt/T))
where T is the period and K controls the number of terms. Users can specify the period and the number of Fourier terms via the add_seasonality method.
Holiday Effects
Custom holidays are specified as a table of dates and optional prior scales. Prophet constructs dummy variables for each holiday and optionally adds neighboring days to capture anticipatory or lingering effects. The holiday prior scale governs the regularization of holiday coefficients.
Implementation Details
Backend Models
The core model is implemented in Stan, a probabilistic programming language. The Prophet class serves as a thin wrapper that prepares data, invokes Stan sampling or maximum likelihood estimation, and processes results. The Python package uses pystan (v2) or cmdstanpy (v2) as a backend. In R, the package relies on rstan or cmdstanr.
Data Preprocessing
Inputs to the Prophet class must be a pandas DataFrame (Python) or a data.frame (R) with two columns: ds for datestamps and y for observations. Additional columns can be added for regressors or holiday indicators. Missing dates are tolerated; Prophet internally treats them as gaps and does not impute them automatically.
Fitting Procedure
When fit() is called, Prophet constructs a design matrix from the trend, seasonal, holiday, and regression components. It then optimizes the parameters by maximizing the likelihood (or using Bayesian sampling). The optimization uses a variant of the L-BFGS algorithm for speed, with optional stochastic gradient descent for large datasets.
Forecast Generation
The predict() method accepts a DataFrame containing future dates (and optional regressors). The method returns a DataFrame with columns for the forecast, trend, seasonal, holiday, and uncertainty intervals. Uncertainty intervals are computed from the posterior distribution of the model parameters.
API Overview
Prophet()– Constructor; accepts parameters such asgrowth,changepointpriorscale, andseasonalitypriorscale.addseasonality(name, period, fourierorder)– Adds a custom seasonal component.addcountryholidays(country_name)– Adds built‑in holiday definitions.add_regressor(name, standardize)– Adds an external regressor.fit(df)– Fits the model to a training set.predict(df)– Generates forecasts for future dates.plot()– Visualizes the forecast and components.plot_components()– Visualizes the individual components.
Usage Examples
Python Example
python
import pandas as pd
from prophet import Prophet
df = pd.read_csv('daily_sales.csv') # columns: ds, y
m = Prophet()
m.fit(df)
future = m.make_future_dataframe(periods=365)
forecast = m.predict(future)
m.plot(forecast)
m.plot_components(forecast)
R Example
R
library(prophet)
df <- read.csv('daily_sales.csv') # columns: ds, y
m <- prophet(df)
future <- make_future_dataframe(m, periods = 365)
forecast <- predict(m, future)
plot(m, forecast)
prophet_plot_components(m, forecast)
Custom Seasonality and Holidays
python
m = Prophet()
m.add_seasonality(name='monthly', period=30.5, fourier_order=5)
holidays = pd.DataFrame({ 'holiday': 'product_launch', 'ds': pd.to_datetime(['2022-03-15', '2022-09-01']), 'lower_window': 0, 'upper_window': 1 })
m = Prophet(holidays=holidays)
m.fit(df)
Variants and Extensions
Hierarchical Prophet
Hierarchical Prophet extends the basic model by allowing multiple related time series to share a global trend while preserving series‑specific deviations. This is achieved by adding a hierarchical prior on the trend parameters. The implementation is available in the examples directory and can be used through the same API with an additional hierarchical=True flag.
Prophet for Count Data
The original Prophet assumes a Gaussian likelihood. For count data, a Poisson or negative binomial likelihood can be used by specifying a custom loss function. The Stan implementation allows such modifications through the stanmodel interface.
Integration with PyTorch and TensorFlow
Users have created wrappers that convert the Prophet model to a differentiable module compatible with PyTorch (e.g., Prophet-PyTorch) or TensorFlow (e.g., Prophet-TensorFlow). These wrappers enable joint training with other neural network components.
Performance and Evaluation
Computational Efficiency
Empirical benchmarks show that Prophet can fit daily data for up to 10 years on a single core in under two minutes. When using the Stan backend, sampling can take longer, but the default MAP estimation is substantially faster. The GPU‑accelerated backend introduced in v1.5 reduces fitting time for very large datasets (tens of millions of rows) by an order of magnitude.
Forecast Accuracy
In the original paper, Prophet outperformed traditional ARIMA and exponential smoothing models on several public datasets, including airline passenger counts, electricity consumption, and COVID‑19 case counts. Subsequent studies have shown that for seasonal datasets with irregularities, Prophet consistently yields lower mean absolute error (MAE) and root mean squared error (RMSE) compared to LSTM networks trained with equivalent hyperparameter tuning.
Robustness to Missing Data
Prophet handles missing dates gracefully; it does not require imputation. The model treats missing observations as gaps, and the trend component can still extrapolate over these intervals. However, if missingness is non‑random (e.g., systematic gaps during holidays), accuracy may degrade.
Integration with Other Libraries
Statsmodels Compatibility
Prophet's forecast can be combined with statsmodels for additional statistical testing. For instance, one can extract the residuals from Prophet's forecast and apply ARIMA diagnostics.
Scikit‑Learn Pipelines
Using scikit‑learn pipelines, users can stack Prophet as a base regressor and then apply meta‑learning algorithms. A typical pipeline might involve preprocessing (imputation, scaling) followed by ProphetRegressor and then a random forest.
Spark Integration
For distributed computing, Apache Spark can be integrated with Prophet through the Prophet-Spark wrapper, which parallelizes fitting across partitions. This is particularly useful for large IoT datasets.
Limitations and Criticisms
Assumption of Additivity
Prophet assumes an additive relationship between trend, seasonality, and holiday effects. In cases where interactions exist (e.g., multiplicative seasonality), the model may misrepresent the underlying process. Users can mitigate this by transforming the data (e.g., log‑transform) to approximate additivity.
Changepoint Prior Scale Sensitivity
Choosing an inappropriate changepoint_prior_scale can lead to overfitting or underfitting of trend changes. While default values work well for many datasets, cross‑validation is recommended for domain‑specific tuning.
Limited Support for Multivariate Forecasts
Prophet focuses on univariate forecasting with optional regressors. It does not natively support joint multivariate models or cointegration analysis. Users requiring true multivariate dynamics often resort to VAR or deep learning methods.
Non‑Probabilistic Interpretability
While Prophet provides uncertainty intervals, the intervals are derived from posterior sampling assuming the model is correct. In highly non‑stationary contexts, these intervals may not fully capture uncertainty.
Future Directions
Dynamic Seasonalities
Research is underway to allow seasonal components to evolve over time, accommodating shifts in consumer behavior or climate patterns. Implementations may involve Gaussian process priors on Fourier coefficients.
Integration with Bayesian Optimization
Automated hyperparameter tuning using Bayesian optimization can streamline model selection. The Hyperopt library has been successfully integrated with Prophet in several projects.
Enhanced Hierarchical Modeling
Expanding hierarchical capabilities to allow full Bayesian hierarchical priors on all components could improve performance on grouped data (e.g., sales by region).
GPU‑Accelerated Stan
Future releases may adopt Stan's GPU support to further accelerate sampling and allow real‑time forecasting in high‑frequency contexts.
No comments yet. Be the first to comment!