Elote

The scikit-learn of rating algorithms: compare rating models behind one largely uniform Python interface, then keep the one that fits your data.

Use Elote to turn pairwise wins, losses, and draws into expected scores and rankings. Start with Elo, switch to Glicko, TrueSkill, Bradley-Terry, or another included model without rewriting the surrounding workflow, and evaluate the alternatives on the same match history.

pip install elote

Compare and rank in 60 seconds

The same matchups can drive different rating systems:

from elote import EloCompetitor, GlickoCompetitor, LambdaArena

winner_loser_pairs = [
    ("Ada", "Grace"),
    ("Grace", "Linus"),
    ("Ada", "Linus"),
    ("Grace", "Linus"),
]

for model in (EloCompetitor, GlickoCompetitor):
    arena = LambdaArena(lambda winner, loser: True, base_competitor=model)
    for winner, loser in winner_loser_pairs:
        arena.matchup(winner, loser)

    ranking = [row["competitor"] for row in arena.leaderboard()]
    print(f"{model.__name__}: {' > '.join(ranking)}")

EloCompetitor: Ada > Grace > Linus
GlickoCompetitor: Ada > Grace > Linus

LambdaArena owns the population, creates competitors as identifiers appear, records each bout, and returns the leaderboard best-first. Change base_competitor to compare another model with the same application code.

Choose your task

Install the dataset adapters when you want the Lichess chess or college-football loaders:

pip install "elote[datasets]"

Install the plotting helpers when you want the visualization functions:

pip install "elote[viz]"

SyntheticDataset and the core rating systems are included in the base installation.

Rating models

Every row below is exported from elote and supports the shared competitor workflow. Constructor parameters and algorithm-specific state still differ.

The common surface covers expected scores, results, ratings, reset, configuration, and state serialization. It does not erase meaningful differences in parameters, uncertainty, rating scale, or whether a model updates incrementally or refits a connected population.

Evaluation tools

Elote keeps pre-result predictions in History objects so you can inspect accuracy, precision, recall, F1, draw-aware metrics, confusion counts, calibration data, optimized decision thresholds, and accuracy by prior bouts. Dataset helpers train on one split and evaluate on another without updating ratings on the held-out rows. Benchmark results retain the trained arena and history for further analysis.

The package also includes plotting helpers for rating-system comparisons, optimized accuracy, calibration, and accuracy by prior bouts.

To see how the rating models compare on the same split, run make compare-systems (or scripts/rating_system_comparison.py directly) for accuracy, Brier score, and log loss — see docs/source/rating_systems/comparison_benchmark.rst for methodology and measured results.

Library boundaries

Elote is an in-process Python library. It does not provide a CLI, hosted API, server, user interface, accounts, authentication, or a database. Your application supplies identifiers and results, decides how a model is selected, and stores exported dictionaries or JSON in the persistence system it owns.

Trust and project status

• Python 3.10 or later
• Typed-package marker (py.typed)
• MIT licensed
• Behavioral and known-value tests across the model catalog, plus tests for serialization, datasets, benchmarking, histories, plots, and the shared interface
• Published with an Alpha development classifier

See the full documentation and the examples/ directory for more workflows.

Blog Posts

Here are some blog posts about Elote:

• Elote: A Python Package for Rating Systems - Introduction to the library
• Using Cursor for Library Maintenance - How Cursor helps maintain Elote
• Year's End: Looking Back at 2017 - Reflections including Elote development

References

1. Glicko Rating System
2. Glicko-2 Rating System
3. Massey Ratings
4. Elo, Arpad (1978). The Rating of Chessplayers, Past and Present. Arco. ISBN 0-668-04721-6.
5. ECF Grading System
6. Deutsche Wertungszahl
7. TrueSkill: A Bayesian Skill Rating System

Contributing

Contributions are welcome. Read CONTRIBUTING.md and the Code of Conduct, then open an issue or pull request.

git clone https://github.com/wdm0006/elote.git
cd elote
make install-dev
make test       # or: make test-cov
make lint       # or: make lint-fix, make format
make docs       # or: make build

Elote is available under the MIT License.