---
title: NFL Receiving Yards Predictor
emoji: 📊
colorFrom: purple
colorTo: red
sdk: gradio
sdk_version: 5.49.0
app_file: app.py
pinned: false
license: mit
---

# 🏈 NFL Receiving Yards Predictor

This interactive Gradio app predicts **NFL receiving yards** for any active wide receiver or tight end based on the quarterback, game week, stadium conditions, and real-time weather forecasts.
The model leverages **AutoGluon Tabular** for regression and integrates **player embeddings**, **team data**, and **environmental context** for enhanced accuracy.

---

## 🚀 Demo

Try it live here: [Hugging Face Space](https://huggingface.co/spaces/SebastianAndreu/2025-24679-NFL-Yards-Predictor)

---

## 🧠 Model Overview

* **Model Type:** Tabular Regression
* **Framework:** [AutoGluon Tabular](https://auto.gluon.ai/stable/tutorials/tabular_prediction/index.html)
* **Training Dataset:** Aggregated play-by-play and player stats from NFL seasons
* **Input Features Include:**

  * Receiver & quarterback IDs (with learned embeddings)
  * Team and opponent IDs
  * Stadium type and surface
  * Game spread and total line
  * Weather conditions (temperature, humidity, wind, precipitation)
  * Home/Away team indicators

---

## ⚙️ How It Works

1. The app loads the pre-trained AutoGluon predictor and historical player embeddings from the Hugging Face model repo:

   ```
   SebastianAndreu/2025-24679-NFL-Yards-Predictor
   ```
2. Users select:

   * Receiver
   * Quarterback
   * Week
   * Season
3. The app fetches:

   * Game info (from local CSVs)
   * Real-time weather forecast (via [Open-Meteo API](https://open-meteo.com/))
4. The combined data is passed into the predictor for inference.
5. The model outputs the **expected receiving yards** for that matchup.

---

## 📁 Repository Structure

```
.
├── app.py                   # Main Gradio interface and logic
├── players.csv              # Active player metadata
├── games.csv                # Game schedule and context
├── hf_assets/               # Cached model assets from Hugging Face
├── nfl_model/               # Snapshot of downloaded model files
├── README.md                # You are here
```

---

## 🧩 Key Functions

### `download_model_and_embeddings()`

Downloads and prepares the AutoGluon model and the player embedding dataset from Hugging Face.

### `get_game_info()`

Matches the selected receiver’s team, week, and season to the corresponding game, including opponent and stadium metadata.

### `get_weather_forecast()`

Fetches real-time forecast for the stadium using **Open-Meteo**, returning temperature, humidity, wind speed, and rain/snow conditions.

### `predict_yards()`

Prepares the full feature vector and runs inference using the AutoGluon predictor. If missing embeddings are detected, they’re replaced by mean values for stability.

---

## 🧰 Requirements

To run locally:

```bash
pip install gradio autogluon tabular pandas requests huggingface_hub
```

---

## 🌤️ Weather API Integration

The app dynamically queries the [Open-Meteo](https://open-meteo.com/) API based on the selected stadium coordinates.
Example usage:

```python
https://api.open-meteo.com/v1/forecast?latitude=40.4468&longitude=-80.0158&hourly=temperature_2m,relative_humidity_2m,wind_speed_10m,weather_code
```

---

## 🏟️ Stadium Metadata

Each NFL stadium’s coordinates are stored in the `STADIUM_COORDS` dictionary to map weather forecasts accurately.

---

## 🏈 Credits

* **Developer:** [Sebastian Andreu](https://huggingface.co/SebastianAndreu)
* **Model:** AutoGluon Tabular Regression trained on historical NFL data
* **APIs:** Open-Meteo (Weather), ESPN (Game Schedule)
* **Hosted on:** [Hugging Face Spaces](https://huggingface.co/spaces/SebastianAndreu/2025-24679-NFL-Yards-Predictor)

---

## 🧾 License

MIT License © 2025 Sebastian Andreu

---

## 💬 Feedback

If you find a bug or have a feature suggestion, please open an issue on the [model repository](https://huggingface.co/SebastianAndreu/2025-24679-NFL-Yards-Predictor).


Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference