Prophet Forecasting

Facebook Prophet — interpretable time series forecasting with full hyperparameter control

---

Overview

• ID: prophet-forecasting
• Type: Time series forecasting (single-column)
• Framework: Facebook Prophet (pystan backend)
• Best for: Daily/weekly/yearly seasonal patterns, business time series with holidays, interpretable trend+seasonality decomposition
• Training time: 1-5 minutes (CPU — no GPU needed)
• GPU required: No

For deep-learning forecasting with quantile predictions, see TimesFM 2.5. For automatic model selection across Prophet/ARIMA/ETS for multi-column datasets, see Classical Forecasting.

---

When to Use

Prophet is the right choice when:

• You need interpretable components (trend + seasonality + holidays)
• Your data has strong weekly, yearly, or holiday effects (retail, web traffic, energy)
• You want calibrated uncertainty intervals (yhat_lower / yhat_upper)
• You want fine-grained control over changepoints, growth model, and seasonality
• No GPU is available

Not ideal for:

• High-frequency tick data (millisecond/second level) — use TimesFM 2.5
• Very short series (fewer than 50 points)
• Multi-column forecasting — use classical-forecasting-auto instead
• Sub-daily data with no meaningful daily pattern

---

Quick Start

from colabhive import ColabHive

client = ColabHive(api_key="...", account_id="...")

dataset = client.datasets.upload("sales_ts", "./sales.csv")

job = client.training.create(
    model="prophet-forecasting",
    dataset_id=dataset.id,
    hyperparameters={
        "target_column": "sales",
        "date_column": "date",
        "horizon_len": 30,
        "frequency": "D",
    }
)

job.wait()

endpoint = client.training.register_for_inference(
    run_id=job.id,
    name="sales-prophet",
    description="Prophet sales forecast",
    visibility="account",
)

result = client.endpoints.infer(
    endpoint_id=endpoint.endpoint_id,
    input_data={"horizon": 30},
)
print(result["task_id"], result["status"])

---

Dataset Format

CSV Format

date,sales,promo,temperature
2024-01-01,1000,0,25.5
2024-01-02,1050,1,26.1
2024-01-03,980,0,24.8

Requirements

• Date column: parseable date/datetime (name it via date_column, default ds)
• Target column: numeric values to forecast (name it via target_column, default y)
• Minimum 50 rows (recommended 200+ for reliable seasonality detection)
• Extra columns can be used as regressors via extra_regressors

---

Hyperparameters

Core

Parameter	Type	Default	Description
target_column	string	"y"	Column to forecast
date_column	string	"ds"	Date/timestamp column
horizon_len	int	30	Steps ahead to predict (1–365)
frequency	string	"D"	Data frequency: D=daily, H=hourly, W=weekly, M=monthly, Q=quarterly

Trend

Parameter	Type	Default	Description
growth	string	"linear"	"linear" (default), "logistic" (saturating), or "flat" (no trend)
changepoint_prior_scale	float	0.05	Trend flexibility. Increase (e.g. 0.3) for more trend changes; decrease (e.g. 0.01) for smoother trend
n_changepoints	int	25	Number of potential changepoints placed in the first changepoint_range of data
changepoint_range	float	0.8	Fraction of training history where changepoints are allowed (default: first 80%)
cap	float	null	Required for logistic growth. Carrying capacity (upper saturation)
floor	float	null	Lower saturation for logistic growth (default: 0)

Seasonality

Parameter	Type	Default	Description
seasonality_mode	string	"additive"	"additive" or "multiplicative". Use multiplicative when seasonal swings scale with the trend level
seasonality_prior_scale	float	10.0	Flexibility of seasonal components. Smaller = smoother seasonality
yearly_seasonality	string	"auto"	"auto", "true", or "false"
weekly_seasonality	string	"auto"	"auto", "true", or "false"
daily_seasonality	string	"false"	Enable for sub-daily (hourly/minutely) data

Holidays & Regressors

Parameter	Type	Default	Description
country_holidays	string	""	ISO country code for built-in holidays (e.g. "US", "DE", "BR", "MX")
holidays_prior_scale	float	10.0	Flexibility of holiday effects
extra_regressors	list	[]	Additional CSV columns to use as regressors (e.g. ["promo", "temperature"])

Uncertainty & Inference

Parameter	Type	Default	Description
interval_width	float	0.8	Width of credible interval (yhat_lower/yhat_upper). 0.80 = 80% CI
mcmc_samples	int	0	0 = MAP estimation (fast). >0 = full Bayesian MCMC (slower, better uncertainty)

---

Inference Response

Each inference call returns a list of forecast records — one per step:

{
  "forecasts": [
    {
      "ds": "2024-02-01",
      "yhat": 1023.4,
      "yhat_lower": 940.2,
      "yhat_upper": 1106.8,
      "trend": 1010.1,
      "weekly": 13.3,
      "yearly": -2.1
    }
  ],
  "horizon": 30,
  "model_type": "Prophet",
  "quantiles": {
    "yhat_lower": [...],
    "yhat_upper": [...],
    "trend": [...],
    "weekly": [...],
    "yearly": [...]
  }
}

Component columns (trend, weekly, yearly, holidays, etc.) are included when the model has them, making it easy to decompose and explain the forecast.

---

Advanced Examples

Logistic Growth (saturating forecast)

Use when your series has a known upper limit (e.g. market share, app installs in a fixed market):

job = client.training.create(
    model="prophet-forecasting",
    dataset_id=dataset.id,
    hyperparameters={
        "target_column": "installs",
        "date_column": "date",
        "horizon_len": 60,
        "growth": "logistic",
        "cap": 500000,       # maximum possible installs
        "floor": 0,
        "changepoint_prior_scale": 0.1,
    }
)

US Holidays + Promotional Regressors

job = client.training.create(
    model="prophet-forecasting",
    dataset_id=dataset.id,
    hyperparameters={
        "target_column": "revenue",
        "date_column": "date",
        "horizon_len": 90,
        "country_holidays": "US",
        "extra_regressors": ["is_promo", "tv_spend"],
        "seasonality_mode": "multiplicative",
        "changepoint_prior_scale": 0.1,
    }
)

Full Bayesian Uncertainty (MCMC)

job = client.training.create(
    model="prophet-forecasting",
    dataset_id=dataset.id,
    hyperparameters={
        "target_column": "sales",
        "date_column": "date",
        "horizon_len": 30,
        "mcmc_samples": 300,     # full Bayesian — slower but better intervals
        "interval_width": 0.95,  # 95% credible interval
    }
)

---

Tips

1. Start with defaults — the defaults are well-calibrated for daily business data
2. Multiplicative seasonality — if your seasonal swings grow with the trend (e.g. percentage-based patterns), set seasonality_mode: multiplicative
3. Overfitting trend — if the trend wiggles too much on future dates, decrease changepoint_prior_scale (try 0.01)
4. Underfitting seasonality — if seasonal patterns are too flat, increase seasonality_prior_scale (try 50.0)
5. Holidays matter — adding country_holidays for retail, e-commerce, or consumer data usually improves accuracy
6. Extra regressors must be known for the future — only add columns whose future values you know at inference time (e.g. is_promo where promotions are planned)
7. MCMC is slow — only use mcmc_samples > 0 when you truly need posterior uncertainty; MAP (mcmc_samples=0) is usually sufficient

---

Comparison with Other Forecasting Models

	Prophet	Classical Auto	TimesFM 2.5
ID	prophet-forecasting	classical-forecasting-auto	timesfm-2.5-finetune-gpu
GPU	No	No	Yes (4GB+)
Multi-column	No (single series)	Yes	No
Interpretable	Yes (components)	Partially	No
Holidays	Yes (built-in)	No	No
Quantile output	Yes (intervals)	No	Yes (q10–q90)
Best for	Seasonal business data	Auto-select across models	Complex/financial patterns

---

Next Steps

• TimesFM 2.5 (Foundation Model) — deep learning with q10–q90 quantiles
• Classical Forecasting (Auto-Selection) — multi-column auto-selection
• All Models