Prophet: Automatic Forecasting Procedure

If holidays or seasonalities are overfitting, you can dampen their effects by reducing their prior scales. This increases regularization.

• Global Holiday Scale: Use holidays_prior_scale (Python) or holidays.prior.scale (R) in the model constructor to adjust all holidays.
• Global Seasonality Scale: Use seasonality_prior_scale (Python) or seasonality.prior.scale (R) in the model constructor.
• Individual Holiday Scale: Include a prior_scale column in your holidays dataframe.
• Individual Seasonality Scale: Pass prior_scale as an argument to add_seasonality.

# Python
# Dampen holiday effects
m = Prophet(holidays=holidays, holidays_prior_scale=0.05).fit(df)

# Set specific scale for a custom seasonality
m.add_seasonality(name='weekly', period=7, fourier_order=3, prior_scale=0.1)

# R
m <- prophet(df, holidays = holidays, holidays.prior.scale = 0.05)
m <- add_seasonality(m, name='weekly', period=7, fourier.order=3, prior.scale=0.1)

Prophet detects abrupt changes in time series trajectories by identifying potential changepoints. It places a large number of potential points (default is 25) uniformly across the first 80% of the time series. To prevent overfitting, Prophet applies a sparse prior (equivalent to L1 regularization) on the magnitudes of the rate changes, meaning it only uses a subset of these potential points where actual changes occur.

Key parameters for automatic detection:

• n_changepoints: Sets the number of potential changepoints (default is 25).
• changepoint_range: Determines the proportion of the history where potential changepoints are placed. The default is 0.8 (80%). Increasing this (e.g., to 0.9) allows detection closer to the end of the series, but may increase overfitting risk at the tail.

You can visualize the detected changepoints on a plot using the add_changepoints_to_plot utility.

# Python
from prophet.plot import add_changepoints_to_plot
fig = m.plot(forecast)
a = add_changepoints_to_plot(fig.gca(), m, forecast)

# R
plot(m, forecast) + add_changepoints_to_plot(m)

When using extra regressors in a multi-stage prediction pipeline, their future values are often unknown and carry uncertainty. As of Prophet v1.4.0, you can use nested Prophet models to integrate regressor forecasting directly into the main model's .predict() and cross_validate() workflows.

How it works:

1. Enable Nested Models: When calling .add_regressor(), set the regressor_predictor parameter (or predict_spec in some contexts) to enable a nested model.
   • Setting regressor_predictor=True uses default settings.
   • Passing a dictionary (e.g., regressor_predictor={'seasonality_prior_scale': 10.0}) allows for custom configuration of the nested model.
   • Limitation: Only simple nested Prophet models are supported. You cannot use nested models that require custom seasonalities via .add_seasonality() or their own additional regressors via .add_regressor().
2. Prediction: When you call .predict() on the main model, the regressor values are automatically filled using the yhat values generated by their respective nested Prophet models.
3. Cross-Validation: When running cross_validate(), the main model will first predict the regressor values for the lookahead range using the nested models. This prevents data leakage and ensures cross-validation results are not overstated by using known future regressor values.

from prophet import Prophet

# Initialize main model
m1 = Prophet(changepoint_range=0.9, seasonality_prior_scale=5.0)

# Add a regressor with a nested Prophet model to handle its own uncertainty
# Using a dictionary to pass custom configuration to the nested model
m1.add_regressor(
    "location_4", 
    mode="additive", 
    regressor_predictor={"seasonality_prior_scale": 10.0}
)

# Fit the main model (this will also fit the nested regressor model)
m1.fit(train_df)

# Predict (the regressor values are automatically forecasted by the nested model)
preds = m1.predict(test_df)

If your historical data contains regular gaps (e.g., only observations from 12a to 6a, or only weekdays), Prophet's seasonality models (daily, weekly, etc.) will be unconstrained for the missing periods. This often leads to poor forecasts with large, unrealistic fluctuations during the gaps.

Solution: Limit your future dataframe to only include the time windows present in your historical data. This ensures you only make predictions for the periods where the seasonality is well-estimated.

# Python example: filtering future dataframe to match historical hour gaps
df2 = df.copy()
df2['ds'] = pd.to_datetime(df2['ds'])
df2 = df2[df2['ds'].dt.hour < 6]

m = Prophet().fit(df2)
future = m.make_future_dataframe(periods=300, freq='H')

# CRITICAL: Filter future to only include hours present in history
future2 = future.copy()
future2 = future2[future2['ds'].dt.hour < 6]

fcst = m.predict(future2)
fig = m.plot(fcst)