---
language: en
license: mit
tags:
- xgboost
- tabular-regression
- mlb
- baseball
library_name: xgboost
---

# ⚾ MLB Live Game Duration XGBoost Predictor

This repository contains an **XGBoost regression model** trained to predict the total expected duration (in minutes) of live Major League Baseball (MLB) games based on real-time pitch-by-pitch game state.

## 📊 Model Details

- **Model Type:** XGBoost Regressor (`XGBRegressor`)
- **Format:** Native XGBoost JSON (`xgb_live_model.json`)
- **Task:** Tabular Regression (`tabular-regression`)
- **Target Variable:** `final_game_minutes` (Total game duration in minutes)

### Input Features (19 columns)

| Feature | Type | Description |
| :--- | :--- | :--- |
| `inning` | Integer | Current inning number |
| `outs_when_up` | Integer | Number of outs (0, 1, or 2) |
| `run_diff` | Integer | Absolute difference between home and away scores |
| `is_home_leading` | Binary (0/1) | Whether the home team is leading |
| `is_tied` | Binary (0/1) | Whether the score is tied |
| `on_1b` | Binary (0/1) | Runner on 1st base |
| `on_2b` | Binary (0/1) | Runner on 2nd base |
| `on_3b` | Binary (0/1) | Runner on 3rd base |
| `total_runs` | Integer | Sum of home and away runs scored so far |
| `home_pitchers_used` | Integer | Count of home team pitchers used |
| `away_pitchers_used` | Integer | Count of away team pitchers used |
| `home_starting_pitcher` | Binary (0/1) | Whether home starting pitcher is still in |
| `away_starting_pitcher` | Binary (0/1) | Whether away starting pitcher is still in |
| `total_pitch_count` | Integer | Total pitches thrown in the game |
| `total_pa` | Integer | Total plate appearances in the game |
| `is_dome` | Binary (0/1) | Game played in a dome stadium |
| `is_national_tv` | Binary (0/1) | Game broadcast on national TV |
| `is_night_game` | Binary (0/1) | Game scheduled as a night game |
| `is_rivalry` | Binary (0/1) | Intra-division rivalry matchup |

---

## 🚀 How to Load & Use in Python

```python
import xgboost as xgb
import pandas as pd
from huggingface_hub import hf_hub_download

# 1. Download the JSON model file from Hugging Face Hub
# Replace 'your-username' with your actual Hugging Face username
model_path = hf_hub_download(
    repo_id="your-username/mlb-game-duration-xgboost", 
    filename="xgb_live_model.json"
)

# 2. Load into XGBRegressor
model = xgb.XGBRegressor()
model.load_model(model_path)

# 3. Make predictions on a game state DataFrame
# sample_df = pd.DataFrame([{ "inning": 5, "outs_when_up": 1, ... }])
# predicted_minutes = model.predict(sample_df)[0]
# print(f"Predicted Total Duration: {predicted_minutes:.1f} minutes")
```