sports-quant

March Madness bracket prediction and NFL over/under modeling.

2025 bracket prediction — 51 of 63 games correct (81.0%)

Model Highlights

Year-by-Year Accuracy

Results from v6b LightGBM ensemble with forward simulation, backtested across 6 tournaments:

Average accuracy: 72.7% across 6 tournaments (274 / 377 games)

Upset Predictions

The model's best upset calls — games where a lower-seeded team was correctly predicted to win:

2024

2023

2019

How the March Madness Model Works

The March Madness model uses a LightGBM ensemble trained on historical tournament data with features derived from team performance metrics, seeding, and matchup interactions.

1. Feature engineering — KenPom ratings, Barttorvik T-Rank, seed-based statistics, conference strength, and matchup interaction features
2. Ensemble prediction — Multiple LightGBM models vote on each game's win probability
3. Forward simulation — The bracket is filled round-by-round, feeding predicted winners into the next round
4. Seed debiasing — Adjusts for historical seed-vs-seed upset rates to avoid over-favoring top seeds
5. Backtesting — Every prediction is out-of-sample; the model never sees future tournament results during training

Survivor Pool Optimizer

The project also includes a survivor pool optimizer that uses the model's round-by-round probabilities to select optimal picks across multiple strategies:

• Greedy — Pick the highest-probability survivor each round
• Bracket-aware — Avoid picking teams from the same bracket side
• Monte Carlo optimal — Simulate thousands of scenarios to maximize expected survival

NFL Over/Under Modeling

An end-to-end data pipeline that scrapes PFF team grades and Pro Football Reference game/betting data, builds analysis-ready datasets, and trains an ensemble XGBoost model for NFL over/under prediction.

How the NFL Model Works

The core idea is simple: don't try to predict every game — find the games where the model is reliably right, and only bet those.

On each game-day the pipeline trains 50 XGBoost models with different random seeds on all available historical data. The pipeline filters to the top 3 based on a weighted seasonal accuracy score, then requires all three to agree on a pick before it counts. Each consensus pick gets an algorithm score that captures how well the ensemble has historically performed at that confidence level.

Higher algorithm-score bins tend to stay accurate across multiple seasons, while lower bins stay inaccurate.

Technical Details

NFL Pipeline Architecture

PFF Scrape              PFR Scrape
    |                       |
    v                       v
Extract Dates          Normalize Dates
    |                       |
    v                       v
Normalize Names        Normalize Names
    |                       |
    +----------+   +--------+
               |   |
               v   v
              Merge
                |
                v
           Over/Under
                |
                v
         Rolling Averages
                |
                v
          Games Played
                |
                v
            Rankings
                |
       +--------+--------+
       |                  |
       v                  v
  Model Train        Backtest
  (ensemble)       (walk-forward)

Example Charts

Features

• March Madness Bracket Prediction — LightGBM ensemble with forward simulation, seed debiasing, and survivor pool optimization
• PFF Scraping — Selenium-based scraper for PFF team grades (requires PFF Premium; manual login on first run, cookies cached for subsequent runs)
• PFR Scraping — Proxy-rotated scraper for Pro Football Reference boxscores
• Data Normalization — Standardizes dates and team names across sources
• Dataset Merging — Inner join on date + team columns
• Rolling Averages — Pre-game cumulative stat averages per team per season
• Games Played Tracking — Cumulative games played before each matchup
• Feature Rankings — Per-date rankings across all teams
• Ensemble Training — Trains 50 XGBoost models per game-day, selects top 3 by weighted seasonal accuracy, requires consensus agreement, and runs a financial simulation
• Walk-Forward Backtesting — Trains 50 models across every historical date using walk-forward validation and averages metrics across all models
• CLI + Python API — Run the full pipeline or any individual step

Installation

Install from PyPI:

pip install sports-quant

Or install from source with Poetry:

git clone https://github.com/thadhutch/sports-quant.git
cd sports-quant
poetry install

Prerequisites

Configuration

Create a .env file (see .env.example) or export environment variables directly:

cp .env.example .env

Usage

CLI

# March Madness
sports-quant march-madness backtest         # Backtest across historical tournaments
sports-quant march-madness simulate 2025    # Generate 2025 bracket predictions
sports-quant march-madness survivor 2025    # Run survivor pool optimizer

# NFL (full pipeline)
sports-quant pipeline

# NFL (individual steps)
sports-quant scrape pff
sports-quant scrape pfr
sports-quant process all
sports-quant model train
sports-quant model backtest

Python API

import sports_quant

# March Madness
sports_quant.run_march_madness_backtest()
sports_quant.simulate_bracket(year=2025)

# NFL
sports_quant.run_full_pipeline()
sports_quant.run_training()
sports_quant.run_backtest()

Project Structure

sports-quant/
├── src/sports_quant/
│   ├── __init__.py           # Public API re-exports
│   ├── _config.py            # Paths, env vars, logging
│   ├── cli.py                # Click CLI entry point
│   ├── pipeline.py           # Pipeline orchestrators
│   ├── teams.py              # Team name/abbreviation mappings
│   ├── march_madness/        # March Madness bracket prediction
│   ├── scrapers/
│   │   ├── pff.py            # PFF grades scraper (Selenium)
│   │   ├── pfr.py            # PFR game data scraper
│   │   ├── pfr_urls.py       # PFR boxscore URL collector
│   │   ├── auth.py           # PFF authentication
│   │   └── proxies.py        # Proxy loading utilities
│   ├── parsers/
│   │   ├── pff_dates.py      # PFF date extraction
│   │   ├── pff_teams.py      # PFF team name normalization
│   │   ├── pfr_dates.py      # PFR date normalization
│   │   └── pfr_teams.py      # PFR team name extraction
│   ├── processing/
│   │   ├── merge.py          # Merge PFF + PFR datasets
│   │   ├── over_under.py     # O/U betting line extraction
│   │   ├── rolling_averages.py
│   │   ├── games_played.py
│   │   └── rankings.py
│   └── modeling/
│       ├── __init__.py       # Public API (run_training, run_backtest)
│       ├── _features.py      # Shared feature definitions
│       ├── _data.py          # Data loading and preparation
│       ├── _training.py      # Single-model and ensemble training
│       ├── _scoring.py       # Season weighting, consensus, model selection
│       ├── _simulation.py    # Financial simulation / profit tracking
│       ├── train.py          # Ensemble training orchestrator
│       ├── backtest.py       # Walk-forward backtesting orchestrator
│       └── plots.py          # All modeling-related charts
├── tests/
├── model_config.yaml
├── pyproject.toml
├── Makefile
├── LICENSE
└── README.md

Development

git clone https://github.com/thadhutch/sports-quant.git
cd sports-quant
poetry install
poetry run pytest -v

CI runs automatically on every push to master and on pull requests via GitHub Actions. Releases are published to PyPI through Trusted Publishers.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes and add tests
4. Run the test suite (poetry run pytest -v)
5. Commit and push
6. Open a Pull Request

Known Limitations

• Data files are not tracked in git. Run the pipeline to generate them.
• PFF scraping is DOM-dependent. If PFF changes their frontend, selectors need updating.
• PFR scraping requires rotating proxies. Without them, requests will be rate-limited.
• PFF login requires manual interaction on first run. Cookies are cached afterward.

License

This project is licensed under the MIT License.

PyPI · Issues · CI Status