balloon-ranking-glicko

A Glicko-2 based rating engine for competitive hot-air balloon pilots.

This is the public, open-source rating math behind the Global Balloon Pilot Ranking System. It is a pure-Python package with zero runtime dependencies. Given a chronological history of competition events, it produces a Glicko-2 rating, rating deviation (RD), and volatility for every pilot, plus derived values (Strength of Field, tier assignments).

Design

• Algorithm: Glicko-2, implemented directly from Mark Glickman's specification.
• Input signal: task finishing position, not raw points. Position is the cleaner signal of "did this pilot beat that pilot in this task".
• Rating period: one per event. All pairwise outcomes from all of an event's tasks are pooled into a single Glicko-2 update per pilot.
• No-result handling: no-result pilots are tied for last within the no-result group. This matches FAI scoring conventions.
• Pure functions, zero I/O: no database, no network, no file I/O. The caller supplies events and prior ratings; the engine returns new ratings.

The engine has no opinions about storage or identity. The caller supplies events plus the rating state entering each event; the engine returns the state coming out.

Install

pip install balloon-ranking-glicko

Quick start

from datetime import date
from balloon_ranking_glicko import Event, Task, TaskResult, RatingEngine

event = Event(
    event_id="example-2026",
    event_date=date(2026, 6, 1),
    tasks=(
        Task(
            task_id="t1",
            results=(
                TaskResult(pilot_id="alice", position=1),
                TaskResult(pilot_id="bob", position=2),
                TaskResult(pilot_id="carol", position=3),
            ),
        ),
    ),
)

engine = RatingEngine()
ratings = engine.process_history([event])
for pid, r in sorted(ratings.items(), key=lambda kv: -kv[1].rating):
    print(f"{pid}: {r.rating:.1f} (RD {r.rd:.1f})")

Public API

• Event, Task, TaskResult, PilotRating — frozen dataclasses
• RatingEngine(tau, initial_rating, initial_rd, initial_volatility)
  • process_event(event, prior_ratings) -> dict[str, PilotRating]
  • process_history(events) -> dict[str, PilotRating]
  • process_history_with_snapshots(events) -> Iterator[(Event, dict[str, PilotRating])]
• compute_sof(event, ratings) -> float
• assign_tiers(ratings, cutoffs=None) -> dict[str, str]

Development

pip install -e ".[dev]"
pytest
mypy

The Glicko-2 implementation is validated against the worked example from Glickman's paper (final rating 1464.06, RD 151.52, volatility 0.05999).

License

MIT