A machine learning-powered system for predicting fantasy football player performance, featuring injury tracking and a modern web dashboard.
Ensure Python 3.9+ is installed, then install requirements:
pip install -r scraper/requirements.txt
pip install -r backend/requirements.txt
pip install -r ml/requirements.txtInstall the CLI globally for easy command access with animated spinners, branded logo, and colored feedback:
npm install -g .Using Python directly:
# 1. Scrape fresh data from FPL API
python scraper/main.py
# 2. Load and process data
python -m backend.etl
python -m backend.features
# 3. Train the ML model
python ml/train.py
# 4. View predictions
python ml/predict.py --gameweek 37 --top 20 --show-injured
# 5. Start API server
python -m uvicorn backend.main:app --reload
# 6. Open dashboard in browser
frontend/dashboard.htmlUsing the CLI (after npm install -g): The CLI features animated spinners, a branded logo, and colored feedback for an enhanced user experience.
# 1. Scrape data
fantasy-cli scrape
# 2. Run ETL and features
fantasy-cli etl
fantasy-cli features
# 3. Train model
fantasy-cli train
# 4. Get predictions
fantasy-cli predict --gameweek 37 --top 20 --show-injured
# 5. Start API
fantasy-cli api
# 6. Open dashboard
fantasy-cli dashboard- Random Forest model trained on 8,063+ match records
- Predicts player points 1-2 gameweeks in advance
- Benchmark: MAE of 1.02 points (within 1 point accuracy on average)
- Automatically scrapes FPL injury data
- Filters injured/unavailable players from predictions
- Shows expected return gameweek
- Modern responsive web interface
- Real-time prediction fetching
- Player rankings and statistics
- Injury alerts and status
- FastAPI backend with full documentation
- Endpoints for players, fixtures, teams, predictions
- CORS enabled for frontend integration
- scraper/ - FPL API data collection
- backend/ - FastAPI server, database, ETL
- ml/ - Feature engineering, model training, predictions
- frontend/ - Interactive HTML dashboard
- data/ - Raw JSON and processed data
FPL API
↓
Scraper (Python) → data/raw/*.json
↓
ETL Pipeline → SQLite Database
↓
Feature Engineering (8 features per player-match)
↓
Model Training (Random Forest, 100 estimators)
↓
Predictions API ← Frontend Dashboard
- Training Samples: 8,063
- Mean Absolute Error (MAE): 1.02 points
- Root Mean Squared Error (RMSE): 1.93 points
- R-squared (R²): 0.32
- Form (43%) - Recent performance
- Goal Threat (16%) - Attacking contribution rate
- Minutes Consistency (12%) - Playing time stability
- Historical Averages (12%) - Past performance
- Injury Risk (8%) - Minute drop-off detection
- Home/Away (3%) - Location advantage
- Opponent Difficulty (6%) - Defense strength
- QUICKSTART.md - Setup and basic usage
- PIPELINE.md - Detailed pipeline explanation
- FRONTEND_GUIDE.md - Dashboard usage guide
- STATUS.md - Implementation status and features
python ml/predict.py --gameweek 37 --top 20
# or
fantasy-cli predict --gameweek 37 --top 20python ml/predict.py --gameweek 37 --show-injured
# or
fantasy-cli predict --gameweek 37 --show-injuredpython -m backend.etl
python -m backend.features
python ml/train.py --model random_forest
# or
fantasy-cli etl && fantasy-cli features && fantasy-cli trainpython -m uvicorn backend.main:app --host 0.0.0.0 --port 8000
# or
fantasy-cli api- Python 3.9+
- pip packages: scikit-learn, pandas, numpy, fastapi, sqlalchemy
- Optional: Node.js for Next.js frontend (current: HTML only)
Priority enhancements:
- Injury tracking integration (completed)
- Interactive dashboard (completed)
- Opponent difficulty dynamic calculation
- Authentication and rate limiting
- Real-time injury updates
- Ensemble models (XGBoost, LightGBM)
- Player watchlist and alerts
- Historical performance tracking