Machine learning · plan.forecastCI passing

Demand Forecasting

Hierarchical, probabilistic demand forecasts, backtested and turned into stock decisions.

View the code Evaluation report Demo tour Run it ›_ last push 5 days ago

36%less error than seasonal naive at store x product level (28% less than Holt-Winters)

81.8%of actuals inside the 80% interval after conformal calibration (raw quantiles: 72.0%)

-51%stock cost ordering at the 80th percentile instead of a seasonal-naive forecast

Backtest report: error by hierarchy level for six methods, interval coverage before and after calibration, and costed stock policies. Screenshot from the project's demo (synthetic data).

demo Demo tour

Screenshots from the running application, with its synthetic demo data. Select one to enlarge.

Error at every level of the hierarchy for six methods; the global GBM with bottom-up reconciliation leads everywhere.

Interval coverage before and after conformal calibration, hard cases, and the cost of four stock policies.

01 The problem

Retail forecasts are usually one number per series from a model fitted to that series alone: they miss what other stores learned about promotions, their intervals are overconfident, store and regional plans don't add up, and stock is set from a median that sits below average demand.

02 How it works

Sales history + planned promotions
Global quantile GBM, all levels
Conformal calibration per level
Reconcile so the hierarchy adds up
Order at the 80th percentile
Backtest and cost every block

03 What I built

One global gradient-boosted model for every store, product and level, with features known at the forecast origin and quantile loss for the 10th to 90th percentiles.
Conformal calibration of the intervals on earlier blocks, and bottom-up, WLS and MinT reconciliation so stores add up to regions and the total.
A rolling-origin backtest against seasonal-naive and Holt-Winters, and a stock simulation that costs each ordering policy.

04 What I learned

Bottom-up beat MinT on this chain at every level; reconciliation methods are worth testing, not assuming.

Ordering at the cost-minimising quantile halved stock cost; a better point forecast alone cut a third.

05 Known limitations

Every repository documents what it doesn't do yet. The main ones:

Synthetic sales; promotions assumed known and executed as planned.
Stock is simulated as daily and perishable, without lead times or carry-over.

06 Stack

Pythonscikit-learnNumPyConformal predictionHierarchical reconciliation

The repository has the design document, operations runbook, full evaluation report and known limitations. All data is synthetic, generated by code in the repository.

run Run it yourself

Every project runs on a laptop: no cloud account and no paid API needed.

git clone https://github.com/codeROCK-IZZY/demand-forecasting.git
cd demand-forecasting
pip install -e ".[dev]" && pytest
forecast evaluate --gate              # writes eval/reports/report.html
forecast store 3                      # next four weeks for store 3