mj-weshh/energy-anomaly-forecasting

An end-to-end ML pipeline for smart meter data. Features unsupervised anomaly detection to filter telemetry, establishing a clean baseline for advanced time-series forecasting (XGBoost/LSTM). Developed for Wawtex Solutions Ltd through the CMU-Africa Techskills program. # Energy Anomaly Forecasting Open-source ML pipeline for **smart-meter anomaly detection** and **short-horizon energy forecasting**, built on the public Kaggle Smart Meter Electricity Consumption Dataset. Developed for **Wawtex Solutions** and **CMU-Africa** handover — reproducible end-to-end from raw CSV to scored forecasts. --- ## Project summary This repository turns 5,000 half-hourly meter readings into a clean timeline, flags anomalies without using the benchmark label for training, and forecasts consumption with a four-model ladder: | Stage | What it does | |-------|----------------| | **Ingest & EDA** | Load, validate schema, profile load patterns | | **Detect & clean** | Isolation Forest / DBSCAN → interpolate flagged intervals | | **Forecast** | Naive → Prophet → XGBoost → LSTM on chronological splits | | **Ship** | Root CLI (`main.py`), tutorial notebook, research write-up, MkDocs site | **Default ladder winner (test MAE / RMSE):** Prophet ≈ **0.121 / 0.149**, beating the seasonal-naive floor (≈ **0.171 / 0.214**). Full narrative: Forecasting Research. **Documentation site (source):** start at `docs/index.md` or run locally with MkDocs (below). --- ## Tech stack | Area | Libraries | |------|-----------| | **Core data** | pandas, numpy | | **Modeling** | scikit-learn, Prophet, XGBoost, PyTorch | | **Visualization** | matplotlib, seaborn | | **Notebooks** | Jupyter, ipykernel | | **Docs & tests** | MkDocs Material, pytest | Pinned minimums live in `requirements.txt`. --- ## How to run ### 1. Clone and create a virtual environment ```bash git clone github.com cd energy-anomaly-forecasting python -m venv .venv # Windows .venv\Scripts\activate # macOS / Linux source .venv/bin/activate ``` ### 2. Install dependencies ```bash pip install -r requirements.txt ``` ### 3. Place the dataset Put `smart_meter_data.csv` in either: - `Smart Meter Electricity Consumption Dataset/smart_meter_data.c …