glicko

README

Package glicko implements the player's strength estimate based on the Glicko-2
rating system.

Originally designed as an improvement over existing rating systems, Glicko-2 has
become a popular choice among game developers.

One potential caveat when using the stock Glicko-2 system is that it expects
a collection of games within a rating period to apply the rating algorithm.

This implementation aims to address that limitation by allowing the player's
rating to be estimated sequentially based on individual match outcomes rather
than in batches. To achieve this, the periodFraction parameter was introduced
into the Estimate function. As a result, rating, deviation, and volatility
evolve smoothly when matches occur at arbitrary moments instead of being
grouped into fixed rating periods.

Another notable modification is the introduction of bounds on the player's rating,
deviation, and volatility. All system parameters are user-defined, making the
system both flexible and safe.

Usage

To install glicko, run go get:

go get github.com/treepeck/glicko

Here is a simple example (based on the original Glicko-2 paper):

package main

import (
	"fmt"

	"github.com/treepeck/glicko"
)

func main() {
	c := glicko.Converter{
		Rating:    glicko.DefaultRating,
		Deviation: glicko.DefaultDeviation,
		Factor:    glicko.DefaultFactor,
	}

	// Initial player's strength.
	s := glicko.Strength{
		Mu:    c.Rating2Mu(glicko.DefaultRating),
		Phi:   c.Deviation2Phi(200),
		Sigma: glicko.DefaultVolatility,
	}

	// Match outcomes.
	outcomes := []glicko.Outcome{
		{Mu: c.Rating2Mu(1400), Phi: c.Deviation2Phi(30), Score: 1},
		{Mu: c.Rating2Mu(1550), Phi: c.Deviation2Phi(100), Score: 0},
		{Mu: c.Rating2Mu(1700), Phi: c.Deviation2Phi(300), Score: 0},
	}

	// Initialize the strength estimator.
	e := glicko.Estimator{
		MinMu: c.Rating2Mu(10), MaxMu: c.Rating2Mu(5000),
		MinPhi:   c.Deviation2Phi(30),
		MaxPhi:   c.Deviation2Phi(glicko.DefaultDeviation),
		MinSigma: 0.04, MaxSigma: 0.08,
		Tau: glicko.DefaultTau, Epsilon: glicko.DefaultEpsilon,
	}

	// Estimate player's rating based on game outcomes sequantially.
	// New rating can be calculated immediately after each match.
	for i := range outcomes {
		e.Estimate(&s, outcomes[i], 1)
	}

	// Those values slighly (+- 1 rating point) differ from the original
	// Glicko-2 example.  This is because the implementation processes each
	// game sequentially and the original algorithm is not linear.  The
	// difference is negligable is most cases.

	// Prints "1463.7884049111285"
	fmt.Println(int(c.Mu2Rating(s.Mu)))
	// Prints "151.87316169372073"
	fmt.Println(c.Phi2Deviation(s.Phi))
	// Prints "0.05999440707992557"
	fmt.Println(s.Sigma)
}

Acknowledgments

https://www.glicko.net/glicko/glicko2.pdf

https://blog.hypersect.com/the-online-skill-ranking-of-inversus-deluxe/

Documentation

Overview

This code names variables and functions according to the conventions used in Professor Mark E. Glickman's paper:

• mu: the player's strength estimate (rating converted to the Glicko-2 scale).
• phi: the rating deviation converted to the Glicko-2 scale. Phi defines the bounds of the 95% confidence interval, where the lower bound is mu-2*phi, and the upper bound is mu+2*phi.
• sigma: the degree of expected fluctuation in a player's rating. This value is high when a player has erratic performances, and low when the player performs at a consistent level.
• tau: the volatility change constraint.
• g: a weighting function that reduces the influence of enemies with high phi values.
• e: the expected score against an enemy with the specified mu and phi.
• v: the updated player's mu based only on expected game outcomes.
• delta: the estimated value of the updated player's mu based on actual game outcomes.

Index

• Constants
• type Converter
  • func (c Converter) Deviation2Phi(deviation float64) float64
  • func (c Converter) Mu2Rating(mu float64) float64
  • func (c Converter) Phi2Deviation(phi float64) float64
  • func (c Converter) Rating2Mu(rating float64) float64
• type Estimator
  • func (e Estimator) Estimate(s *Strength, o Outcome, periodFraction float64)
  • func (e Estimator) Validate(s *Strength)
• type Outcome
• type Strength

Constants

const (
	DefaultRating = 1500
	// This value can also be an upper bound, since the system cannot be less
	// uncertain about a player's rating than it is for an unrated player.
	DefaultDeviation  = 350
	DefaultVolatility = 0.06
	DefaultTau        = 0.5
	DefaultFactor     = 173.7178
	DefaultEpsilon    = 0.000001
	// Default rating period duration in seconds.
	DefaultDuration = 60 * 60 * 24 * 7
)

Recommended values based on the original Glicko-2 paper.

Types

type Converter

type Converter struct {
	// Default rating of the unrated player.  Use [DefaultRating] constant for
	// the recommended value.
	Rating float64
	// Default deviation of the unrated player.  Use [DefaultDeviation] constant
	// for the recommended value.
	Deviation float64
	// Scaling factor.  Use [DefaultFactor] constant for the recommended value.
	Factor float64
}

Converter performs conversions between the Glicko-2 and traditional "Elo-style" rating scales. Internally all calculations to estimate the player's Strength are performed using the Glicko-2 scaled values.

func (Converter) Deviation2Phi

func (c Converter) Deviation2Phi(deviation float64) float64

Deviation2Phi converts deviation to the Glicko-2 scale.

func (Converter) Mu2Rating

func (c Converter) Mu2Rating(mu float64) float64

Mu2Rating converts mu to the "Elo-style" rating scale.

func (Converter) Phi2Deviation

func (c Converter) Phi2Deviation(phi float64) float64

Phi2Deviation converts phi to the "Elo-style" rating deviation scale.

func (Converter) Rating2Mu

func (c Converter) Rating2Mu(rating float64) float64

Rating2Mu converts rating to the Glicko-2 scale.

type Estimator

type Estimator struct {
	// Rating period duration in seconds.  Use [DefaultDuration] constant for
	// the recommended value.
	Duration uint64
	// Lower bound of the possible mu value.
	MinPhi float64
	// Upper bound of the possible mu value.
	MaxPhi float64
	// Lower bound of the possible phi value.
	MinMu float64
	// Upper bound of the possible phi value.
	MaxMu float64
	// Lower bound of the possible sigma value.
	MinSigma float64
	// Upper bound of the possible sigma value.
	MaxSigma float64
	// System variable.  Use [DefaultTau] constant for the recommended value.
	Tau float64
	// System variable.  Use [DefaultEpsilon] constant for the recommended value.
	Epsilon float64
}

Estimator performs calculations of the player's strength.

func (Estimator) Estimate

func (e Estimator) Estimate(s *Strength, o Outcome, periodFraction float64)

Estimate updates the player's Strength by analyzing:

• s: player's Strength at the onset of the rating period.
• o: Outcome of a single match withing a single rating period.
• periodFraction: fraction of a rating period that has elapsed since the last rating update.

The result of this function is validated.

func (Estimator) Validate

func (e Estimator) Validate(s *Strength)

Validate validates the [Srength] by checking if the values satisfy the established limits.

type Outcome

type Outcome struct {
	// Enemy's mu.
	Mu float64
	// Enemy's phi.
	Phi float64
	// Set score to 0 if the player lost the match, 0.5 for a draw, and 1 if
	// the player won.
	Score float64
}

Outcome represents a game information used to calculate the new player's rating. It stores only Glicko-2 scaled values which are used for internal calculations, hence all fields are unexported.

type Strength

type Strength struct {
	Mu    float64
	Phi   float64
	Sigma float64
}

Strength represents a player's strength estimate.