README.md

---
tags:
- time-series-forecasting
- multivariate-forecasting
- transformer
- e-commerce
- inventory-management
datasets:
- EcomSalesPerformance
license: mit
---

# EcomSalesTrendPredictor

## 📈 Overview

EcomSalesTrendPredictor is a **Time Series Transformer** model designed for **multivariate forecasting** of e-commerce sales performance metrics. Specifically, it is trained to predict future `Revenue_USD` and `UnitsSold` (implicitly handled as separate series during training, or focused on one primary series like `Revenue_USD` as `input_size=1` for simplicity) for multiple product SKUs across various regions.

The model incorporates numerous real-world contextual features, including static (e.g., product category, region) and dynamic (e.g., promotion status, season, inventory level) variables, making it highly robust for complex supply chain and financial planning tasks.

## 🧠 Model Architecture

This model utilizes the **Time Series Transformer (TST)** architecture, which is state-of-the-art for sequence modeling tasks due to its use of self-attention mechanisms.

* **Model Type:** `TimeSeriesTransformerModel` (from HuggingFace's transformers/pytorch-forecasting implementation).
* **Input:** Multiple time series (each SKU/Region combination is a series) of historical data for the target metric (`Revenue_USD` or `UnitsSold`).
* **Context/Prediction:** Uses a `context_length` of 30 days of historical data to predict the next `prediction_length` of 7 days.
* **Feature Integration:**
    * **Static Categorical:** Region, ProductCategory, SKU (embedded).
    * **Static Real:** Log of average CustomerRating, Shipping Cost.
    * **Dynamic Real:** Inventory_Level, DaysSinceLastRestock, InventoryRiskScore.
    * **Dynamic Categorical:** PromotionApplied, Season.
* **Output:** The model outputs a set of **quantiles** (0.1, 0.5, 0.9) for the forecast, providing an uncertainty range rather than a single point estimate.

## 🚀 Intended Use

* **Sales Forecasting:** Predict weekly revenue and unit sales for better financial planning.
* **Inventory Optimization:** Use the 7-day forecast to trigger restocking orders, minimizing stockouts (high `InventoryRiskScore`) or excess inventory.
* **Demand Planning:** Analyze the impact of dynamic features (promotions, season) on future demand.
* **Multi-Region Strategy:** Compare and predict performance across different geographic regions simultaneously.

## ⚠️ Limitations

* **Data Density:** Performance may degrade if the input time series contains large gaps or is highly irregular.
* **External Shocks:** Like all time-series models, it cannot predict sudden, unforeseen external events (e.g., pandemics, major news events) that significantly disrupt market patterns.
* **Computational Cost:** Transformer-based models are more computationally expensive than simpler models (like ARIMA) for both training and inference.
* **SKU Limit:** The model is implicitly limited by the SKU cardinality it was trained on; adding entirely new products requires retraining or fine-tuning.

## 💻 Example Code

To use the model for forecasting (requires a compatible time series library like `pytorch-forecasting`):

```python
import pandas as pd
from transformers import AutoModel
from pytorch_forecasting import TimeSeriesDataSet, DeepAR

# NOTE: Actual inference with TST requires full PyTorch Forecasting setup.
# This example illustrates the data preparation steps.

model_name = "your-username/EcomSalesTrendPredictor" # Replace with actual HuggingFace path
# model = AutoModel.from_pretrained(model_name) 

# Example historical data for one series (truncated for simplicity)
data = {
    'time_idx': [1, 2, 3, 4, 5],
    'target': [34995.0, 3600.0, 937.5, 18750.0, 2700.0],
    'series': ['EL-LAP-001'] * 5,
    'Region': ['North America'] * 5,
    'ProductCategory': ['Electronics'] * 5,
    'UnitsSold': [45, 180, 75, 15, 90],
    'Inventory_Level': [120, 500, 90, 40, 300],
    'PromotionApplied': [0, 1, 0, 0, 1]
}
df = pd.DataFrame(data)

# The loaded model object expects a TimeSeriesDataSet object for inference.
# The TST is highly dependent on the correct feature schema defined in its config.
print(f"Model configured for a prediction length of {model_config.prediction_length} days.")
print("Inference requires pre-processing the data into a TimeSeriesDataSet format.")