Time Series Forecasting with Prophet Cheat Sheet
Forecast seasonal time series data using Meta's Prophet library, covering trend, seasonality, holidays, and cross-validation.
Fit a Model and Forecast
Prophet expects a two-column DataFrame with 'ds' (date) and 'y' (value) columns.
import pandas as pdfrom prophet import Prophetdf = pd.DataFrame({"ds": dates, "y": values}) # ds: datetime, y: numericmodel = Prophet( yearly_seasonality=True, weekly_seasonality=True, daily_seasonality=False, seasonality_mode="multiplicative",)model.fit(df)future = model.make_future_dataframe(periods=90) # 90 days aheadforecast = model.predict(future)print(forecast[["ds", "yhat", "yhat_lower", "yhat_upper"]].tail())
Add Holidays and Extra Regressors
Incorporate known holiday effects and additional predictive signals into the model.
holidays = pd.DataFrame({ "holiday": "black_friday", "ds": pd.to_datetime(["2025-11-28", "2026-11-27"]), "lower_window": -1, "upper_window": 1,})model = Prophet(holidays=holidays)model.add_regressor("marketing_spend")model.fit(df) # df must include a 'marketing_spend' column
Plot Forecast and Components
Visualize the forecast with uncertainty intervals and decompose it into trend/seasonality.
fig1 = model.plot(forecast)fig2 = model.plot_components(forecast) # trend, weekly, yearly panels# mark changepoints where the trend shiftedfrom prophet.plot import add_changepoints_to_plotadd_changepoints_to_plot(fig1.gca(), model, forecast)
Cross-Validate Forecast Accuracy
Backtest the model across multiple rolling cutoffs and compute error metrics.
from prophet.diagnostics import cross_validation, performance_metricscv_results = cross_validation( model, initial="730 days", period="180 days", horizon="90 days")metrics = performance_metrics(cv_results)print(metrics[["horizon", "mape", "rmse"]].head())
Key Model Parameters
The parameters most likely to need tuning for a real dataset.
- changepoint_prior_scale- controls trend flexibility; higher = trend adapts more to fluctuations
- seasonality_mode- 'additive' (default) vs 'multiplicative' for seasonality that scales with the trend
- seasonality_prior_scale- controls how strongly seasonal components can fit the data
- growth- 'linear', 'logistic' (needs a cap), or 'flat' trend assumption
- interval_width- width of the uncertainty interval, default 0.80
Always run cross_validation with realistic initial/period/horizon windows before trusting a Prophet forecast — a model that looks great on an in-sample plot.model() call often has much worse MAPE once you backtest it on rolling out-of-sample cutoffs.
