---
language: en
license: mit
tags:
- sports
- football
- soccer
- premier-league
- tabular
- poisson
- expected-goals
- statsmodels
library_name: statsmodels
pipeline_tag: summarization
---

# ⚽ EPL-Pulse_v1  
**English Premier League Match Outcome & Goals Predictor**

`EPL-Pulse_v1` is a **leakage-safe football match prediction model** trained on historical English Premier League data (1993/94 → 2024/25 mid-season).

The model estimates:
- **Expected goals (xG)** for home and away teams
- **Outcome probabilities**:
  - Home Win
  - Draw
  - Away Win
- **Scoreline probability distribution** (e.g., 1–0, 2–1, 0–0)

This repository contains the **production-ready model artifacts** used by the public Hugging Face Space.

---

##  What’s inside this repository

### Model artifacts
- `home_goals_model.pkl`  
  Poisson regression model for **home team goals**
- `away_goals_model.pkl`  
  Poisson regression model for **away team goals**
- `feature_list.pkl`  
  Ordered list of features used during training
- `team_state.pkl`  
  Latest per-team snapshot used for inference:
  - Elo rating
  - Rolling goals-for / goals-against
  - Timestamp of last update

> `team_state.pkl` enables **fast production inference** without recomputing rolling features at request time.

---

##  Modeling approach

### Model type
- **Poisson Generalized Linear Models (GLM)**  
  (one model for home goals, one for away goals)

### Why Poisson?
- Goals are discrete counts
- Well-established baseline in football analytics
- Interpretable and deployable
- Produces full scoreline probability distributions

### Outcome probabilities
Win / Draw / Loss probabilities are derived from the joint scoreline distribution:

```bash
P(H=i, A=j) = \text{Poisson}(i|\lambda_H) \times \text{Poisson}(j|\lambda_A)

```

---

##  Features used (leakage-safe)

All features are **computed strictly from matches played before kickoff**.



This design prevents **data leakage** and supports reliable backtesting.

---

##  Quickstart (Python)

###  Install dependencies

```bash
from huggingface_hub import hf_hub_download
import joblib

REPO_ID = "YOUR_USERNAME/EPL-Pulse_v1"

home_path = hf_hub_download(REPO_ID, "home_goals_model.pkl")
away_path = hf_hub_download(REPO_ID, "away_goals_model.pkl")
feat_path = hf_hub_download(REPO_ID, "feature_list.pkl")
state_path = hf_hub_download(REPO_ID, "team_state.pkl")

home_model = joblib.load(home_path)
away_model = joblib.load(away_path)
feature_list = joblib.load(feat_path)
team_state = joblib.load(state_path)