Example: Sales Forecasting

End-to-end workflow for forecasting monthly sales using Prophet (CPU, interpretable) and TimesFM 2.5 (GPU, foundation model). Covers dataset prep, training, evaluation, and inference.

Estimated time: 5-15 minutes
Models: prophet-forecasting (no GPU) or timesfm-2.5-finetune-gpu (GPU)
Task: Time series forecasting

---

Dataset

A sales forecasting dataset needs a date column and a numeric target column:

date,sales,promo,temperature
2022-01-01,12500,0,5.2
2022-02-01,11800,0,6.1
2022-03-01,13200,1,9.4
2022-04-01,14500,0,13.7
2022-05-01,15100,1,17.2
2022-06-01,16200,0,21.8
2022-07-01,17800,1,24.1
2022-08-01,17200,0,23.5
2022-09-01,15600,0,19.2
2022-10-01,14100,1,13.8
2022-11-01,18500,1,7.4
2022-12-01,21000,1,4.1

Minimum: 24 data points for ARIMA/Prophet. More is always better.

---

Option A: Prophet (CPU, Interpretable)

Best for: single series with seasonal patterns, holiday effects, or when you need to understand trend decomposition.

Step 1: Upload Dataset

import os
from colabhive import ColabHive

client = ColabHive(
    api_key=os.getenv("COLABHIVE_API_KEY"),
    account_id=os.getenv("COLABHIVE_ACCOUNT_ID"),
    base_url="https://api.colabhive.com",
)

dataset = client.datasets.upload(
    name="monthly_sales",
    file="./sales.csv",
)
print(f"Dataset: {dataset.dataset_id} ({dataset.num_samples} rows)")

Step 2: Train with Prophet

job = client.training.create(
    model="prophet-forecasting",
    dataset_id=dataset.dataset_id,
    job_name="sales-prophet",
    hyperparameters={
        "date_column": "date",
        "target_column": "sales",
        "forecast_horizon": 6,           # Forecast 6 months ahead
        "seasonality_mode": "additive",  # Use "multiplicative" for % growth
        "yearly_seasonality": True,
        "country_holidays": "US",        # Include US public holidays
        "changepoint_prior_scale": 0.05, # Trend flexibility (0.001-0.5)
    },
)

job.wait()
print(f"MAE:  {job.metrics.get('mae', 'N/A')}")
print(f"MAPE: {job.metrics.get('mape', 'N/A')}%")

Expected MAPE: 5-15% on clean monthly sales data.

Step 3: Register and Forecast

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

# Forecast next 6 months
result = client.endpoints.infer(
    endpoint_id=endpoint.endpoint_id,
    input_data={"forecast_horizon": 6},
)

print(result["result"])
# Returns: {"forecast": [{"ds": "2023-01-01", "yhat": 13100, "yhat_lower": 11200, "yhat_upper": 15000}, ...]}

---

Option B: TimesFM 2.5 (GPU, Foundation Model)

Best for: complex patterns, quantile predictions (confidence intervals), or when you have GPU available.

Train with TimesFM 2.5

job = client.training.create(
    model="timesfm-2.5-finetune-gpu",
    dataset_id=dataset.dataset_id,
    job_name="sales-timesfm",
    hyperparameters={
        "date_column": "date",
        "target_column": "sales",
        "forecast_horizon": 6,
        "context_length": 24,   # Use 24 months of history as input
        "epochs": 20,
        "learning_rate": 1e-4,
    },
)

job.wait()
print(f"MAE: {job.metrics.get('mae', 'N/A')}")

TimesFM advantages:

• Returns quantile predictions (p10, p50, p90) for confidence intervals
• Zero-shot forecasting on unseen patterns
• Better on complex, irregular series

---

Full Script (Prophet)

import os
from colabhive import ColabHive

client = ColabHive(
    api_key=os.getenv("COLABHIVE_API_KEY"),
    account_id=os.getenv("COLABHIVE_ACCOUNT_ID"),
    base_url="https://api.colabhive.com",
)

# 1. Upload
dataset = client.datasets.upload("monthly_sales", "./sales.csv")
print(f"Dataset: {dataset.dataset_id}")

# 2. Train
job = client.training.create(
    model="prophet-forecasting",
    dataset_id=dataset.dataset_id,
    job_name="sales-prophet",
    hyperparameters={
        "date_column": "date",
        "target_column": "sales",
        "forecast_horizon": 6,
        "yearly_seasonality": True,
        "country_holidays": "US",
    },
)
job.wait()
print(f"MAPE: {job.metrics.get('mape', 'N/A')}%")

# 3. Register
endpoint = client.training.register_for_inference(
    run_id=job.run_id,
    name="sales-forecast",
    description="Monthly sales forecast",
    visibility="account",
)

# 4. Forecast
result = client.endpoints.infer(
    endpoint_id=endpoint.endpoint_id,
    input_data={"forecast_horizon": 6},
)
print("Forecast:", result["result"])

---

Choosing Between Models

	Prophet	TimesFM 2.5	ARIMA	Classical Auto
GPU needed	No	Yes	No	No
Training time	1-5 min	5-30 min	1-10 min	1-10 min
Confidence intervals	✅ Credible	✅ Quantiles	❌	❌
Holiday support	✅	❌	❌	Partial
Multi-column	❌	✅	❌	✅
Best for	Seasonal, interpretable	Complex patterns, GPU	Statistical, small data	Multi-series, auto

---

Improving Results

If MAPE is high (> 20%):

1. Add more history: Longer time series = better seasonality detection
2. Check for outliers: Remove or cap extreme values before upload
3. Try multiplicative seasonality: If sales have % growth patterns, use "seasonality_mode": "multiplicative"
4. Add regressors: Include promotional flags (promo column) as extra features
5. Switch to TimesFM: Foundation models handle irregular patterns better

---

Next Steps

• Prophet Forecasting Documentation
• TimesFM 2.5 Documentation
• ARIMA Forecasting
• Hyperparameter Tuning — Time Series
• House Price Prediction Example — regression use case