Forecasting methodology¶
Customer-facing summary of how AccuPredix produces forecasts. For full
algorithm detail see model/MODEL_EXPLAINED.md in the repository.
Pipeline overview¶
Orders history → Quality checks → Monthly series → Model competition
→ Walk-forward backtest → Winner forecasts → Conformal bands (P10/P50/P90)
→ Optional hierarchy reconcile → Dashboard & exports
Every product–customer series is forecast independently, then aggregated for portfolio metrics.
Model competition¶
AccuPredix does not force one algorithm on all SKUs. For each series it runs a walk-forward backtest across specialists and picks the lowest-error method.
| Specialist | Best for |
|---|---|
| Seasonal naive | Stable seasonality baseline |
| Moving average | Smooth, low seasonality |
| AutoETS | Clear trend + seasonality |
| Croston / TSB / ADIDA | Intermittent demand (many zero months) |
| LightGBM | Cross-series ML patterns |
| LightGBM + indicators | ML with external macro/sector signals |
| TFT (optional) | Deep model — Agency tier opt-in (FC-002-R) |
You do not choose the model per series unless using Growth+ model override.
Demand personalities¶
Before modelling, each series is classified:
| Personality | Pattern |
|---|---|
| Smooth | Regular, predictable |
| Erratic | Variable but frequent |
| Intermittent | Many zero months |
| Lumpy | Sporadic large orders |
Classification routes intermittent series to Croston-family methods automatically.
Walk-forward backtesting¶
To score fairly, the engine:
- Holds out recent months
- Trains on earlier history only
- Forecasts the held-out period
- Compares to actuals (WAPE)
- Repeats across multiple windows
This prevents “memorising” the past and inflating accuracy.
Uncertainty bands (P10 / P50 / P90)¶
Quantiles are conformal-calibrated from backtest errors:
- P50 (median) — best single estimate
- P10 / P90 — low and high scenarios for planning buffers
Bands widen when history is short or demand is erratic.
Hierarchy reconciliation¶
When product_master includes brand/category tree, forecasts can be
reconciled so SKU totals match category totals (FE-005). Without hierarchy
data, series are independent.
Events and masking¶
Optional events table marks promotions, stockouts, or shutdowns. Training can exclude or down-weight affected months (FC-008) so one-off spikes do not become false trends.
External indicators¶
Growth+ orgs can attach industry indicators (CPI, PMI, commodity prices) from the External Data Catalogue. LightGBM variants may use these as features when history supports it.
Overrides vs scenarios¶
| Mechanism | Persists | Retrains |
|---|---|---|
| Override | Yes — stored per run/series | No |
| Scenario preview | No — compute on read | No |
| New run | Yes — new model fit | Yes |
Official numbers for S&OP should come from an approved run plus documented overrides.
Accuracy metrics¶
| Metric | Meaning |
|---|---|
| WAPE | Weighted absolute % error — lower is better (technical view) |
| Accuracy score | 0–100 derived from WAPE (simple view) |
| Bias | Systematic over/under-forecast direction |
| Data drift | Rising WAPE slope over recent runs (RM-003, Growth+) |
Data requirements¶
Minimum: 4 columns on orders (customer_id, product_id, order_date,
ordered_qty). 24+ months history recommended for seasonality. See
Upload data.
Limitations (set expectations)¶
- Default grain is monthly — not daily POS forecasting (see roadmap RM-008)
- New products use cold-start priors until history accumulates
- Price elasticity and promo uplift are on the roadmap, not automatic today
- Forecasts reflect uploaded history — garbage in, garbage out