Introduction

Prophet is a calendar-aware additive model that mixes trend, seasonalities, and holiday effects with robust defaults, making it ideal for fast, business-facing forecasts. It ships for Python and R, is resilient to missing data/outliers, and includes built-in tools for time-series cross-validation. Recent 1.1.x releases rely on a cmdstan backend and add practical improvements like scaling.

Core Model Concepts

Additive structure

(y(t)=g(t)+s(t)+h(t)+\epsilon_t) with linear/logistic trend (g(t)), yearly/weekly/daily seasonalities (s(t)), holiday effects (h(t)), and noise. Works best when strong calendar seasonality exists and you have several seasons of history.

Installation

  • Python: python -m pip install prophet or conda install -c conda-forge prophet
    Name changed from fbprophet → prophet at v1.0. Min Python ≥3.7.
  • Backend: Python switched to cmdstan + cmdstanpy; binaries are prepackaged and a fixed cmdstan is downloaded by default.

Quick Start (Python)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

import pandas as pd
from prophet import Prophet

df = pd.read_csv("series.csv")  # must have ds, y
df['ds'] = pd.to_datetime(df['ds'])

m = Prophet(seasonality_mode="additive", changepoint_prior_scale=0.05, interval_width=0.95)
m.add_country_holidays(country_name='US')
m.add_seasonality(name='monthly', period=30.5, fourier_order=5)
m.fit(df)

future = m.make_future_dataframe(periods=90, freq='D')
forecast = m.predict(future)

m.plot(forecast); m.plot_components(forecast);

Tuning the Model

Trend & changepoints

Control flexibility with changepoint_prior_scale, define search region via changepoint_range, or specify changepoint dates explicitly. Use CV to avoid over/underfitting.

Seasonalities & modes

Enable/disable yearly/weekly/daily; add custom seasonalities; pick "additive" vs "multiplicative" depending on scale effects.

Holidays & events

add_country_holidays(country_name=...) to include built-in holiday calendars; or pass a custom holiday dataframe with windows around events (e.g., Black Friday ±1 day).

Newer options (1.1.5+)

scaling={'absmax','minmax'} controls target scaling; NumPy 2.0 and Apple Silicon support improvements are included in recent releases.

Cross-Validation & Metrics

Prophet provides rolling-origin CV:

1
2
3

from prophet.diagnostics import cross_validation, performance_metrics
df_cv = cross_validation(m, horizon='30 days', period='15 days', initial='365 days')
df_pm = performance_metrics(df_cv)  # rmse, mae, mape, coverage

Plot error vs. horizon with plot_cross_validation_metric.

Production Tips

  • Ensure at least 2–3 seasons of history; prevent leakage in feature engineering.
  • Maintain profiles by horizon (7/30/90d).
  • Use domain-driven regressors (price, promo, weather) via add_regressor.
  • Inspect components to validate business narratives.

Conclusion

Prophet is a strong baseline for calendar-driven series thanks to its additive structure, holiday awareness, and robust defaults. Pair hypothesis-led feature design with CV-based tuning to reach reliable forecasts—then consider advanced models only if they beat this baseline.

Summary

  • Calendar-aware additive model with trend, seasonalities, holidays
  • Simple API for fast baselines; resilient to missing data/outliers
  • cmdstan backend since 1.1.x; easier installs and better compatibility
  • Use CV (cross_validation, performance_metrics) to tune changepoints/seasonalities
  • Add domain regressors and custom holidays for lift

#prophet #time-series #forecasting #python #r #changepoints #seasonality #holidays #ml #datascience

References