"algo-forecast-prophet"

Prophet Forecasting

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.

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)

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.

Phase 1: Input Validation

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.

Phase 2: Core Algorithm

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

Phase 3: Verification

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.