Introduction

Cross-validation in Prophet is not ordinary random-fold validation. It is a time-aware backtesting procedure that repeatedly fits the model on historical data up to a cutoff date, forecasts forward for a chosen horizon, and compares those forecasts with the actual values that came after the cutoff.

What Prophet Cross-Validation Is Actually Doing

If you shuffle time-series rows, you leak future information into the training set. Prophet avoids that by using simulated historical forecasts.

For each cutoff:

• fit the model using only data up to that cutoff
• forecast the future for the specified horizon
• compare predictions with real observed values in that future window

This is often called rolling-origin evaluation or forward-chaining validation.

The important Prophet parameters are:

• 'horizon: how far into the future each fold predicts'
• 'initial: how much history is used before the first cutoff'
• 'period: spacing between cutoffs'

According to the Prophet diagnostics documentation, the default initial window is three times the horizon and the default period is half the horizon.

A Runnable Python Example

The following example creates a simple synthetic daily series and evaluates a Prophet model with cross-validation.

1import numpy as np
2import pandas as pd
3from prophet import Prophet
4from prophet.diagnostics import cross_validation, performance_metrics
5
6np.random.seed(0)
7
8days = 500
9df = pd.DataFrame({
10    "ds": pd.date_range("2023-01-01", periods=days, freq="D"),
11    "y": np.linspace(10, 30, days)
12         + 2 * np.sin(np.arange(days) * 2 * np.pi / 7)
13         + np.random.normal(0, 0.5, days)
14})
15
16m = Prophet()
17m.fit(df)
18
19df_cv = cross_validation(
20    m,
21    initial="300 days",
22    period="60 days",
23    horizon="90 days"
24)
25
26print(df_cv[["ds", "cutoff", "y", "yhat"]].head())
27
28df_perf = performance_metrics(df_cv)
29print(df_perf[["horizon", "rmse", "mae", "coverage"]].head())

This produces a dataframe where each row corresponds to an out-of-sample forecasted point. The cutoff column tells you which training window produced that prediction.

How to Read the Output

The df_cv dataframe usually contains:

• 'ds: the predicted timestamp'
• 'cutoff: the last timestamp included in training'
• 'y: the actual observed value'
• 'yhat: the forecast'
• 'yhat_lower and yhat_upper: the prediction interval'

This means a single observed date can appear multiple times if it was forecast from multiple earlier cutoffs. That is normal. Cross-validation here is measuring how the model behaves from different historical starting points.

The performance_metrics helper summarizes those rows into measures such as:

• RMSE
• MAE
• MAPE
• coverage

Coverage is especially useful in Prophet because it tells you how often actual values fall inside the forecast interval.

Choosing initial, period, and horizon

These parameters should match the business question, not just arbitrary defaults.

If you care about forecasts 30 days ahead, set the horizon around 30 days. If you need quarterly planning, use a longer horizon.

The initial window must be long enough to capture the patterns your model needs. Prophet's documentation explicitly notes that the initial period should be long enough to include relevant seasonal structure, such as at least a full yearly cycle if yearly seasonality matters.

The period controls how many cutoff dates you evaluate. A smaller period gives more folds and more compute cost. A larger period gives fewer folds and coarser diagnostics.

In practice:

• small horizon for short-term operational forecasts
• large horizon for planning-style forecasts
• larger initial window when the series has yearly seasonality or extra regressors

What This Is Good For

Prophet cross-validation is useful for:

• comparing parameter choices
• checking how forecast error grows with prediction distance
• validating whether intervals are too narrow or too wide
• testing whether seasonal terms and regressors are helping

It is often better than looking at one final train-test split, because one split may be unusually easy or unusually hard.

Prophet also supports parallelized cross-validation in Python, which is useful once the number of cutoffs becomes large.

Common Pitfalls

The most common mistake is treating Prophet cross-validation like random k-fold validation. Time series must respect temporal order.

Another issue is choosing an initial window that is too short. If the model has yearly seasonality but the first training fold does not contain a full year, the diagnostic result can be misleading.

Developers also misread the output by assuming each row is an independent fold summary. It is not. df_cv contains per-prediction rows, and metrics are computed afterward.

Finally, cross-validation can be expensive. Every cutoff refits the model, so reduce the number of cutoffs if diagnostics are taking too long.

Summary

• Prophet cross-validation is rolling historical backtesting, not random-fold validation.
• 'horizon is forecast distance, initial is the first training window, and period controls cutoff spacing.'
• The output rows show out-of-sample predictions tied to specific cutoff dates.
• Use performance_metrics to summarize forecast accuracy and interval quality.
• Choose validation windows that reflect the real forecasting horizon and seasonality in your problem.