$ show fivethirtyeight/nfl-elo-game
This repository implements FiveThirtyEight's NFL Elo forecasting model and evaluation framework. The data lineage flows from two raw CSV sources: `data/nfl_games.csv` containing historical game results (1920-present) with pre-computed Elo win probabilities, and `data/initial_elos.csv` providing starting Elo ratings for each franchise. The `forecast.py` module implements the core Elo engine: it initializes team ratings, applies season-to-season reversion (retaining 2/3 of prior rating, reverting 1/3 toward 1505), incorporates home-field advantage (65 Elo points), and updates ratings post-game using a margin-of-victory multiplier (log(pd+1) * 2.2/(elo_diff*0.001+2.2)). Special hardcoded reversions handle franchise relocations/expansions. The `util.py` module handles CSV parsing with type coercion and evaluates forecasts using a Brier-score-based points system (25 - 100*brier, doubled for playoffs). The `eval.py` script orchestrates the full pipeline: load games, generate forecasts, evaluate against FiveThirtyEight's baseline. The repo answers the research question: 'Can alternative forecasting models beat FiveThirtyEight's Elo model on historical NFL data?'
The LLM identified 3 files worth highlighting for reuse:
Production-grade Elo implementation with sophisticated margin-of-victory multiplier and season reversion logic. The MOV multiplier `log(max(pd,1)+1) * 2.2/(elo_diff*0.001+2.2)` elegantly handles blowouts while auto-calibrating for pre-game favorite status. The REVERSIONS dict handles franchise relocations (e.g., Cleveland 1999 expansion, St. Louis Rams 1944) with historical accuracy. Reusable for any sports league with minimal parameter changes (HFA, K, REVERT).
Robust CSV loader with defensive type coercion (int/float/None handling for empty strings) and a complete forecast evaluation framework. The Brier scoring system (25 - 100*brier, playoff 2x) is the exact FiveThirtyEight game scoring rule. The `evaluate_forecasts` method provides per-season breakdowns and overall averages, plus upcoming game forecast printing. Directly reusable for any binary outcome forecasting competition.
Minimal, clean pipeline orchestrator demonstrating the Unix philosophy: one script that composes loader → model → evaluator. No CLI args, config files, or boilerplate — just three lines showing the full data flow. Ideal template for rapid prototyping of forecasting models where you want to swap `forecast.py` with alternative implementations.