unirating 0.1.0

Bayesian inverse-variance fusion of FIDE, Chess.com and Lichess ratings into a single FIDE-scale rating.

unirating

Author: Sourav Sahu (@souravsahums)

Bayesian inverse-variance fusion of a player's FIDE, Chess.com and Lichess ratings into a single number on the FIDE scale, with proper handling of missing ratings, calibrated per time control.

The estimator is the maximum-likelihood / Best Linear Unbiased Estimator (Gauss–Markov) when all sources are present, and the posterior mean of a Gaussian–Gaussian Bayesian model when one or more sources are missing — so a player with no ratings at all gracefully degrades to the population prior (the "base rating") rather than crashing.

Full mathematical derivation with proof: docs/derivation.md. Citations: docs/citations.md.

---

Install

pip install unirating

Zero runtime dependencies. Python 3.9+.

---

Quick start

from unirating import Rating, TimeControl, fuse

result = fuse(
    fide       = Rating(value=1820, sigma=60),   # FIDE Rapid, settled
    chesscom   = Rating(value=1950, sigma=55),   # Chess.com Rapid, RD=55
    lichess    = Rating(value=2100, sigma=50),   # Lichess Rapid, RD=50
    time_control = TimeControl.RAPID,
)

print(result.rating)        # 1838.95  (FIDE scale)
print(result.sigma)         # 31.36    (1-sigma uncertainty)
print(result.ci95)          # (1777.5, 1900.4)
print(result.contributions) # per-source weight share, sums to 1.0

A player with no ratings at all:

from unirating import fuse, TimeControl

result = fuse(time_control=TimeControl.RAPID)
print(result.rating)  # 1500.0  (prior mean — the "base rating")
print(result.sigma)   # 350.0   (prior std-dev — full uncertainty)
print(result.is_prior_only)  # True

Lichess gives you the RD directly via API — pass it in. If you only have the rating number, the package will use a sensible default $\sigma$ but you should treat the result as approximate:

from unirating import Rating, TimeControl, fuse

result = fuse(
    lichess = Rating(value=1850),   # sigma=None → default used + warning
    time_control = TimeControl.RAPID,
)

---

What's in the box

Module	Purpose
unirating.fuse	The main entry point — call this.
unirating.Rating	Immutable (value, sigma) measurement.
unirating.Prior	Gaussian prior over latent skill. Defaults to $\mathcal N(1500, 350^2)$.
unirating.Calibration	Affine map source ↔ FIDE. Defaults per time control.
unirating.TimeControl	BULLET, BLITZ, RAPID, CLASSICAL.
unirating.FusionResult	(rating, sigma, ci95, contributions, used_sources, …).
unirating (CLI)	One-shot fusion from the shell.

---

CLI

unirating \
  --fide 1820 --fide-sigma 60 \
  --chesscom 1950 --chesscom-rd 55 \
  --lichess 2100 --lichess-rd 50 \
  --time-control rapid

Output:

Unified rating (FIDE scale): 1839 ± 31
95% CI: [1778, 1900]
Sources used: fide, chesscom, lichess
Contributions: prior=1%  fide=27%  chesscom=33%  lichess=39%

---

How the math works (one paragraph)

Each rating is treated as a noisy linear measurement $R_i = \alpha_i + \beta_i \theta + \varepsilon_i$, $\varepsilon_i \sim \mathcal N(0, \sigma_i^2)$, of the latent FIDE-equivalent skill $\theta$. After inverting each measurement to a FIDE-scale estimate $\hat\theta_i$ with variance $\tau_i^2 = \sigma_i^2/\beta_i^2$, the posterior mean of $\theta$ given a Gaussian prior $\mathcal N(\mu_0, \sigma_0^2)$ is the precision-weighted average

$$ \hat\theta = \frac{\mu_0/\sigma_0^2 + \sum_{i \in S} \hat\theta_i/\tau_i^2}{1/\sigma_0^2 + \sum_{i \in S} 1/\tau_i^2} $$

over whatever subset $S$ of sources is present. With no sources, the formula collapses to $\mu_0$. The full proof (MLE + Gauss–Markov + Bayes), the choice of constants, and a worked example are in docs/derivation.md.

---

Calibration constants (defaults)

Time control	Chess.com $\alpha,\beta$	Lichess $\alpha,\beta$
BULLET	150, 1.0	400, 1.0
BLITZ	120, 1.0	350, 1.0
RAPID	100, 1.0	250, 1.0
CLASSICAL	50, 1.0	200, 1.0

Source: published community regressions (see docs/citations.md). You can override per call:

from unirating import Calibration, fuse

custom = Calibration(chesscom_alpha=80, lichess_alpha=300)
result = fuse(..., calibration=custom)

---

Edge cases handled

• No ratings → returns prior, is_prior_only=True.
• One rating → posterior shrinks toward prior; weight reported.
• Missing $\sigma_i$ → fills with conservative default, emits MissingSigmaWarning.
• Provisional rating (large RD, Lichess ?) → naturally down-weighted; warns if RD > 110.
• Zero / negative $\sigma_i$ → raises InvalidRatingError.
• Non-finite values (nan, inf) → raises InvalidRatingError.
• Out-of-range ratings → raises InvalidRatingError (configurable bounds).
• Mixed time controls → only one TimeControl per call; the calibration enforces consistency.
• Custom prior → pass any Prior(mu, sigma) (e.g. for juniors, titled players).
• Numerical stability → all sums computed in precision-space then inverted at the end.

See tests/ for the formal coverage.

---

Citation

If you use this package in academic work, please cite:

@software{sahu_unirating_2026,
  author  = {Sahu, Sourav},
  title   = {unirating: Bayesian inverse-variance fusion of FIDE,
             Chess.com and Lichess ratings},
  year    = {2026},
  url     = {https://github.com/souravsahums/unirating},
  version = {0.1.0},
}

Plain text: Sahu, S. (2026). unirating: Bayesian inverse-variance fusion of FIDE, Chess.com and Lichess ratings (v0.1.0) [Computer software]. https://github.com/souravsahums/unirating

---

License

MIT — see LICENSE. Copyright © 2026 Sourav Sahu.