README.md

# Demand Prediction System for E-commerce

A complete machine learning and time-series forecasting system for predicting product demand (sales quantity) in e-commerce. Compares both supervised learning regression models and time-series models (ARIMA, Prophet) to find the best approach.

## 📋 Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Project Structure](#project-structure)
- [Installation](#installation)
- [Dataset](#dataset)
- [Usage](#usage)
- [Model Details](#model-details)
- [Evaluation Metrics](#evaluation-metrics)
- [Visualizations](#visualizations)
- [Example Predictions](#example-predictions)
- [Technical Details](#technical-details)

## 🎯 Overview

This project implements a demand prediction system that uses historical sales data to forecast future product demand. The system compares two approaches:

1. **Machine Learning Models**: Treat demand prediction as a regression problem using product features (price, discount, category, date features)
2. **Time-Series Models**: Treat demand prediction as a time-series problem using historical patterns (ARIMA, Prophet)

The system automatically selects the best performing model across both approaches.

**Key Capabilities:**
- Predicts sales quantity for products on future dates (ML models)
- Predicts overall daily demand (Time-series models)
- Handles temporal patterns and seasonality
- Considers price, discount, category, and date features (ML models)
- Captures time-series patterns and trends (Time-series models)
- Automatically selects the best model from multiple candidates
- Provides comprehensive evaluation metrics
- Compares ML vs Time-Series approaches

## ✨ Features

- **Data Preprocessing**: Automatic handling of missing values, date feature extraction
- **Feature Engineering**: 
  - Date features (day, month, day_of_week, weekend, year, quarter)
  - Categorical encoding (product_id, category)

  - Feature scaling

- **Multiple Models**: 

  - **Machine Learning Models:**

    - Linear Regression

    - Random Forest Regressor

    - XGBoost Regressor (optional)

  - **Time-Series Models:**

    - ARIMA (AutoRegressive Integrated Moving Average)

    - Prophet (Facebook's time-series forecasting tool)

- **Model Selection**: Automatic best model selection based on R2 score

- **Evaluation Metrics**: MAE, RMSE, and R2 Score

- **Visualizations**: 

  - Demand trends over time

  - Monthly average demand

  - Feature importance

  - Model comparison

- **Model Persistence**: Save and load trained models using joblib

- **Future Predictions**: Predict demand for any product on any future date



## 📁 Project Structure



```

demand_prediction/
│
├── data/
│   └── sales.csv                    # Sales dataset
│
├── models/                          # Generated during training
│   ├── best_model.joblib           # Best ML model (if ML is best)

│   ├── best_timeseries_model.joblib # Best time-series model (if TS is best)

│   ├── preprocessing.joblib        # Encoders and scaler (for ML models)

│   ├── model_metadata.json         # Model metadata (legacy)
│   └── all_models_metadata.json    # All models comparison metadata
│
├── plots/                           # Generated during training
│   ├── demand_trends.png           # Time series plot

│   ├── monthly_demand.png          # Monthly averages
│   ├── feature_importance.png      # Feature importance (ML models)

│   ├── model_comparison.png        # Model metrics comparison (all models)
│   └── timeseries_predictions.png  # Time-series model predictions

│

├── generate_dataset.py             # Script to generate synthetic dataset
├── train_model.py                  # Main training script

├── predict.py                      # Prediction script

├── app.py                          # Streamlit dashboard (interactive web app)

├── requirements.txt                # Python dependencies

└── README.md                       # This file

```



## 🚀 Installation



### Prerequisites



- Python 3.8 or higher

- pip (Python package manager)



### Step 1: Navigate to Project Directory



```bash

cd demand_prediction
```



### Step 2: Create Virtual Environment (Recommended)



**Why use a virtual environment?**

- Keeps project dependencies isolated from your system Python

- Prevents conflicts with other projects

- Makes it easier to manage package versions

- Best practice for Python projects



**Quick Setup (Recommended):**



**Windows:**

```bash

setup_env.bat

```

**Linux/Mac:**
```bash

chmod +x setup_env.sh

./setup_env.sh

```

**Manual Setup:**

**Windows:**
```bash

python -m venv venv

venv\Scripts\activate

```

**Linux/Mac:**
```bash

python3 -m venv venv

source venv/bin/activate

```

After activation, you should see `(venv)` in your terminal prompt.

**To deactivate later:**
```bash

deactivate

```

### Step 3: Install Dependencies

```bash

pip install -r requirements.txt

```

**Note**: If you don't want to use XGBoost, you can remove it from `requirements.txt`. The system will work fine without it, just skipping XGBoost model training.

**Alternative (without virtual environment):**
If you prefer not to use a virtual environment, you can install directly:
```bash

pip install -r requirements.txt

```
However, this is **not recommended** as it may cause conflicts with other Python projects.

### Step 4: Generate Dataset

If you don't have a dataset, generate a synthetic one:

```bash

python generate_dataset.py

```

This will create `data/sales.csv` with realistic e-commerce sales data.

## 📊 Dataset

The dataset should contain the following columns:

- **product_id**: Unique identifier for each product (integer)

- **date**: Date of sale (YYYY-MM-DD format)

- **price**: Product price (float)

- **discount**: Discount percentage (0-100, float)

- **category**: Product category (string)

- **sales_quantity**: Target variable - number of units sold (integer)

### Dataset Format Example

```csv

product_id,date,price,discount,category,sales_quantity

1,2020-01-01,499.99,10,Electronics,45

2,2020-01-01,29.99,0,Clothing,120

...

```

## 💻 Usage

### Step 1: Train the Model

Train the model using the sales dataset:

```bash

python train_model.py

```

This will:
1. Load and preprocess the data
2. Extract features from dates
3. Encode categorical variables
4. Train multiple ML models (Linear Regression, Random Forest, XGBoost)
5. Prepare time-series data (aggregate daily sales)
6. Train time-series models (ARIMA, Prophet)
7. Evaluate each model using MAE, RMSE, and R2 Score
8. Compare ML vs Time-Series models
9. Select the best model automatically (across all model types)
10. Save the model and preprocessing objects
11. Generate visualizations

**Output:**
- Best model saved to `models/best_model.joblib` (ML) or `models/best_timeseries_model.joblib` (TS)
- Preprocessing objects saved to `models/preprocessing.joblib` (for ML models)
- Visualizations saved to `plots/` directory
- All models metadata saved to `models/all_models_metadata.json`

### Step 2: Make Predictions

**For ML Models (product-specific predictions):**

Predict demand for a specific product on a date:

```bash

python predict.py --product_id 1 --date 2024-01-15 --price 100 --discount 10 --category Electronics

```

**Parameters for ML Models:**
- `--product_id`: Product ID (integer, required)
- `--date`: Date in YYYY-MM-DD format (required)
- `--price`: Product price (float, required)
- `--discount`: Discount percentage 0-100 (float, default: 0)
- `--category`: Product category (string, required)
- `--model_type`: Model type - `auto` (default), `ml`, or `timeseries`

**For Time-Series Models (overall daily demand):**

Predict total daily demand across all products:

```bash

python predict.py --date 2024-01-15 --model_type timeseries

```

**Parameters for Time-Series Models:**
- `--date`: Date in YYYY-MM-DD format (required)
- `--model_type`: Set to `timeseries` to use time-series models

**Example Predictions:**

```bash

# ML Model - Electronics product with discount

python predict.py --product_id 1 --date 2024-06-15 --price 500 --discount 20 --category Electronics



# ML Model - Clothing product without discount

python predict.py --product_id 5 --date 2024-12-25 --price 50 --discount 0 --category Clothing



# Time-Series Model - Overall daily demand

python predict.py --date 2024-07-06 --model_type timeseries



# Auto-detect best model (default)

python predict.py --product_id 10 --date 2024-07-06 --price 75 --discount 15 --category Sports

```

### Step 3: Launch Interactive Dashboard (Optional)

Launch the Streamlit dashboard for interactive visualization and predictions:

```bash

streamlit run app.py

```

The dashboard will open in your default web browser (usually at `http://localhost:8501`).

**Dashboard Features:**

1. **📈 Sales Trends Page**
   - Interactive filters (category, product, date range)
   - Daily sales trends visualization
   - Monthly sales trends
   - Category-wise analysis
   - Price vs demand relationship
   - Real-time statistics and metrics

2. **🔮 Demand Prediction Page**
   - Interactive prediction interface
   - Select model type (Auto/ML/Time-Series)
   - For ML models:
     - Product selection dropdown
     - Category selection
     - Price and discount sliders
     - Date picker
     - Product statistics display
   - For Time-Series models:
     - Date picker for future predictions
     - Overall daily demand forecast
   - Prediction insights and recommendations

3. **📊 Model Comparison Page**
   - Side-by-side model performance comparison
   - MAE, RMSE, and R2 Score metrics
   - Visual charts comparing all models
   - Best model highlighting
   - Model type indicators (ML vs Time-Series)

**Dashboard Screenshots:**
- Interactive widgets for easy data exploration
- Real-time predictions with visual feedback
- Comprehensive model comparison charts

## 🤖 Model Details

### Models Trained

1. **Linear Regression**
   - Simple linear model
   - Fast training and prediction
   - Good baseline model

2. **Random Forest Regressor**
   - Ensemble of decision trees
   - Handles non-linear relationships
   - Provides feature importance
   - Hyperparameters:
     - n_estimators: 100

     - max_depth: 15
     - min_samples_split: 5
     - min_samples_leaf: 2

3. **XGBoost Regressor** (Optional)
   - Gradient boosting algorithm
   - Often provides best performance
   - Handles complex patterns
   - Hyperparameters:
     - n_estimators: 100

     - max_depth: 6
     - learning_rate: 0.1



4. **ARIMA** (AutoRegressive Integrated Moving Average)

   - Classic time-series forecasting model

   - Captures trends and seasonality

   - Automatically selects best order (p, d, q)

   - Works on aggregated daily sales data

   - Uses chronological train/validation split



5. **Prophet** (Facebook's Time-Series Forecasting)

   - Designed for business time series

   - Handles seasonality (weekly, yearly)

   - Robust to missing data and outliers

   - Works on aggregated daily sales data

   - Uses chronological train/validation split



### Model Comparison: ML vs Time-Series



**Machine Learning Models:**

- ✅ Predict per-product demand

- ✅ Use product features (price, discount, category)

- ✅ Can handle new products with similar features

- ❌ May not capture long-term temporal patterns as well



**Time-Series Models:**

- ✅ Capture temporal patterns and trends

- ✅ Handle seasonality automatically

- ✅ Good for overall demand forecasting

- ❌ Predict aggregate demand, not per-product

- ❌ Don't use product-specific features



**The system automatically selects the best model based on R2 score across all model types.**



### Feature Engineering



**For ML Models:**



The system extracts the following features from the input data:



**Date Features:**

- `day`: Day of month (1-31)

- `month`: Month (1-12)

- `day_of_week`: Day of week (0=Monday, 6=Sunday)

- `weekend`: Binary indicator (1 if weekend, 0 otherwise)

- `year`: Year

- `quarter`: Quarter of year (1-4)



**Original Features:**

- `product_id`: Encoded as categorical
- `price`: Numerical (scaled)
- `discount`: Numerical (scaled)
- `category`: Encoded as categorical

**Total Features**: 10 features after encoding and scaling

**For Time-Series Models:**

- Data is aggregated by date (total daily sales)
- Uses chronological split (80% train, 20% validation)
- Prophet automatically handles:
  - Weekly seasonality
  - Yearly seasonality
  - Trend components

## 📈 Evaluation Metrics

The system evaluates models using three metrics:

1. **MAE (Mean Absolute Error)**
   - Average absolute difference between predicted and actual values
   - Lower is better
   - Units: same as target variable (sales quantity)

2. **RMSE (Root Mean Squared Error)**
   - Square root of average squared differences
   - Penalizes large errors more than MAE
   - Lower is better
   - Units: same as target variable (sales quantity)

3. **R2 Score (Coefficient of Determination)**
   - Proportion of variance explained by the model
   - Range: -∞ to 1 (1 is perfect prediction)
   - Higher is better
   - Used for model selection

**Model Selection**: The model with the highest R2 score is selected as the best model.

## 📊 Visualizations

The training script generates several visualizations:

1. **Demand Trends Over Time** (`plots/demand_trends.png`)
   - Shows total daily sales quantity over the entire time period
   - Helps identify overall trends and patterns

2. **Monthly Average Demand** (`plots/monthly_demand.png`)
   - Bar chart showing average sales by month
   - Reveals seasonal patterns (e.g., holiday season spikes)

3. **Feature Importance** (`plots/feature_importance.png`)
   - Shows which features are most important for predictions
   - Only available for tree-based models (Random Forest, XGBoost)

4. **Model Comparison** (`plots/model_comparison.png`)
   - Side-by-side comparison of all models (ML and Time-Series)
   - Color-coded: ML models (blue) vs Time-Series models (orange/red)
   - Shows MAE, RMSE, and R2 Score for each model

5. **Time-Series Predictions** (`plots/timeseries_predictions.png`)
   - Actual vs predicted plots for ARIMA and Prophet models
   - Shows how well time-series models capture temporal patterns
   - Only generated if time-series models are available

## 🔮 Example Predictions

Here are some example predictions to demonstrate the system:

```bash

# Example 1: Electronics on a weekday

python predict.py --product_id 1 --date 2024-03-15 --price 500 --discount 10 --category Electronics

# Expected: Moderate demand (weekday, some discount)



# Example 2: Clothing on weekend

python predict.py --product_id 5 --date 2024-07-06 --price 50 --discount 20 --category Clothing

# Expected: Higher demand (weekend, good discount)



# Example 3: Holiday season prediction

python predict.py --product_id 10 --date 2024-12-20 --price 100 --discount 25 --category Toys

# Expected: High demand (holiday season, good discount)

```

## 🔧 Technical Details

### Data Preprocessing Pipeline

1. **Date Conversion**: Convert date strings to datetime objects
2. **Feature Extraction**: Extract temporal features from dates
3. **Missing Value Handling**: Fill missing values with median (if any)
4. **Categorical Encoding**: Label encode product_id and category

5. **Feature Scaling**: Standardize numerical features using StandardScaler



### Model Training Pipeline



1. **Data Splitting**: 80% training, 20% validation

2. **Model Training**: Train all available models

3. **Evaluation**: Calculate MAE, RMSE, and R2 for each model

4. **Selection**: Choose model with highest R2 score

5. **Persistence**: Save model, encoders, and scaler



### Prediction Pipeline



1. **Load Model**: Load trained model and preprocessing objects

2. **Feature Preparation**: Extract features from input parameters

3. **Encoding**: Encode categorical variables using saved encoders

4. **Scaling**: Scale features using saved scaler

5. **Prediction**: Make prediction using loaded model

6. **Post-processing**: Ensure non-negative predictions



### Handling Unseen Data



The prediction script handles cases where:

- Product ID was not seen during training (uses default encoding)

- Category was not seen during training (uses default encoding)



Warnings are displayed in such cases.



## 🎓 Learning Points



This project demonstrates:



1. **Supervised Learning**: Regression problem solving

2. **Feature Engineering**: Creating meaningful features from raw data

3. **Model Comparison**: Training and evaluating multiple models

4. **Model Selection**: Automatic best model selection

5. **Model Persistence**: Saving and loading trained models

6. **Production-Ready Code**: Clean, modular, well-documented code

7. **Time Series Features**: Extracting temporal patterns

8. **Categorical Encoding**: Handling categorical variables

9. **Feature Scaling**: Normalizing features for better performance

10. **Evaluation Metrics**: Understanding different regression metrics



## 🐛 Troubleshooting



### Issue: "Model not found"

**Solution**: Run `python train_model.py` first to train and save the model.

### Issue: "XGBoost not available"
**Solution**: Install XGBoost with `pip install xgboost`, or the system will work without it (skipping XGBoost model).

### Issue: "Category not seen during training"
**Solution**: This is handled automatically with a warning. The system uses a default encoding.

### Issue: Poor prediction accuracy
**Solutions**:
- Ensure you have sufficient training data
- Check that input features are in the same range as training data
- Try retraining with different hyperparameters
- Consider adding more features or more training data

## 📝 Notes

- The synthetic dataset generator creates realistic patterns including:
  - Weekend effects (higher sales on weekends)
  - Seasonal patterns (holiday season spikes)
  - Price and discount effects
  - Category-specific base prices

- For production use, consider:
  - Using real historical data
  - Retraining models periodically
  - Adding more features (promotions, weather, etc.)
  - Implementing model versioning
  - Adding prediction confidence intervals

## 📄 License

This project is provided as-is for educational purposes.

## 👤 Author

Created as a complete machine learning project demonstrating demand prediction for e-commerce.

---

**Happy Predicting! 🚀**