unirating 0.1.0__tar.gz

unirating-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/
+.hypothesis/
+coverage.xml
+*.cover
+
+# mypy / ruff
+.mypy_cache/
+.ruff_cache/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Virtual envs
+.venv/
+venv/
+env/

unirating-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-13
+
+### Added
+- Initial release.
+- Bayesian inverse-variance fusion of FIDE, Chess.com and Lichess ratings.
+- `Rating`, `Prior`, `Calibration`, `TimeControl`, `FusionResult` data models.
+- `fuse()` entry point with full edge-case coverage:
+  no ratings, single rating, missing sigma, provisional ratings,
+  invalid inputs, custom priors, custom calibration.
+- Default per-time-control calibration constants
+  (Bullet / Blitz / Rapid / Classical).
+- Command-line interface (`unirating`).
+- Full mathematical derivation with proof (MLE, Gauss–Markov, Bayes).
+- Citations document.
+- Test suite (unit + property-based via Hypothesis).

unirating-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sourav Sahu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

unirating-0.1.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: unirating
+Version: 0.1.0
+Summary: Bayesian inverse-variance fusion of FIDE, Chess.com and Lichess ratings into a single FIDE-scale rating.
+Project-URL: Homepage, https://github.com/souravsahums/unirating
+Project-URL: Documentation, https://github.com/souravsahums/unirating#readme
+Project-URL: Issues, https://github.com/souravsahums/unirating/issues
+Project-URL: Source, https://github.com/souravsahums/unirating
+Author-email: Sourav Sahu <souravsahu@duck.com>
+License: MIT License
+        
+        Copyright (c) 2026 Sourav Sahu
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: bayesian,chess,chess.com,elo,fide,glicko,lichess,meta-analysis,rating,sensor-fusion
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment :: Board Games
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: hypothesis>=6; extra == 'test'
+Requires-Dist: pytest-cov>=4; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# unirating
+
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> Author: **Sourav Sahu** ([@souravsahums](https://github.com/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](docs/derivation.md).
+Citations: [docs/citations.md](docs/citations.md).
+
+---
+
+## Install
+
+```bash
+pip install unirating
+```
+
+Zero runtime dependencies. Python 3.9+.
+
+---
+
+## Quick start
+
+```python
+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:
+
+```python
+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:
+
+```python
+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`](src/unirating/fusion.py) | The main entry point — call this. |
+| [`unirating.Rating`](src/unirating/models.py) | Immutable `(value, sigma)` measurement. |
+| [`unirating.Prior`](src/unirating/models.py) | Gaussian prior over latent skill. Defaults to $\mathcal N(1500, 350^2)$. |
+| [`unirating.Calibration`](src/unirating/calibration.py) | Affine map source ↔ FIDE. Defaults per time control. |
+| [`unirating.TimeControl`](src/unirating/calibration.py) | `BULLET`, `BLITZ`, `RAPID`, `CLASSICAL`. |
+| [`unirating.FusionResult`](src/unirating/models.py) | `(rating, sigma, ci95, contributions, used_sources, …)`. |
+| `unirating` (CLI) | One-shot fusion from the shell. |
+
+---
+
+## CLI
+
+```bash
+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](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](docs/citations.md)). You can override per call:
+
+```python
+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/](tests/) for the formal coverage.
+
+---
+
+## Citation
+
+If you use this package in academic work, please cite:
+
+```bibtex
+@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](LICENSE). Copyright © 2026 Sourav Sahu.

unirating-0.1.0/README.md

@@ -0,0 +1,174 @@
+# unirating
+
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> Author: **Sourav Sahu** ([@souravsahums](https://github.com/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](docs/derivation.md).
+Citations: [docs/citations.md](docs/citations.md).
+
+---
+
+## Install
+
+```bash
+pip install unirating
+```
+
+Zero runtime dependencies. Python 3.9+.
+
+---
+
+## Quick start
+
+```python
+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:
+
+```python
+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:
+
+```python
+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`](src/unirating/fusion.py) | The main entry point — call this. |
+| [`unirating.Rating`](src/unirating/models.py) | Immutable `(value, sigma)` measurement. |
+| [`unirating.Prior`](src/unirating/models.py) | Gaussian prior over latent skill. Defaults to $\mathcal N(1500, 350^2)$. |
+| [`unirating.Calibration`](src/unirating/calibration.py) | Affine map source ↔ FIDE. Defaults per time control. |
+| [`unirating.TimeControl`](src/unirating/calibration.py) | `BULLET`, `BLITZ`, `RAPID`, `CLASSICAL`. |
+| [`unirating.FusionResult`](src/unirating/models.py) | `(rating, sigma, ci95, contributions, used_sources, …)`. |
+| `unirating` (CLI) | One-shot fusion from the shell. |
+
+---
+
+## CLI
+
+```bash
+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](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](docs/citations.md)). You can override per call:
+
+```python
+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/](tests/) for the formal coverage.
+
+---
+
+## Citation
+
+If you use this package in academic work, please cite:
+
+```bibtex
+@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](LICENSE). Copyright © 2026 Sourav Sahu.

unirating-0.1.0/docs/citations.md

@@ -0,0 +1,126 @@
+# Citations
+
+The math in this package is classical; what is novel is the application to chess rating fusion across platforms. Below are the primary sources for each component of the derivation, plus the empirical sources for the default calibration constants.
+
+---
+
+## 1. Rating systems
+
+### FIDE Elo
+- **FIDE Handbook B.02 — FIDE Rating Regulations** (current edition).
+  <https://handbook.fide.com/chapter/B022017>
+- **Elo, A. E.** (1978). *The Rating of Chessplayers, Past and Present.* Arco Publishing.
+
+### Glicko / Glicko-2
+- **Glickman, M. E.** (1995). The Glicko system. Boston University.
+  <http://www.glicko.net/glicko/glicko.pdf>
+- **Glickman, M. E.** (2012). Example of the Glicko-2 system. Boston University.
+  <http://www.glicko.net/glicko/glicko2.pdf>
+- **Glickman, M. E.** (1999). Parameter estimation in large dynamic paired comparison experiments. *Journal of the Royal Statistical Society: Series C (Applied Statistics)*, 48(3), 377–394.
+
+### Chess.com rating system
+- Chess.com — *Chess.com Ratings.* <https://support.chess.com/en/articles/8569091-chess-com-ratings>
+  (States that Chess.com Live uses Glicko, Daily uses Glicko-2.)
+
+### Lichess rating system
+- Lichess — *Lichess Ratings.* <https://lichess.org/page/rating-systems>
+  (States that all Lichess ratings are Glicko-2, with the RD shown on every profile and exposed by the API.)
+- Lichess API reference. <https://lichess.org/api>
+
+---
+
+## 2. Cross-platform rating comparisons (defaults for $\alpha, \beta$)
+
+There is no single authoritative regression. The defaults in `unirating/calibration.py` are consensus values from the following long-running community sources, cross-checked against each other:
+
+- **Lichess FAQ** — *"What about my Lichess rating compared to others?"*
+  <https://lichess.org/faq#rating-comparison>
+  (Notes that Lichess ratings run hotter than FIDE; the gap widens at faster time controls.)
+- **Chess.com Forums & Help — Rating comparison threads** (community-maintained
+  conversion tables, e.g. <https://www.chess.com/article/view/chess-ratings---how-they-work>).
+- **r/chess rating-comparison megathreads**, regularly updated, e.g.
+  <https://www.reddit.com/r/chess/comments/qewqtq/the_difference_between_fide_chesscom_and_lichess/>
+  (typical values: FIDE Rapid ≈ Chess.com Rapid − 100, FIDE Rapid ≈ Lichess Rapid − 250).
+- **Sonas, J.** (2002). *The Sonas Rating Formula — Better than Elo?* ChessBase.
+  <https://en.chessbase.com/post/the-sonas-rating-formula-better-than-elo->
+- **Universal Rating System (URS)** — Maxime Rischard & Jeff Sonas, used by the
+  Grand Chess Tour. Combines a player's Classical / Rapid / Blitz FIDE ratings
+  into one. Spirit-precursor to this package, but stays inside FIDE.
+  <https://universalrating.com/>
+
+---
+
+## 3. Inverse-variance weighting / meta-analysis
+
+The §3.1 formula is textbook **fixed-effect meta-analysis**:
+
+- **Cochran, W. G.** (1937). Problems arising in the analysis of a series of similar experiments. *Journal of the Royal Statistical Society*, 4(1), 102–118.
+  (Earliest formal statement of the inverse-variance weighted mean.)
+- **DerSimonian, R., & Laird, N.** (1986). Meta-analysis in clinical trials. *Controlled Clinical Trials*, 7(3), 177–188.
+  (The standard reference for inverse-variance combination of independent estimates.)
+- **Hartung, J., Knapp, G., & Sinha, B. K.** (2008). *Statistical Meta-Analysis with Applications.* Wiley.
+
+---
+
+## 4. Gauss–Markov / BLUE optimality
+
+The §3.1 proof that inverse-variance weights minimise variance among linear unbiased combinations is a special case of the Gauss–Markov theorem:
+
+- **Gauss, C. F.** (1823). *Theoria combinationis observationum erroribus minimis obnoxiae.* (Reprinted in *Werke*, vol. 4.)
+- **Markov, A. A.** (1900). *Wahrscheinlichkeitsrechnung.* (German translation, Teubner.)
+- **Rao, C. R.** (1973). *Linear Statistical Inference and Its Applications* (2nd ed.). Wiley. (§4a — Gauss–Markov; §5a — Cramér–Rao bound for the Gaussian case.)
+- **Lehmann, E. L., & Casella, G.** (1998). *Theory of Point Estimation* (2nd ed.). Springer. (§4.1 — MMSE estimators.)
+
+---
+
+## 5. Gaussian–Gaussian conjugacy (the Bayesian extension, §3.2)
+
+The closed-form posterior for a Gaussian likelihood with a Gaussian prior is one of the oldest results in Bayesian statistics:
+
+- **DeGroot, M. H.** (1970). *Optimal Statistical Decisions.* McGraw-Hill. (§9.5 — Gaussian–Gaussian updates in precision form.)
+- **Murphy, K. P.** (2007). *Conjugate Bayesian analysis of the Gaussian distribution.* Technical note, University of British Columbia.
+  <https://www.cs.ubc.ca/~murphyk/Papers/bayesGauss.pdf>
+- **Gelman, A., Carlin, J. B., Stern, H. S., Dunson, D. B., Vehtari, A., & Rubin, D. B.** (2013). *Bayesian Data Analysis* (3rd ed.). CRC Press. (§2.5 — normal model with known variance.)
+
+---
+
+## 6. Related work — latent-skill rating models
+
+While this package fuses *existing* ratings rather than computing ratings from games directly, the latent-skill philosophy is shared with:
+
+- **Herbrich, R., Minka, T., & Graepel, T.** (2007). *TrueSkill™: A Bayesian Skill Rating System.* In *Advances in Neural Information Processing Systems 19* (pp. 569–576). MIT Press.
+- **Coulom, R.** (2008). Whole-history rating: A Bayesian rating system for players of time-varying strength. In *Computers and Games* (Lecture Notes in Computer Science, vol. 5131, pp. 113–124). Springer.
+- **Weng, R. C., & Lin, C.-J.** (2011). A Bayesian approximation method for online ranking. *Journal of Machine Learning Research*, 12, 267–300.
+
+---
+
+## 7. Robustness / heavy-tailed alternatives (§9 caveats)
+
+If you suspect the Gaussian-noise assumption is too tight (e.g. one source is clearly wrong), swap it for one of:
+
+- **Huber, P. J.** (1964). Robust estimation of a location parameter. *Annals of Mathematical Statistics*, 35(1), 73–101.
+- **Lange, K. L., Little, R. J. A., & Taylor, J. M. G.** (1989). Robust statistical modeling using the t distribution. *Journal of the American Statistical Association*, 84(408), 881–896.
+
+---
+
+## 8. Software references
+
+- **NumPy / SciPy** — the formula is closed-form so no numerical libraries are needed at runtime. For dataset-level fitting of $(\alpha, \beta)$ a least-squares regression from `numpy.polyfit` or `scipy.stats.linregress` is sufficient.
+- **Hypothesis** — Maclver, D. R., et al. <https://hypothesis.readthedocs.io/> (used for the property-based tests).
+
+---
+
+## Citation of this package
+
+If you use `unirating` in academic work, please cite:
+
+```bibtex
+@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},
+}
+```