API Reference / algorithms / timeseries /

prophet.py

Prophet forecasting model for business time series.

Classes

Prophet

class algorithms.timeseries.prophet.Prophet(Regressor)

Prophet forecasting model for business time series with trend, seasonality, and holiday effects.

Prophet is a procedure for forecasting time series data based on an additive decomposition model where non-linear trends are fit with yearly, weekly, and daily seasonality, plus holiday effects. It works best with time series that have strong seasonal effects and several seasons of historical data.
Constructor 
__init__(
    self,
    growth: str = 'linear',
    changepoints: List[str] | None = None,
    n_changepoints: int = 25,
    changepoint_range: float = 0.8,
    yearly_seasonality: bool | int | str = 'auto',
    weekly_seasonality: bool | int | str = 'auto',
    daily_seasonality: bool | int | str = 'auto',
    seasonality_mode: str = 'additive',
    seasonality_prior_scale: float = 10.0,
    changepoint_prior_scale: float = 0.05,
    holidays_prior_scale: float = 10.0,
    mcmc_samples: int = 0,
    interval_width: float = 0.8,
    uncertainty_samples: int = 1000,
)

Overview

The Prophet modeling procedure follows these steps:

  1. Decompose the time series into trend, seasonality, and holiday
components using an additive (or multiplicative) model.
  1. Fit a piecewise linear (or logistic) growth model for the trend,
automatically detecting changepoints.
  1. Model seasonal patterns using Fourier series with configurable
order for yearly, weekly, and daily periodicities.
  1. Incorporate holiday effects as indicator variables with prior
regularization.
  1. Generate forecasts by summing the extrapolated components and
optionally produce uncertainty intervals via simulation.

Theory

Prophet uses a decomposable time series model with three main structural components: trend, seasonality, and holidays.

y(t) = g(t) + s(t) + h(t) + \epsilon_t
where:
  • g(t): The trend function which models non-periodic changes
in the value of the time series.
  • s(t): Periodic changes (e.g., weekly and yearly seasonality).
  • h(t): The effects of holidays which occur on potentially
irregular schedules over one or more days.
  • \epsilon_t: The error term represents any idiosyncratic
changes which are not accommodated by the model (assumed to be normally distributed).

Trend Component g(t): Prophet implements a piecewise linear growth model:

g(t) = (k + a(t)^T \delta)t + (m + a(t)^T \gamma)

Seasonality Component s(t): The seasonal component is modeled using Fourier series:

s(t) = \sum_{n=1}^N \left( a_n \cos\left(\frac{2\pi n t}{P}\right) + b_n \sin\left(\frac{2\pi n t}{P}\right) \right)

Parameters

growth
{"linear", "logistic"} = "linear"
The trend growth model.
changepoints
list of str = None
List of dates at which to include potential changepoints.
n_changepoints
int = 25
Number of potential changepoints to automatically detect.
changepoint_range
float = 0.8
Proportion of history in which trend changepoints are allowed.
yearly_seasonality
bool, int, or "auto" = "auto"
Fit yearly seasonality.
weekly_seasonality
bool, int, or "auto" = "auto"
Fit weekly seasonality.
daily_seasonality
bool, int, or "auto" = "auto"
Fit daily seasonality.
seasonality_mode
{"additive", "multiplicative"} = "additive"
How seasonality components are integrated into the forecast.
seasonality_prior_scale
float = 10.0
Parameter modulating the strength of the seasonality model.
changepoint_prior_scale
float = 0.05
Parameter modulating the flexibility of the automatic changepoint selection.
holidays_prior_scale
float = 10.0
Parameter modulating the strength of the holiday effects.
mcmc_samples
int = 0
If > 0, will perform full Bayesian sampling with the specified number of MCMC samples.
interval_width
float = 0.80
Width of the uncertainty intervals provided for the forecast.
uncertainty_samples
int = 1000
Number of simulated draws used to estimate uncertainty intervals.

Attributes

trend_
np.ndarray
The fitted trend component.
seasonal_
np.ndarray
The fitted seasonal component.
params_
dict
The fitted model parameters.
changepoints_
np.ndarray
The detected changepoint locations.
n_features_in_
int
The number of input features (always 1 for univariate).

Notes

Complexity:

  • Training: O(n \cdot k) where n is the number of
samples and k is the number of features/holiday effects.
  • Prediction: O(h) where h is the forecast horizon.
When to use Prophet:
  • Business time series with strong seasonal patterns (yearly, weekly, daily)
  • Data with holiday effects or known special events
  • Time series with missing values or outliers
  • When an analyst-friendly, easily tunable model is desired
  • Long-horizon forecasting where trend changepoints are expected

References

Taylor2018
Taylor, S. J., & Letham, B. (2018). Forecasting at scale. The American Statistician, 72(1), 37-45.
Prophet
Facebook Prophet Documentation: https://facebook.github.io/prophet/

See Also

ExponentialSmoothing

Classical smoothing methods with trend and seasonality.
STLDecomposition

Decomposition of trend and seasonal components using LOESS.
ARIMA

Box-Jenkins approach to forecasting non-stationary series.
python 
>>> import numpy as np
>>> import pandas as pd
>>> from tuiml.algorithms.timeseries import Prophet
>>> # Generate synthetic data
>>> dates = pd.date_range('2020-01-01', periods=100, freq='D')
>>> y = np.arange(100) * 0.1 + np.random.normal(size=100)
>>> model = Prophet()
>>> model.fit(y, dates=dates)
>>> forecast = model.predict(steps=10)

Methods

get_parameter_schema (cls) -> Dict[str, Dict[str, Any]]

Return JSON Schema for algorithm parameters.

get_capabilities (cls) -> List[str]

Return supported capabilities.

get_complexity (cls) -> str

Return complexity analysis.

get_references (cls) -> List[str]

Return academic citations.

fit (self, y: np.ndarray, dates: Optional[pd.DatetimeIndex]=None, _X: Optional[np.ndarray]=None) -> 'Prophet'

Fit the Prophet model to time series data.

Parameters
y
np.ndarray of shape (n_samples,)
Time series values to fit.
dates
pd.DatetimeIndex = None
Datetime index for the series. Recommended for best results.
_X
np.ndarray = None
Ignored. Present for API consistency with regressors.
Returns
self
Prophet
Fitted estimator.
predict (self, steps: int=1, freq: str='D', include_history: bool=False) -> np.ndarray | pd.DataFrame

Forecast future values using the fitted Prophet model.

Parameters
steps
int = 1
Number of future time steps to forecast.
freq
str = "D"
Frequency of predictions ('D' for daily, 'W' for weekly, etc.).
include_history
bool = False
If True, return a DataFrame containing the forecast and its components (trend, seasonal, etc.). If False, return only the forecasted values as an array.
Returns
forecast
np.ndarray or pd.DataFrame
The forecasted values or a detailed components DataFrame.
fit_predict (self, y: np.ndarray, steps: int=1, dates: Optional[pd.DatetimeIndex]=None) -> np.ndarray

Fit the model and forecast future values in one step.

Parameters
y
np.ndarray of shape (n_samples,)
Time series values to fit.
steps
int = 1
Number of future time steps to forecast.
dates
pd.DatetimeIndex
Datetime index for the series.
Returns
forecast
np.ndarray of shape (steps,)
Forecasted values.
plot_components (self)

Plot forecast components (trend, seasonality).

Returns
fig
matplotlib.figure.Figure
Figure with component plots.