Whole-History Rating for Python

A maintained, pure-Python implementation of Rémi Coulom's Whole-History Rating (WHR) algorithm for estimating time-varying skills from dated pairwise results.

WHR is useful when the history of a competitor's strength matters—not only the latest leaderboard—and when later evidence should be allowed to refine earlier ratings.

Installation

pip install whole-history-rating

Python 3.11 or newer and NumPy 2.0 or newer are required.

Quickstart

from whr import WHR

model = WHR()
model.load_games(
    [
        "alice bob B 1",
        "alice bob W 2",
        "alice bob B 3",
    ]
)
model.auto_iterate()

print(model.ratings_for_player("alice"))
print(model.probability_future_match("alice", "bob"))

Games are formatted as black_player white_player result time_step, where the result is B, W, or D. You can also add structured games with create_game().

Why Whole-History Rating?

Unlike an online rating update, WHR jointly revisits each competitor's complete trajectory when new results are added. A later result can therefore refine the estimated rating at an earlier date.

This implementation provides:

• retrospective smoothing of time-varying skill;
• uncertainty for ratings, differences, and changes over time;
• uncertainty-aware match predictions;
• binary outcomes and Davidson-model draws;
• learned contextual advantages such as home advantage, handicap, and komi;
• convergence and data-connectivity diagnostics;
• a reproducible comparison with KickScore and TrueSkill Through Time.

The main reason to choose WHR is not that it wins every predictive benchmark—it does not. Its strength is an interpretable, relatively lightweight model of complete pairwise histories.

Benchmark evidence

Lower log-loss is better. All systems below are trained, tuned, and evaluated under the same temporal protocol.

No system wins every dataset, and the gaps are small. WHR leads the three-outcome football comparison, KickScore leads the NBA comparison, and TrueSkill Through Time leads tennis. Domain-specific NBA models using rosters, injuries, and travel still outperform all three generic rating systems.

The complete protocol, hyperparameter grids, limitations, data sources, and reproduction commands are in the benchmark report and benchmark README.

Applications

WHR can be used for dated pairwise-comparison histories such as:

• board games including Go and chess;
• sports and esports rankings;
• historical leaderboards;
• matchmaking analysis;
• human-preference experiments;
• pairwise evaluation of models or systems.

The model observes outcomes, dates, and optional contextual effects. It does not use domain-specific information such as rosters, injuries, maps, prompts, or evaluator identities. For LLM evaluation, treat it as a rating component rather than a complete evaluation methodology.

Documentation

• User guide: complete examples, configuration, uncertainty, draws, handicap, and komi.
• API reference: the supported high-level surface.
• Benchmark report: protocol, results, and caveats.
• Changelog: release-by-release compatibility notes.

The documentation site can be built locally with:

uv sync --group docs
uv run --group docs mkdocs build --strict

Implementation characteristics

• Pure Python with NumPy used where batching is beneficial.
• No compiled extension required.
• Binary and drawn outcomes.
• Learned contextual advantages.
• Reproducible real-data benchmark suite.
• High-level compatibility alias for the former Base class.

The project originated as a port of the GoShrine Ruby implementation and has since added a modern API, diagnostics, draws, learned contextual advantages, uncertainty-aware predictions, and cross-library benchmarks.

Citation

If you use this package in research, cite both the software and Rémi Coulom's original WHR paper. GitHub exposes the complete metadata from CITATION.cff.

Rémi Coulom. “Whole-History Rating: A Bayesian Rating System for Players of Time-Varying Strength.” Computers and Games, LNCS 5131, 113–124, 2008. DOI: 10.1007/978-3-540-87608-3_11.

Development

uv sync --dev
uv run ruff check whr tests benchmarks
uv run mypy
uv run pytest

The fast CI suite also runs a synthetic benchmark smoke test. Full real-data benchmarks are intentionally manual because they download external datasets and can take hours.

License

MIT. See the license text.