algo-forecast-prophet

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Prophet Forecasting

Prophet预测

Overview

概述

Prophet (Meta) decomposes time series into trend + seasonality + holidays + error. Uses an additive (or multiplicative) model fitted with Stan. Handles missing data, outliers, and holiday effects natively. Designed for business time series at daily/weekly granularity.

Prophet（Meta）将时间序列分解为趋势+季节性+节假日+误差项。采用由Stan拟合的加法（或乘法）模型。原生支持缺失数据、异常值和节假日效应处理。专为日/周粒度的业务时间序列设计。

When to Use

适用场景

Trigger conditions:

Forecasting business metrics (sales, traffic, engagement) at daily/weekly frequency
Data with strong seasonal patterns and known holiday effects
Need quick, reasonable forecasts without deep time series expertise

When NOT to use:

For high-frequency data (sub-hourly) — Prophet is designed for daily+
When you need causal/explanatory models (Prophet is descriptive)
For very short time series (< 2 seasonal cycles)

触发场景：

对日/周频率的业务指标（销售额、流量、用户参与度）进行预测
数据具有明显季节性模式且存在已知节假日效应
无需深入的时间序列专业知识，即可快速获取合理预测结果

不适用场景：

高频数据（亚小时级）——Prophet专为日级及以上粒度设计
需要因果/解释性模型的场景（Prophet是描述性模型）
极短时间序列（少于2个完整季节周期）

Algorithm

算法原理

IRON LAW: Prophet Is an Additive Regression Model, NOT Classical Time Series
y(t) = g(t) + s(t) + h(t) + ε(t)
- g(t): piecewise linear or logistic trend with automatic changepoints
- s(t): Fourier series for yearly/weekly/daily seasonality
- h(t): user-specified holiday effects
Prophet does NOT model autocorrelation in residuals. If residuals are
autocorrelated, the uncertainty intervals will be too narrow.

IRON LAW: Prophet Is an Additive Regression Model, NOT Classical Time Series
y(t) = g(t) + s(t) + h(t) + ε(t)
- g(t): piecewise linear or logistic trend with automatic changepoints
- s(t): Fourier series for yearly/weekly/daily seasonality
- h(t): user-specified holiday effects
Prophet does NOT model autocorrelation in residuals. If residuals are
autocorrelated, the uncertainty intervals will be too narrow.

Phase 1: Input Validation

阶段1：输入验证

Prepare DataFrame with columns: ds (datestamp), y (metric). Add regressor columns if available. Specify: country holidays, custom holidays, growth type. Gate: Data formatted, minimum 2 full seasonal cycles.

准备包含ds（日期戳）、y（指标）列的DataFrame。若有可用数据，可添加回归变量列。指定：国家节假日、自定义节假日、增长类型。 准入条件： 数据格式正确，至少包含2个完整的季节周期。

Phase 2: Core Algorithm

阶段2：核心算法

Choose growth model: 'linear' (default) or 'logistic' (with cap and floor)
Set seasonality: yearly (default), weekly (default), custom (e.g., monthly)
Add holidays: country built-ins + custom events (promotions, launches)
Fit model:
```
m = Prophet(); m.fit(df)
```
Generate future DataFrame and predict:
```
m.predict(future)
```

选择增长模型：'linear'（默认）或'logistic'（需设置上限与下限）
设置季节性：年度（默认）、周度（默认）、自定义（如月度）
添加节假日：内置国家节假日 + 自定义事件（促销、产品发布等）
拟合模型：
```
m = Prophet(); m.fit(df)
```
生成未来DataFrame并预测：
```
m.predict(future)
```

Phase 3: Verification

阶段3：结果验证

Check: forecast components (trend, seasonality, holidays) are intuitive. Cross-validate: use Prophet's built-in

cross_validation()

with rolling windows. Evaluate MAPE, RMSE. Gate: MAPE acceptable for use case, components pass visual inspection.

检查：预测分解组件（趋势、季节性、节假日效应）符合直觉。交叉验证：使用Prophet内置的

cross_validation()

进行滚动窗口验证。评估指标为MAPE、RMSE。 准入条件： MAPE符合业务场景要求，组件通过可视化检查。

Phase 4: Output

阶段4：输出结果

Return forecast with decomposed components.

返回包含分解组件的预测结果。

Output Format

输出格式

json

{
  "forecasts": [{"ds": "2025-04-15", "yhat": 1200, "yhat_lower": 1050, "yhat_upper": 1350}],
  "components": {"trend": "upward_3pct", "yearly_seasonality": "peak_in_december", "weekly_seasonality": "low_on_weekends"},
  "metadata": {"mape": 0.08, "training_days": 730, "forecast_days": 90}
}

json

{
  "forecasts": [{"ds": "2025-04-15", "yhat": 1200, "yhat_lower": 1050, "yhat_upper": 1350}],
  "components": {"trend": "upward_3pct", "yearly_seasonality": "peak_in_december", "weekly_seasonality": "low_on_weekends"},
  "metadata": {"mape": 0.08, "training_days": 730, "forecast_days": 90}
}

Examples

示例

Sample I/O

输入输出样例

Input: 2 years of daily website traffic with Christmas spike and summer dip Expected: Forecast captures: upward trend, weekly pattern (weekday > weekend), annual pattern (Christmas spike, summer dip).

输入： 2年的每日网站流量数据，包含圣诞节峰值与夏季低谷 预期输出： 预测结果需覆盖：上升趋势、周度模式（工作日流量>周末）、年度模式（圣诞节峰值、夏季低谷）。

Edge Cases

边缘场景

Input	Expected	Why
Many missing days	Prophet handles natively	Unlike ARIMA, no imputation needed
Sudden trend change	Changepoint detected automatically	Prophet's key feature vs ARIMA
Multiplicative seasonality	Set seasonality_mode='multiplicative'	When seasonal amplitude grows with trend

输入	预期结果	原因
存在大量缺失日期	Prophet原生支持处理	与ARIMA不同，无需进行插补
趋势突然变化	自动检测到变点	这是Prophet相对ARIMA的核心特性
乘法季节性	设置seasonality_mode='multiplicative'	当季节性幅度随趋势增长时适用

Gotchas

注意事项

Default changepoint sensitivity: Prophet may over/under-detect trend changes. Tune
```
changepoint_prior_scale
```
(default 0.05): higher = more flexible, lower = smoother.
Flat forecasts: If trend changepoints are too conservative, long-range forecasts can be unrealistically flat. Increase flexibility or specify growth cap.
Holiday effects require specification: Prophet doesn't discover holidays automatically. You must provide a holiday DataFrame — missing holidays will not be modeled.
Not for causal inference: Prophet finds patterns but doesn't explain why. Adding a regressor shows correlation, not causation.
Uncertainty intervals: Based on historical trend change variance, not residual autocorrelation. May be too narrow if residuals are structured.

默认变点敏感度：Prophet可能过度/不足检测趋势变化。可调整
```
changepoint_prior_scale
```
（默认值0.05）：值越高，模型灵活性越强；值越低，趋势越平滑。
预测结果扁平化：若趋势变点设置过于保守，长期预测结果可能不切实际地扁平化。可提高模型灵活性或指定增长上限。
节假日效应需手动指定：Prophet不会自动识别节假日。必须提供节假日DataFrame——未指定的节假日将不会被纳入建模。
不支持因果推断：Prophet仅能发现模式，无法解释原因。添加回归变量仅能体现相关性，而非因果关系。
不确定性区间：基于历史趋势变化方差计算，未考虑残差自相关。若残差存在结构化特征，区间可能过窄。

References

参考资料

For Prophet hyperparameter tuning guide, see
```
references/prophet-tuning.md
```
For cross-validation best practices, see
```
references/prophet-cv.md
```

关于Prophet超参数调优指南，请查看
```
references/prophet-tuning.md
```
关于交叉验证最佳实践，请查看
```
references/prophet-cv.md
```