Prophet for Time Series Forecasting
What Prophet is designed for
Prophet, released by Facebook's Core Data Science team in 2017, is a forecasting library built around a simple premise: most business time series — sales, signups, server load — share a common structure of trend, multiple seasonalities, and holiday effects, and a model that makes this structure explicit will be both more accurate and far easier for a non-specialist to tune than a general-purpose ARIMA model.
Prophet models the series as an additive (or optionally multiplicative) decomposition: $y(t) = g(t) + s(t) + h(t) + \epsilon_t$, where $g(t)$ is a piecewise trend, $s(t)$ captures seasonality via Fourier terms, $h(t)$ captures holiday and event effects, and $\epsilon_t$ is noise assumed normally distributed.
The trend component: piecewise linear or logistic growth
Prophet's trend $g(t)$ is either piecewise linear or piecewise logistic. The piecewise linear form lets the growth rate change at a set of changepoints: $g(t) = (k + \mathbf{a}(t)^T \boldsymbol{\delta}) t + (m + \mathbf{a}(t)^T \boldsymbol{\gamma})$, where $k$ is the base growth rate, $\boldsymbol{\delta}$ are rate adjustments at each changepoint, and $\mathbf{a}(t)$ indicates which changepoints have occurred by time $t$. Changepoints are placed automatically (by default, at the first 80% of the series, evenly spaced) and a sparse prior pushes most of the $\delta_j$ adjustments toward zero, so the model only bends the trend where the data really demands it.
The logistic form adds a saturating carrying capacity, useful for series that are expected to plateau — like adoption curves approaching market saturation.
Seasonality as a Fourier series
Rather than estimating a separate parameter for every day of the year, Prophet represents each seasonal component as a truncated 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)$, where $P$ is the period (365.25 for yearly, 7 for weekly) and $N$ controls how flexible the seasonal curve can be. More Fourier terms let the seasonal shape capture sharper features but risk overfitting; Prophet defaults to $N=10$ for yearly and $N=3$ for weekly seasonality. Holiday effects are added as simple indicator regressors, each with its own estimated effect size and an optional window of days before/after the holiday.
import pandas as pd
from prophet import Prophet
# Prophet expects columns named exactly 'ds' (date) and 'y' (value)
df = pd.read_csv("daily_sales.csv")
df = df.rename(columns={"date": "ds", "sales": "y"})
model = Prophet(
growth="linear",
changepoint_prior_scale=0.05, # flexibility of the trend
seasonality_mode="multiplicative",
yearly_seasonality=True,
weekly_seasonality=True,
)
model.add_country_holidays(country_name="US")
model.add_seasonality(name="monthly", period=30.5, fourier_order=5)
model.fit(df)
future = model.make_future_dataframe(periods=90) # forecast 90 days ahead
forecast = model.predict(future)
print(forecast[["ds", "yhat", "yhat_lower", "yhat_upper"]].tail())
fig1 = model.plot(forecast)
fig2 = model.plot_components(forecast) # trend / weekly / yearly / holidays, separately
Prophet is fit with Bayesian MAP estimation, not just least squares
mcmc_samples > 0) for more accurate uncertainty intervals at the cost of much slower fitting. The priors on changepoint magnitudes and seasonality coefficients act as built-in regularization, which is why Prophet tends to behave reasonably even with relatively little tuning.Uncertainty intervals and their caveats
Prophet's uncertainty intervals come from two sources: uncertainty in the trend (simulated by assuming future changepoints will occur at the same average rate and magnitude as historical ones) and, if using MCMC, uncertainty in the seasonality and parameters themselves. By default only trend uncertainty is included, which means Prophet's intervals can be noticeably too narrow — they don't account for parameter uncertainty in the seasonal terms or for unmodeled regressors. Widening interval_width or enabling MCMC sampling are the usual remedies when calibrated intervals matter.
Prophet struggles with sub-daily patterns and abrupt regime changes
Prophet vs. classical seasonal models
| Aspect | Prophet | SARIMA |
|---|---|---|
| Seasonality | Fourier series, flexible | Fixed seasonal differencing order |
| Trend changes | Automatic changepoints | Requires manual differencing/re-fit |
| Missing data / irregular timestamps | Handled natively | Needs regular, gap-free series |
| Tuning effort | Low, sensible defaults | Higher, requires ACF/PACF analysis |
What's next
Prophet is a strong, interpretable baseline for business-style seasonal series, but it isn't the right tool for every shape of time series — especially ones with complex nonlinear dependencies or long memory that a hand-specified additive model can't capture. That gap is exactly where learned sequence models come in, trading some interpretability for the ability to discover patterns directly from the data.
I build these systems professionally.
Whether it's a RAG pipeline, analytics migration, or AI workflow — let's talk.