README.md

---
title: NBA Performance Predictor
emoji: 🏀
colorFrom: red
colorTo: blue
sdk: gradio
sdk_version: 5.44.0
app_file: app.py
pinned: false
license: mit
---

# NBA Player Performance Predictor

## Model Description

This interactive web application predicts NBA player points per game (PPG) using machine learning. The model analyzes historical player statistics, lag features, and engineered metrics to make predictions.

## Features

- **Interactive Interface**: User-friendly sliders and inputs for player statistics
- **Example Players**: Pre-loaded NBA stars (LeBron James, Stephen Curry, etc.)
- **Real-time Predictions**: Instant predictions as you adjust parameters
- **Player Categories**: Automatic classification (Role Player → Superstar)
- **Mobile Friendly**: Works on phones, tablets, and desktops

## How to Use

1. **Input Current Season Stats**: Use sliders to set age, games played, minutes, etc.
2. **Add Historical Data**: Enter previous season performance metrics
3. **Select Position**: Choose the player's primary position
4. **Get Prediction**: Click "🔮 Predict Performance" for instant results
5. **Try Examples**: Use the example player buttons for quick testing

## Model Details

- **Task**: Regression (Predicting NBA player points per game)
- **Method**: XGBoost with time-series features
- **Features**: Age, games, minutes, shooting stats, historical performance
- **Performance**: RMSE ~3-5 points per game, R² ~0.6-0.8

## Key Features Used

The model considers various factors:
- **Basic Stats**: Age, Games, Minutes Played, Field Goals, etc.
- **Historical Performance**: Previous season statistics
- **Efficiency Metrics**: Points per minute, overall efficiency
- **Position & Team**: Encoded categorical variables
- **Trend Analysis**: Performance changes over time

## Prediction Categories

Based on predicted PPG:
- 🔵 **Role Player**: < 8 PPG
- 🟢 **Solid Contributor**: 8-15 PPG  
- 🟡 **Good Scorer**: 15-20 PPG
- 🟠 **Star Player**: 20-25 PPG
- 🔴 **Superstar**: 25+ PPG

## Example Players

Try these pre-loaded examples:
- **LeBron James (Prime)**: All-around superstar stats
- **Stephen Curry (Peak)**: Elite shooting guard numbers
- **Rookie Player**: Typical first-year player stats
- **Veteran Role Player**: Experienced bench contributor

## Technical Implementation

- **Frontend**: Gradio for interactive web interface
- **Backend**: Python with XGBoost, scikit-learn, pandas
- **Deployment**: Hugging Face Spaces
- **Fallback Mode**: Simple heuristic when ML model unavailable

## Limitations

- Works best for players with NBA history (lag features required)
- May be less accurate for rookies or players with significant role changes
- Predictions based on historical patterns, may not account for injuries or major team changes
- Current version runs in fallback mode (simplified predictions)

## Future Improvements

- Full XGBoost model integration
- Additional statistics (advanced metrics, team context)
- Multi-target prediction (rebounds, assists, efficiency)
- Player comparison features
- Historical trend visualization

## Usage Examples

### Basic Prediction
```python
# Example input for a typical NBA player
player_stats = {
    'age': 27,
    'games': 75,
    'minutes': 32.0,
    'field_goal_pct': 45.0,
    'position': 'Small Forward',
    'pts_last_season': 18.5
}
```

### Star Player Example
```python
# Example for elite player
star_stats = {
    'age': 28,
    'games': 79,
    'minutes': 36.0,
    'field_goal_pct': 50.0,
    'position': 'Point Guard',
    'pts_last_season': 28.5
}
```

## Data Sources

The model was trained on historical NBA player statistics including:
- Regular season performance data
- Multiple seasons for trend analysis
- Various player positions and team contexts

## Ethical Considerations

This model is for educational and analytical purposes only. It should not be used for:
- Player salary negotiations without additional context
- Draft decisions as the sole determining factor
- Any form of discrimination or bias in player evaluation

## Contact & Feedback

Feel free to provide feedback or suggestions for improvements. This is an educational project demonstrating machine learning applications in sports analytics.

---

**Live Demo**: Try the interactive interface above!  
**Status**: Currently running in fallback mode (simplified predictions)  
**Next Update**: Full XGBoost model integration for enhanced accuracy