README.md

metadata

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

---

🧠 Model Overview

• Model Type: Tabular Regression

• Framework: AutoGluon Tabular

• 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)

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:

pip install gradio autogluon tabular pandas requests huggingface_hub

---

🌤️ Weather API Integration

The app dynamically queries the Open-Meteo API based on the selected stadium coordinates. Example usage:

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
• Model: AutoGluon Tabular Regression trained on historical NFL data
• APIs: Open-Meteo (Weather), ESPN (Game Schedule)
• Hosted on: Hugging Face Spaces

---

🧾 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.

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