Upload folder using huggingface_hub

README.md

@@ -0,0 +1,132 @@
+---
+license: mit
+tags:
+- tabular-regression
+- demand-forecasting
+- retail
+- islamic-calendar
+- ramadan
+- xgboost
+- sklearn
+- gcc
+library_name: sklearn
+pipeline_tag: tabular-regression
+---
+
+# GCC Ramadan Retail Demand Forecasting Model
+
+An XGBoost Regressor model for predicting retail demand in GCC (Gulf Cooperation Council) countries based on Islamic calendar features.
+
+## Model Description
+
+This model predicts the `demand_index` for retail products in GCC countries (UAE, KSA, Qatar, Kuwait, Bahrain, Oman) across various product categories. The model leverages Islamic calendar features including Ramadan timing, Eid celebrations, and Hajj season to capture the unique seasonal patterns in GCC retail markets.
+
+### Features Used
+
+| Feature | Type | Description |
+|---------|------|-------------|
+| is_ramadan | Binary (0/1) | Whether it is Ramadan |
+| ramadan_week | Integer (0-5) | Week of Ramadan (0 if not Ramadan) |
+| days_to_eid | Integer (-1 to 30) | Days until Eid al-Fitr (-1 if not applicable) |
+| is_eid_fitr | Binary (0/1) | Whether it is Eid al-Fitr |
+| is_eid_adha | Binary (0/1) | Whether it is Eid al-Adha |
+| is_hajj_season | Binary (0/1) | Whether it is Hajj season |
+| country | Categorical | Country (UAE, KSA, Qatar, Kuwait, Bahrain, Oman) |
+| category | Categorical | Product category |
+| temperature | Float | Temperature in Celsius |
+| day_of_week | Integer (0-6) | Day of week (Monday=0) |
+| month | Integer (1-12) | Gregorian month |
+| hijri_month | Integer (1-12) | Hijri month |
+| hijri_day | Integer (1-30) | Hijri day |
+
+### Product Categories
+
+- dates_sweets
+- electronics
+- fashion_abayas
+- gifts
+- groceries
+- perfumes_oud
+
+## Model Performance
+
+| Metric | Value |
+|--------|-------|
+| R2 Score | 0.91 |
+| RMSE | 5.13 |
+| MAE | 3.91 |
+
+### Feature Importance
+
+The top 5 most important features:
+1. **is_hajj_season** (60.7%) - Hajj season is the strongest predictor
+2. **is_eid_adha** (9.9%) - Eid al-Adha celebrations
+3. **days_to_eid** (8.2%) - Proximity to Eid al-Fitr
+4. **ramadan_week** (8.0%) - Week of Ramadan
+5. **category_encoded** (4.4%) - Product category effects
+
+## Usage
+
+```python
+import joblib
+import numpy as np
+
+# Load model and encoders
+model = joblib.load("model.joblib")
+encoders = joblib.load("encoders.joblib")
+country_encoder = encoders['country_encoder']
+category_encoder = encoders['category_encoder']
+
+# Prepare features
+country_encoded = country_encoder.transform(["UAE"])[0]
+category_encoded = category_encoder.transform(["groceries"])[0]
+
+# Feature order: is_ramadan, ramadan_week, days_to_eid, is_eid_fitr, is_eid_adha,
+#                is_hajj_season, country_encoded, category_encoded, temperature,
+#                day_of_week, month, hijri_month, hijri_day
+
+features = np.array([[
+    1,      # is_ramadan
+    2,      # ramadan_week
+    15,     # days_to_eid
+    0,      # is_eid_fitr
+    0,      # is_eid_adha
+    0,      # is_hajj_season
+    country_encoded,
+    category_encoded,
+    30.0,   # temperature
+    4,      # day_of_week (Friday)
+    4,      # month
+    9,      # hijri_month (Ramadan)
+    15      # hijri_day
+]])
+
+prediction = model.predict(features)
+print(f"Predicted demand index: {prediction[0]:.2f}")
+```
+
+## Training Data
+
+The model was trained on a synthetic dataset representing 15+ years of retail demand data from 6 GCC countries across 6 product categories. The dataset captures seasonal patterns associated with:
+- Ramadan shopping behavior
+- Eid al-Fitr celebrations
+- Eid al-Adha celebrations
+- Hajj season
+
+## Limitations
+
+- Model is trained on synthetic data and should be fine-tuned on real retail data before production use
+- Predictions are most accurate within the feature ranges seen during training
+- Country and category must be from the predefined lists
+
+## Files
+
+- `model.joblib` - Trained XGBoost model (sklearn-compatible)
+- `model.json` - XGBoost model in JSON format
+- `encoders.joblib` - Label encoders for country and category
+- `config.json` - Model configuration and metadata
+- `feature_importances.json` - Feature importance scores
+
+## License
+
+MIT License

config.json

@@ -0,0 +1,57 @@
+{
+  "model_type": "GradientBoostingRegressor",
+  "feature_columns": [
+    "is_ramadan",
+    "ramadan_week",
+    "days_to_eid",
+    "is_eid_fitr",
+    "is_eid_adha",
+    "is_hajj_season",
+    "country_encoded",
+    "category_encoded",
+    "temperature",
+    "day_of_week",
+    "month",
+    "hijri_month",
+    "hijri_day"
+  ],
+  "countries": [
+    "Bahrain",
+    "KSA",
+    "Kuwait",
+    "Oman",
+    "Qatar",
+    "UAE"
+  ],
+  "categories": [
+    "dates_sweets",
+    "electronics",
+    "fashion_abayas",
+    "gifts",
+    "groceries",
+    "perfumes_oud"
+  ],
+  "metrics": {
+    "mse": 24.44782802085175,
+    "rmse": 4.944474493902436,
+    "mae": 3.8228789470187383,
+    "r2_score": 0.905699037541998
+  },
+  "description": "GCC Ramadan Retail Demand Forecasting Model",
+  "input_features": {
+    "is_ramadan": "Boolean (0/1) - Whether it is Ramadan",
+    "ramadan_week": "Integer (0-5) - Week of Ramadan (0 if not Ramadan)",
+    "days_to_eid": "Integer (-1 to 30) - Days until Eid (-1 if not applicable)",
+    "is_eid_fitr": "Boolean (0/1) - Whether it is Eid al-Fitr",
+    "is_eid_adha": "Boolean (0/1) - Whether it is Eid al-Adha",
+    "is_hajj_season": "Boolean (0/1) - Whether it is Hajj season",
+    "country": "String - One of: UAE, KSA, Qatar, Kuwait, Bahrain, Oman",
+    "category": "String - Product category",
+    "temperature": "Float - Temperature in Celsius",
+    "day_of_week": "Integer (0-6) - Day of week",
+    "month": "Integer (1-12) - Gregorian month",
+    "hijri_month": "Integer (1-12) - Hijri month",
+    "hijri_day": "Integer (1-30) - Hijri day"
+  },
+  "output": "demand_index - Predicted retail demand index"
+}

encoders.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:da84e6211fe94a186197f3850a18bf6c3aae1f58360000a75f8590b8c5a2cc0a
+size 850

feature_importances.json

@@ -0,0 +1,15 @@
+{
+  "is_ramadan": 3.69275253834204e-05,
+  "ramadan_week": 0.003525943796247472,
+  "days_to_eid": 0.29290416306240935,
+  "is_eid_fitr": 0.0010144082359060686,
+  "is_eid_adha": 0.0012917867230512092,
+  "is_hajj_season": 0.10161264627734466,
+  "country_encoded": 0.11934693744055763,
+  "category_encoded": 0.3920205132356218,
+  "temperature": 0.022141510058809637,
+  "day_of_week": 0.0418962978935297,
+  "month": 0.02049986667570955,
+  "hijri_month": 0.00037238780289487874,
+  "hijri_day": 0.0033366112725345945
+}

inference.py

@@ -0,0 +1,227 @@
+"""
+GCC Ramadan Retail Demand Forecasting - Inference Script
+
+This script demonstrates how to use the trained demand forecasting model.
+When downloaded from HuggingFace, this script works alongside model.joblib and encoders.joblib.
+
+Usage:
+    python inference.py
+
+Or import and use programmatically:
+    from inference import DemandForecaster
+    forecaster = DemandForecaster()
+    prediction = forecaster.predict(...)
+"""
+
+import joblib
+import json
+import numpy as np
+import os
+
+# Get model directory (same directory as this script)
+MODEL_DIR = os.path.dirname(os.path.abspath(__file__))
+
+
+class DemandForecaster:
+    """Class for loading and using the GCC Ramadan demand forecasting model."""
+
+    def __init__(self, model_dir=None):
+        """
+        Initialize the forecaster by loading the model and encoders.
+
+        Args:
+            model_dir: Path to directory containing model files.
+                      Defaults to same directory as this script.
+        """
+        self.model_dir = model_dir or MODEL_DIR
+        self._load_model()
+
+    def _load_model(self):
+        """Load the trained model, encoders, and configuration."""
+        # Load model
+        model_path = os.path.join(self.model_dir, "model.joblib")
+        self.model = joblib.load(model_path)
+
+        # Load encoders
+        encoders_path = os.path.join(self.model_dir, "encoders.joblib")
+        encoders = joblib.load(encoders_path)
+        self.country_encoder = encoders['country_encoder']
+        self.category_encoder = encoders['category_encoder']
+
+        # Load config
+        config_path = os.path.join(self.model_dir, "config.json")
+        with open(config_path, 'r') as f:
+            self.config = json.load(f)
+
+        self.countries = self.config['countries']
+        self.categories = self.config['categories']
+
+    def predict(self,
+                is_ramadan: int,
+                ramadan_week: int,
+                days_to_eid: int,
+                is_eid_fitr: int,
+                is_eid_adha: int,
+                is_hajj_season: int,
+                country: str,
+                category: str,
+                temperature: float,
+                day_of_week: int,
+                month: int,
+                hijri_month: int,
+                hijri_day: int) -> float:
+        """
+        Predict demand index for given features.
+
+        Args:
+            is_ramadan: 1 if Ramadan, 0 otherwise
+            ramadan_week: Week of Ramadan (1-5), 0 if not Ramadan
+            days_to_eid: Days until Eid al-Fitr (-1 if not applicable)
+            is_eid_fitr: 1 if Eid al-Fitr, 0 otherwise
+            is_eid_adha: 1 if Eid al-Adha, 0 otherwise
+            is_hajj_season: 1 if Hajj season, 0 otherwise
+            country: One of UAE, KSA, Qatar, Kuwait, Bahrain, Oman
+            category: Product category (dates_sweets, electronics, fashion_abayas,
+                      gifts, groceries, perfumes_oud)
+            temperature: Temperature in Celsius
+            day_of_week: Day of week (0-6, Monday=0)
+            month: Gregorian month (1-12)
+            hijri_month: Hijri month (1-12)
+            hijri_day: Hijri day (1-30)
+
+        Returns:
+            Predicted demand index (typically 30-200 range)
+        """
+        # Validate inputs
+        if country not in self.countries:
+            raise ValueError(f"Invalid country: {country}. Must be one of {self.countries}")
+        if category not in self.categories:
+            raise ValueError(f"Invalid category: {category}. Must be one of {self.categories}")
+
+        # Encode categorical features
+        country_encoded = self.country_encoder.transform([country])[0]
+        category_encoded = self.category_encoder.transform([category])[0]
+
+        # Create feature vector
+        features = np.array([[
+            is_ramadan,
+            ramadan_week,
+            days_to_eid,
+            is_eid_fitr,
+            is_eid_adha,
+            is_hajj_season,
+            country_encoded,
+            category_encoded,
+            temperature,
+            day_of_week,
+            month,
+            hijri_month,
+            hijri_day
+        ]])
+
+        # Make prediction
+        prediction = self.model.predict(features)[0]
+        return prediction
+
+    def predict_dict(self, data: dict) -> float:
+        """
+        Predict demand index from a dictionary of features.
+
+        Args:
+            data: Dictionary with keys matching the predict() parameters
+
+        Returns:
+            Predicted demand index
+        """
+        return self.predict(**data)
+
+    def predict_batch(self, data_list: list) -> list:
+        """
+        Predict demand index for multiple records.
+
+        Args:
+            data_list: List of dictionaries with feature values
+
+        Returns:
+            List of predicted demand indices
+        """
+        return [self.predict(**record) for record in data_list]
+
+
+def demo():
+    """Demonstrate the model with example predictions."""
+    print("=" * 60)
+    print("GCC Ramadan Retail Demand Forecasting - Demo")
+    print("=" * 60)
+
+    # Initialize forecaster
+    forecaster = DemandForecaster()
+
+    print(f"\nAvailable countries: {forecaster.countries}")
+    print(f"Available categories: {forecaster.categories}")
+    print(f"\nModel metrics: R2={forecaster.config['metrics']['r2_score']:.3f}, "
+          f"RMSE={forecaster.config['metrics']['rmse']:.2f}")
+
+    print("\n" + "-" * 60)
+    print("Example Predictions:")
+    print("-" * 60)
+
+    examples = [
+        {
+            "name": "Normal day in UAE (groceries)",
+            "params": {
+                "is_ramadan": 0, "ramadan_week": 0, "days_to_eid": -1,
+                "is_eid_fitr": 0, "is_eid_adha": 0, "is_hajj_season": 0,
+                "country": "UAE", "category": "groceries", "temperature": 25.0,
+                "day_of_week": 5, "month": 6, "hijri_month": 11, "hijri_day": 15
+            }
+        },
+        {
+            "name": "Ramadan Week 2 in KSA (dates_sweets)",
+            "params": {
+                "is_ramadan": 1, "ramadan_week": 2, "days_to_eid": 15,
+                "is_eid_fitr": 0, "is_eid_adha": 0, "is_hajj_season": 0,
+                "country": "KSA", "category": "dates_sweets", "temperature": 30.0,
+                "day_of_week": 4, "month": 4, "hijri_month": 9, "hijri_day": 15
+            }
+        },
+        {
+            "name": "Eid al-Fitr in Qatar (gifts)",
+            "params": {
+                "is_ramadan": 0, "ramadan_week": 0, "days_to_eid": 0,
+                "is_eid_fitr": 1, "is_eid_adha": 0, "is_hajj_season": 0,
+                "country": "Qatar", "category": "gifts", "temperature": 35.0,
+                "day_of_week": 0, "month": 5, "hijri_month": 10, "hijri_day": 1
+            }
+        },
+        {
+            "name": "Hajj season in KSA (perfumes_oud)",
+            "params": {
+                "is_ramadan": 0, "ramadan_week": 0, "days_to_eid": -1,
+                "is_eid_fitr": 0, "is_eid_adha": 0, "is_hajj_season": 1,
+                "country": "KSA", "category": "perfumes_oud", "temperature": 40.0,
+                "day_of_week": 3, "month": 7, "hijri_month": 12, "hijri_day": 8
+            }
+        },
+        {
+            "name": "Eid al-Adha in Kuwait (fashion_abayas)",
+            "params": {
+                "is_ramadan": 0, "ramadan_week": 0, "days_to_eid": -1,
+                "is_eid_fitr": 0, "is_eid_adha": 1, "is_hajj_season": 1,
+                "country": "Kuwait", "category": "fashion_abayas", "temperature": 42.0,
+                "day_of_week": 5, "month": 7, "hijri_month": 12, "hijri_day": 10
+            }
+        }
+    ]
+
+    for i, example in enumerate(examples, 1):
+        pred = forecaster.predict(**example["params"])
+        print(f"\n{i}. {example['name']}: {pred:.2f}")
+
+    print("\n" + "=" * 60)
+    print("Demo complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    demo()

model.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:69bef2bf5c0f86a0819e3a66afcf5a196fa3335ba8e17d87e3b6e31a7c69401a
+size 1760473

requirements.txt

@@ -0,0 +1,3 @@
+scikit-learn>=1.3.0
+joblib>=1.3.0
+numpy>=1.24.0