📈 Demand Forecasting with Advanced Machine Learning

🇬🇧 English Version

---

🎯 Overview

This project presents a production-grade demand forecasting system for retail store sales using advanced machine learning techniques. Developed as a comprehensive research initiative, it addresses the critical challenge of accurate demand prediction with proper time series methodology.

Research Objectives:

1. Develop a robust forecasting model with minimal prediction error
2. Prevent data leakage in time series cross-validation
3. Ensure model interpretability through SHAP analysis
4. Quantify business impact with asymmetric cost functions
5. Create a scalable, production-ready solution

Dataset: Kaggle Store Sales - Time Series Forecasting (3M+ transactions, 54 stores, 33 product families)

---

✨ Key Features

🔬 Advanced Feature Engineering

• Lag Features: sales_lag_16 to sales_lag_30 (respecting 16-day forecast horizon)
• Rolling Statistics: 7, 14, 28-day windows for mean, std, min, max
• Calendar Features: Day of week, month, year, weekend, payday detection
• External Features: Oil prices, holidays, promotions
• Store & Product Encoding: Target encoding with smoothing
• 50+ engineered features from 6 original variables

🤖 State-of-the-Art ML Pipeline

• XGBoost with Optuna hyperparameter optimization (30 trials)
• LightGBM for model comparison
• Prophet for time series baseline
• SARIMA for statistical baseline
• GroupTimeSeriesSplit: Custom CV respecting temporal & group structure

📊 Comprehensive Evaluation

• Multiple metrics: RMSLE, RMSE, MAE, MAPE
• Naive baselines: Seasonal naive, Moving average
• Diebold-Mariano test for statistical significance
• Error analysis by forecast horizon (1-16 days)

🔍 Model Interpretability (XAI)

• SHAP (SHapley Additive exPlanations) values via XGBoost native API
• Feature importance ranking with business interpretation
• Promotion effect quantification (+45% average lift)
• Oil price correlation analysis

💼 Business Impact Analysis

• Asymmetric cost function (stockout 1.5x vs overstock 0.3x)
• Bias correction optimization (+14% optimal adjustment)
• Annual savings projections
• Revenue impact quantification

---

📈 Results & Performance

Metric	Value	Baseline	Improvement
RMSLE	0.1235	0.2694	✅ 54.2% better
RMSE	245.3	534.1	✅ 54.1% better
MAE	112.7	298.4	✅ 62.2% better
Business Cost	6.32%	10.44%	✅ 39.5% reduction

💰 Business Metrics

• Baseline Cost: $13.13M (10.44% of revenue)
• Optimized Cost: $7.94M (6.32% of revenue)
• Annual Savings: $5.19M
• ROI: 39.5%

Comparison with Baselines:

• 54% better than Seasonal Naive (RMSLE: 0.12 vs 0.27)
• 48% better than Moving Average baseline
• Statistically significant (Diebold-Mariano p < 0.001)

---

🛠️ Technology Stack

Category	Technologies
ML Models	XGBoost, LightGBM, Prophet, SARIMA
Optimization	Optuna (TPE sampler, 30 trials)
Interpretability	SHAP (native XGBoost integration)
Visualization	Matplotlib, Seaborn, Plotly
Data Processing	Pandas, NumPy, Scikit-learn
Statistical Tests	Statsmodels, Diebold-Mariano

---

🚀 Quick Start

# Clone repository
git clone https://github.com/yourusername/demand-forecasting.git
cd demand-forecasting

# Install dependencies
pip install pandas numpy scikit-learn xgboost lightgbm prophet statsmodels shap optuna matplotlib seaborn

# Download data from Kaggle
kaggle competitions download -c store-sales-time-series-forecasting
unzip store-sales-time-series-forecasting.zip -d data/

# Run notebook
jupyter notebook demand_forecasting.ipynb

---

📁 Project Structure

Demand Forecasting/
├── demand_forecasting.ipynb   # Main notebook (79 cells)
├── data/                      # Kaggle dataset
│   ├── train.csv              # 3M+ training samples
│   ├── test.csv               # Test set
│   ├── stores.csv             # Store metadata
│   ├── oil.csv                # Daily oil prices
│   ├── holidays_events.csv    # Ecuador holidays
│   └── transactions.csv       # Daily transactions
└── README.md

---

💡 Key Insights

1. Lag features dominate: sales_lag_16 is the strongest predictor
2. Weekly seasonality is strong: Day of week in top-5 features
3. Promotions boost sales: +45% average lift, critical for forecasting
4. Oil prices matter: Ecuador's economy correlates with retail demand
5. Bias correction is crucial: Asymmetric costs require deliberate over-forecasting

---

🇷🇺 Русская Версия

---

🎯 Обзор

Данный проект представляет собой production-ready систему прогнозирования спроса для розничных продаж с использованием передовых методов машинного обучения. Разработанный как комплексное исследование, он решает критическую задачу точного прогнозирования спроса с корректной методологией временных рядов.

Цели исследования:

1. Разработать надёжную модель прогнозирования с минимальной ошибкой
2. Предотвратить утечку данных в кросс-валидации временных рядов
3. Обеспечить интерпретируемость модели через SHAP-анализ
4. Количественно оценить бизнес-влияние с асимметричными функциями потерь
5. Создать масштабируемое решение, готовое к внедрению

Набор данных: Kaggle Store Sales - Time Series Forecasting (3M+ транзакций, 54 магазина, 33 категории товаров)

---

✨ Ключевые особенности

🔬 Продвинутый Feature Engineering

• Лаговые признаки: sales_lag_16 до sales_lag_30 (с учётом 16-дневного горизонта прогноза)
• Скользящая статистика: окна 7, 14, 28 дней для среднего, std, min, max
• Календарные признаки: день недели, месяц, год, выходные, день зарплаты
• Внешние признаки: цены на нефть, праздники, промоакции
• Кодирование магазинов и продуктов: Target encoding со сглаживанием
• 50+ созданных признаков из 6 исходных переменных

🤖 Современный ML-конвейер

• XGBoost с оптимизацией гиперпараметров Optuna (30 итераций)
• LightGBM для сравнения моделей
• Prophet как baseline временных рядов
• SARIMA как статистический baseline
• GroupTimeSeriesSplit: кастомная CV с учётом временной и групповой структуры

📊 Комплексная оценка

• Множественные метрики: RMSLE, RMSE, MAE, MAPE
• Наивные baselines: Seasonal naive, Moving average
• Тест Дибольда-Мариано для статистической значимости
• Анализ ошибки по горизонту прогноза (1-16 дней)

🔍 Интерпретируемость модели (XAI)

• SHAP значения через нативный API XGBoost
• Ранжирование важности признаков с бизнес-интерпретацией
• Количественная оценка эффекта промоакций (+45% средний подъём)
• Анализ корреляции с ценами на нефть

💼 Анализ бизнес-влияния

• Асимметричная функция потерь (дефицит 1.5x vs избыток 0.3x)
• Оптимизация коррекции смещения (+14% оптимальная корректировка)
• Прогнозы годовой экономии
• Количественная оценка влияния на выручку

---

📈 Результаты и производительность

Метрика	Значение	Baseline	Улучшение
RMSLE	0.1235	0.2694	✅ 54.2% лучше
RMSE	245.3	534.1	✅ 54.1% лучше
MAE	112.7	298.4	✅ 62.2% лучше
Бизнес-стоимость	6.32%	10.44%	✅ 39.5% снижение

💰 Бизнес-метрики

• Базовые потери: $13.13M (10.44% от выручки)
• Оптимизированные потери: $7.94M (6.32% от выручки)
• Годовая экономия: $5.19M
• ROI: 39.5%

Сравнение с baselines:

• На 54% лучше Seasonal Naive (RMSLE: 0.12 vs 0.27)
• На 48% лучше Moving Average baseline
• Статистически значимо (Дибольд-Мариано p < 0.001)

---

🛠️ Технологический стек

Категория	Технологии
ML модели	XGBoost, LightGBM, Prophet, SARIMA
Оптимизация	Optuna (TPE sampler, 30 итераций)
Интерпретируемость	SHAP (нативная интеграция XGBoost)
Визуализация	Matplotlib, Seaborn, Plotly
Обработка данных	Pandas, NumPy, Scikit-learn
Статистические тесты	Statsmodels, Diebold-Mariano

---

🚀 Быстрый старт

# Клонировать репозиторий
git clone https://github.com/yourusername/demand-forecasting.git
cd demand-forecasting

# Установить зависимости
pip install pandas numpy scikit-learn xgboost lightgbm prophet statsmodels shap optuna matplotlib seaborn

# Скачать данные с Kaggle
kaggle competitions download -c store-sales-time-series-forecasting
unzip store-sales-time-series-forecasting.zip -d data/

# Запустить ноутбук
jupyter notebook demand_forecasting.ipynb

---

📁 Структура проекта

Demand Forecasting/
├── demand_forecasting.ipynb   # Основной ноутбук (79 ячеек)
├── data/                      # Данные Kaggle
│   ├── train.csv              # 3M+ обучающих примеров
│   ├── test.csv               # Тестовый набор
│   ├── stores.csv             # Метаданные магазинов
│   ├── oil.csv                # Дневные цены на нефть
│   ├── holidays_events.csv    # Праздники Эквадора
│   └── transactions.csv       # Дневные транзакции
└── README.md

---

💡 Ключевые инсайты

1. Лаговые признаки доминируют: sales_lag_16 — сильнейший предиктор
2. Сильная недельная сезонность: день недели в топ-5 признаков
3. Промоакции увеличивают продажи: +45% средний рост, критично для прогноза
4. Цены на нефть важны: экономика Эквадора коррелирует с розничным спросом
5. Коррекция смещения критична: асимметричные потери требуют намеренного завышения прогноза

---

Made by ispromashka!