demand-forecasting-engine

Multi-method demand forecasting toolkit using ARIMA, Prophet, LSTM, and XGBoost for supply chain planning with automated model selection and accuracy benchmarking

Demand Forecasting Engine 📈

Multi-method demand forecasting toolkit for supply chain planning — comparing statistical, ML, and deep learning approaches on real-world demand patterns.

---

Overview

Accurate demand forecasting is the foundation of supply chain planning. Poor forecasts cascade into excess inventory, stockouts, bullwhip effects, and wasted production capacity. This project implements and benchmarks multiple forecasting methods on supply chain demand data, providing a practical framework for selecting the right model for different demand patterns.

The toolkit covers stationary, trended, seasonal, and intermittent demand — the four patterns that account for the majority of real-world SKU behavior.

---

Methods Implemented

Method	Category	Best For
ARIMA / SARIMA	Statistical	Stationary & seasonal patterns
Exponential Smoothing (Holt-Winters)	Statistical	Trend + seasonality
Facebook Prophet	Decomposition	Multiple seasonality + holidays
XGBoost	Machine Learning	Complex nonlinear relationships
LightGBM	Machine Learning	Large-scale, high-cardinality data
LSTM	Deep Learning	Long sequential dependencies
Croston's Method	Specialized	Intermittent / lumpy demand

---

Project Structure

demand-forecasting-engine/
├── data/
│   ├── raw/                    # Raw demand datasets
│   ├── processed/              # Cleaned and feature-engineered data
│   └── sample_demand.csv       # Sample multi-SKU demand dataset
├── notebooks/
│   ├── 01_eda_demand_patterns.ipynb
│   ├── 02_statistical_models.ipynb
│   ├── 03_ml_models.ipynb
│   ├── 04_deep_learning.ipynb
│   └── 05_model_comparison.ipynb
├── src/
│   ├── data_loader.py
│   ├── feature_engineering.py
│   ├── models/
│   │   ├── arima_model.py
│   │   ├── prophet_model.py
│   │   ├── xgboost_model.py
│   │   └── lstm_model.py
│   ├── evaluation.py
│   └── utils.py
├── requirements.txt
├── .gitignore
├── LICENSE
└── README.md

---

Key Features

Automated Model Selection — Runs all methods against the dataset and ranks by MAPE, RMSE, and MAE to identify the best fit.

Demand Classification — Automatically classifies SKUs into demand pattern categories (smooth, erratic, intermittent, lumpy) using the ADI-CV² framework.

Feature Engineering Pipeline — Generates lag features, rolling statistics, calendar features, and promotion flags from raw demand data.

Forecast Reconciliation — Supports hierarchical forecasting to ensure SKU-level forecasts align with category and total-level predictions.

---

Sample Dataset

The included sample dataset (data/sample_demand.csv) contains 3 years of weekly demand data across 50 SKUs with varying demand patterns:

Column	Description
date	Week ending date
sku_id	Product identifier
demand_qty	Units demanded
category	Product category
price	Unit selling price
promotion	Binary promotion flag
lead_time_days	Supplier lead time

---

Evaluation Metrics

All models are evaluated using:

• MAPE — Mean Absolute Percentage Error
• • RMSE — Root Mean Squared Error
  • • MAE — Mean Absolute Error

    • • Bias — Systematic over/under-forecasting detection

      • • Forecast Value Added (FVA) — Improvement over naive baseline

        ---

        Getting Started

        # Clone the repository
        git clone https://github.com/virbahu/demand-forecasting-engine.git
        cd demand-forecasting-engine
        
        # Install dependencies
        pip install -r requirements.txt
        
        # Run the EDA notebook
        jupyter notebook notebooks/01_eda_demand_patterns.ipynb

        ---

        Requirements

        pandas>=2.0
        numpy>=1.24
        scikit-learn>=1.3
        statsmodels>=0.14
        prophet>=1.1
        xgboost>=2.0
        lightgbm>=4.0
        tensorflow>=2.15
        matplotlib>=3.7
        plotly>=5.18
        

        ---

        Use Cases

        • Retail — Weekly SKU-level demand planning with promotional lift
        • • Manufacturing — Monthly production planning with seasonal adjustments

          • • Distribution — Daily warehouse replenishment forecasting

            • • Procurement — Quarterly raw material demand estimation

              ---

              References

              • Hyndman, R.J., & Athanasopoulos, G. — Forecasting: Principles and Practice

              • • Syntetos, A.A., & Boylan, J.E. — Intermittent Demand Forecasting

                • • Makridakis, S. et al. — The M5 Competition

                  ---

                  About Quantisage

                  Quantisage builds AI-powered supply chain solutions for regulated and performance-driven industries. This project is part of our open-source initiative to advance supply chain analytics.

                  License

                  MIT License — see LICENSE for details.