Intermediate

Facebook Prophet

Prophet is an additive regression model designed for business forecasting. It handles holidays, changepoints, and multiple seasonalities with minimal tuning.

Why Prophet?

Prophet was developed by Facebook's Core Data Science team to address common business forecasting challenges:

  • Handles missing data and outliers gracefully without imputation.
  • Multiple seasonalities: Daily, weekly, and yearly patterns simultaneously.
  • Holiday effects: Built-in support for holiday calendars.
  • Changepoints: Automatic detection of trend changes.
  • Analyst-friendly: Interpretable components and intuitive parameters.
Bash — Installation
pip install prophet

Basic Usage

Python — Prophet quickstart
from prophet import Prophet
import pandas as pd

# Prophet requires columns named 'ds' (date) and 'y' (value)
df = pd.read_csv('sales.csv')
df = df.rename(columns={'date': 'ds', 'sales': 'y'})

# Fit the model
model = Prophet()
model.fit(df)

# Create future dataframe (365 days ahead)
future = model.make_future_dataframe(periods=365)
forecast = model.predict(future)

# Plot forecast
model.plot(forecast)

# Plot components (trend, weekly, yearly seasonality)
model.plot_components(forecast)

Adding Holidays

Python — Custom holidays
import pandas as pd
from prophet import Prophet

# Define custom holidays
holidays = pd.DataFrame({
    'holiday': 'black_friday',
    'ds': pd.to_datetime([
        '2023-11-24', '2024-11-29', '2025-11-28'
    ]),
    'lower_window': -1,   # 1 day before
    'upper_window': 1,    # 1 day after
})

# Or use built-in country holidays
model = Prophet(holidays=holidays)
model.add_country_holidays(country_name='US')
model.fit(df)

Tuning Prophet

Python — Advanced configuration
model = Prophet(
    growth='linear',              # or 'logistic' for saturating growth
    changepoint_prior_scale=0.05, # flexibility of trend (default 0.05)
    seasonality_prior_scale=10,   # flexibility of seasonality
    holidays_prior_scale=10,      # flexibility of holiday effects
    seasonality_mode='multiplicative', # or 'additive'
    changepoint_range=0.8,        # proportion of history for changepoints
)

# Add custom seasonality
model.add_seasonality(
    name='monthly',
    period=30.5,
    fourier_order=5
)

# Add external regressors
model.add_regressor('temperature')
model.add_regressor('is_promotion')

model.fit(df)

Cross-Validation

Python — Prophet cross-validation
from prophet.diagnostics import cross_validation, performance_metrics

# Time series cross-validation
cv_results = cross_validation(
    model,
    initial='730 days',    # training period
    period='180 days',     # spacing between cutoff dates
    horizon='365 days'     # forecast horizon
)

# Compute metrics
metrics = performance_metrics(cv_results)
print(metrics[['horizon', 'mape', 'rmse', 'mae']].tail())

# Plot cross-validation metrics
from prophet.plot import plot_cross_validation_metric
plot_cross_validation_metric(cv_results, metric='mape')
✅
When to choose Prophet: Prophet excels at business forecasting with daily data that has strong seasonality and holiday effects. It is not the best choice for high-frequency data (sub-hourly), very short time series, or when you need multi-step multivariate forecasting.