elogo

README

Elo for Go

Elo ranking system for Go (Golang) programming language.

Elo ranking system is a system for ranking players in a competitive environment, by calculating expected outcome in a match between two ranked players and their new ranks based on the outcome of a match. Can be used in head-to-head mathes, as well as team based matches.

Factors

There are two factors that affect how Elo works - K-factor and deviation.

Deviation controls how much the difference in ratings affects the expected outcome. The higher the number, the higher expected chance that a better rated player wins. The default deviation is 400.

K-factor controls how much points are gained/lost after the outcome of the match is known. The higher the factor, players rating is more affected. This is especially useful if you want to control point fluctuation based on number of games played. Players with less games played should have higher k-factor, because their early ranking doesn't necessarily replicate their skill level. The default k-factor is 32.

Documentation

Full documentation on GoDoc.

Sample usage

rankA := 1500
rankB := 1600
elo := NewElo() // or NewEloWithFactors(k, d) for custom factors

// Expected chance that A defeats B
// use ExpectedScoreWithFactors(rankA, rankB, deviation) to use custom factor for this method
elo.ExpectedScore(rankA, rankB) // 0.3599350001971149

// Results for A in the outcome of A defeats B
score := 1 // Use 1 in case A wins, 0 in case B wins, 0.5 in case of a draw
elo.RatingDelta(rankA, rankB, score) // 20
elo.Rating(rankA, rankB, score) // 1520
outcomeA, outcomeB := elo.Outcome(rankA, rankB, score)
outcomeA.Delta // 20
outcomeA.Rating // 1520
outcomeB.Delta // -20
outcomeB.Rating // 1580

All Elo methods have WithFactors variants, where you can override factors for that specific method call:

kFactor = 40
deviation := 800

elo := NewEloWithFactors(kFactor, deviation) // set default factors on elo struct

// override factors for indiviual methods
elo.ExpectedScoreWithFactors(rankA, rankB, deviation)
elo.RatingDeltaWithFactors(rankA, rankB, score, kFactor, deviation)
elo.RatingWithFactors(rankA, rankB, score, kFactor, deviation)
elo.OutcomeWithFactors(rankA, rankB, score, kFactor, deviation)

Documentation

Index

• Constants
• type Elo
  • func NewElo() *Elo
  • func NewEloWithFactors(k, d int) *Elo
  • func (e *Elo) ExpectedScore(ratingA, ratingB int) float64
  • func (e *Elo) ExpectedScoreWithFactors(ratingA, ratingB, d int) float64
  • func (e *Elo) Outcome(ratingA, ratingB int, score float64) (Outcome, Outcome)
  • func (e *Elo) OutcomeWithFactors(ratingA, ratingB int, score float64, k, d int) (Outcome, Outcome)
  • func (e *Elo) Rating(ratingA, ratingB int, score float64) int
  • func (e *Elo) RatingDelta(ratingA, ratingB int, score float64) int
  • func (e *Elo) RatingDeltaWithFactors(ratingA, ratingB int, score float64, k, d int) int
  • func (e *Elo) RatingWithFactors(ratingA, ratingB int, score float64, k, d int) int
• type Outcome

Constants

const (
	// K is the default K-Factor
	K = 32
	// D is the default deviation
	D = 400
)

Types

type Elo

type Elo struct {
	K int
	D int
}

Elo calculates Elo rating changes based on the configured factors.

func NewElo

func NewElo() *Elo

NewElo instantiates the Elo object with default factors. Default K-Factor is 32 Default deviation is 400

func NewEloWithFactors

func NewEloWithFactors(k, d int) *Elo

NewEloWithFactors instantiates the Elo object with custom factor values.

func (*Elo) ExpectedScore

func (e *Elo) ExpectedScore(ratingA, ratingB int) float64

ExpectedScore gives the expected chance that the first player wins

func (*Elo) ExpectedScoreWithFactors

func (e *Elo) ExpectedScoreWithFactors(ratingA, ratingB, d int) float64

ExpectedScoreWithFactors overrides default factors and gives the expected chance that the first player wins

func (*Elo) Outcome

func (e *Elo) Outcome(ratingA, ratingB int, score float64) (Outcome, Outcome)

Outcome gives an Outcome object for each player for the given score

func (*Elo) OutcomeWithFactors

func (e *Elo) OutcomeWithFactors(ratingA, ratingB int, score float64, k, d int) (Outcome, Outcome)

OutcomeWithFactors overrides default factors and gives an Outcome object for each player for the given score

func (*Elo) Rating

func (e *Elo) Rating(ratingA, ratingB int, score float64) int

Rating gives the new rating for the first player for the given score

func (*Elo) RatingDelta

func (e *Elo) RatingDelta(ratingA, ratingB int, score float64) int

RatingDelta gives the ratings change for the first player for the given score

func (*Elo) RatingDeltaWithFactors

func (e *Elo) RatingDeltaWithFactors(ratingA, ratingB int, score float64, k, d int) int

RatingDeltaWithFactors overrides default factors and gives the ratings change for the first player for the given score

func (*Elo) RatingWithFactors

func (e *Elo) RatingWithFactors(ratingA, ratingB int, score float64, k, d int) int

RatingWithFactors overrides default factors and gives the new rating for the first player for the given score

type Outcome

type Outcome struct {
	Delta  int
	Rating int
}

Outcome is a match result data for a single player.