Prophet Parameter Tuning and Practical Guide for Time Series Forecasting

The previous article introduced Prophet's features and basic usage; this follow‑up focuses on practical parameter tuning for real‑world applications.

1. Parameter Understanding

class Prophet(object): def __init__(self, growth='linear', changepoints=None, n_changepoints=25, changepoint_range=0.8, yearly_seasonality='auto', weekly_seasonality='auto', daily_seasonality='auto', holidays=None, seasonality_mode='additive', seasonality_prior_scale=10.0, holidays_prior_scale=10.0, changepoint_prior_scale=0.05, mcmc_samples=0, interval_width=0.80, uncertainty_samples=1000, stan_backend=None): pass

Growth : determines the trend function; options are linear or logistic . Only one can be active per model.

Changepoints : dates where the trend may change. If not supplied, Prophet automatically detects them.

n_changepoints : maximum number of automatically detected changepoints (ignored if changepoints is set).

changepoint_range : proportion of the history in which changepoints are allowed to appear; works together with n_changepoints .

changepoint_prior_scale : flexibility of automatic changepoint selection; larger values make changepoints easier to appear.

1.1 Seasonal Parameters

yearly_seasonality : enable yearly seasonality (True/False) or set the number of Fourier terms (default 10).

weekly_seasonality : similar to yearly, default 3 Fourier terms.

daily_seasonality : activated only for hourly data.

seasonality_mode : 'additive' (default) or 'multiplicative' .

seasonality_prior_scale : controls the strength of seasonal components; larger values increase their influence.

1.2 Holiday Parameters

holidays : a pd.DataFrame with columns holiday , ds , upper_window , lower_window . Example rows for New Year's Day are shown.

holiday_prior_scale : adjusts the impact of holiday effects.

1.3 Other Parameters

mcmc_samples : 0 uses MAP estimation; >0 performs full Bayesian inference via MCMC, providing uncertainty intervals.

interval_width : width of the predictive interval (default 0.80).

uncertainty_samples : number of samples for estimating uncertainty intervals; set to 0 to skip.

stan_backend : choose between CMDSTANPY (recommended on Windows) and PYSTAN (Linux).

2. Parameter Tuning in Practice

Because production time‑series models often involve massive datasets, manual tuning is infeasible; grid search with cross‑validation is recommended.

Key evaluation metrics in Prophet include MSE, RMSE, MAE, MAPE, and coverage. Users may also define custom metrics such as the 0.8‑quantile of relative error.

class ProphetTrain(ABC):
    def __init__(self, name=None):
        self.name = name
        self.data: pd.DataFrame = None
        self.params = {"holidays": holidays}
        self.mape = np.inf
        self.model = None
        self.grid_search_params_path = None
        self.predict_freq_num = 7
        self.freq = 'd'
    # ... (methods for loading data, cross‑validation, running, grid search, saving/loading model) ...

The grid_search method iterates over combinations of:

seasonality_mode : ['additive', 'multiplicative']

changepoint_range : [0.3, 0.4, ..., 0.9]

seasonality_prior_scale : [0.05, 0.1, 0.5, 1, 5, 10, 15]

holidays_prior_scale : same range as above

For each combination, the model is either evaluated with Prophet's built‑in cross_validation function or with a simple run call, and the best MAPE score and parameters are stored.

3. Conclusion

No single algorithm fits every scenario; understanding the underlying mathematics and adapting the model to the data (e.g., replacing the default normal prior for holidays with an F‑distribution) can significantly improve accuracy.

References

Prophet official documentation: https://facebook.github.io/prophet/

Prophet paper: https://peerj.com/preprints/3190/

Prophet GitHub repository: https://github.com/facebook/prophet