Exglicko2 (exglicko2 v0.2.1)
Tools for working with Glicko-2 ratings.
Players are represented by a Exglicko2.Rating
struct.
You can get a new, default struct with the new_player/0
function.
iex> Exglicko2.new_player()
%Exglicko2.Rating{value: 0.0, deviation: 2.0, volatility: 0.06}
Once your players have ratings, the games can begin! Game results are represented by a number ranging from zero to one, with a one representing a win, and a zero representing a loss.
Ratings are updated with a list of game results passed to the update_rating/3
function.
Game results are batched into a list of tuples, with the first element being the opponent's rating tuple,
and the second being the resulting score.
This function also accepts an optional system constant, which governs how much ratings are allowed to change.
This value must be between 0.4 and 1.2, and is 0.5 by default.
iex> player = Exglicko2.Rating.new(0.0, 1.2, 0.06)
iex> results = [
...> {Exglicko2.new_player(-0.6, 0.2, 0), 1},
...> {Exglicko2.new_player(0.3, 0.6, 0), 0},
...> {Exglicko2.new_player(1.2, 1.7, 0), 0}
...> ]
iex> Exglicko2.update_player(player, results, tau: 0.5)
%Exglicko2.Rating{value: -0.21522518921916625, deviation: 0.8943062104659615, volatility: 0.059995829968027437}
Here is some guidance on the optimal number of games to pass into the update_rating/3
function,
directly from the original paper:
The Glicko-2 system works best when the number of games in a rating period is moderate to large, say an average of at least 10-15 games per player in a rating period. The length of time for a rating period is at the discretion of the administrator.
If you use the older Glicko rating system,
you can convert a player back-and-forth using the Exglicko2.Rating.from_glicko/1
and Exglicko2.Rating.to_glicko/1
functions.
iex> Exglicko2.Rating.from_glicko({1500.0, 350, 0.06})
%Exglicko2.Rating{value: 0.0, deviation: 2.014761872416068, volatility: 0.06}
Link to this section Summary
Functions
Create a new player with a default rating.
Create a new player with the given rating.
Update a player's rating based on game results.
Updates a whole team of players with update_rating/3
.
Link to this section Functions
new_player()
Create a new player with a default rating.
new_player(rating, deviation, volatility)
Create a new player with the given rating.
update_player(player, results, opts \\ [])
Update a player's rating based on game results.
Each player is represented by a tuple of the player's rating, their rating deviation, and their rating volatility. Game results are batched into a list of tuples, with the first element being the opponent's values, and the second being the resulting score between zero and one.
You can also specify a system constant, called :tau
, which governs how much ratings are allowed to change.
This value must be between 0.4 and 1.2, and the default is 0.5.
Example
A player with a rating of 0.0, a deviation of 1.2, and a volatility of 0.06 plays three games.
- Against the first opponent, they win. Thus the score is 1.
- Against the second opponent, they lose. Thus the score is 0.
- Against the third opponent, they lose again. Thus the score is 0.
The result is that the player's score drops to -0.2, their deviation drops to 0.9, and their volatility drops slightly.
iex> player = Exglicko2.Rating.new(0.0, 1.2, 0.06)
iex> results = [
...> {Exglicko2.Rating.new(-0.6, 0.2, 0.06), 1},
...> {Exglicko2.Rating.new(0.3, 0.6, 0.06), 0},
...> {Exglicko2.Rating.new(1.2, 1.7, 0.06), 0}
...> ]
iex> Exglicko2.update_player(player, results, tau: 0.5)
%Exglicko2.Rating{value: -0.21522518921916625, deviation: 0.8943062104659615, volatility: 0.059995829968027437}
update_team(team, results, opts \\ [])
Updates a whole team of players with update_rating/3
.
Instead of individual player structs, pass in lists of players, like this:
iex> team_one = [
...> Exglicko2.new_player(-0.6, 0.2, 0.06),
...> Exglicko2.new_player(0.3, 0.6, 0.06),
...> Exglicko2.new_player(1.2, 1.7, 0.06)
...> ]
...> team_two = [
...> Exglicko2.new_player(-0.6, 0.2, 0.06),
...> Exglicko2.new_player(0.3, 0.6, 0.06),
...> Exglicko2.new_player(1.2, 1.7, 0.06)
...> ]
...> results = [
...> {team_two, 1}
...> ]
...> Exglicko2.update_team(team_one, results)
[
%Exglicko2.Rating{
value: -0.5727225148150104,
deviation: 0.20801152963424144,
volatility: 0.05999777767142373
},
%Exglicko2.Rating{
value: 0.45366492480429327,
deviation: 0.581562104768686,
volatility: 0.059997452826507966
},
%Exglicko2.Rating{
value: 1.7340823171025699,
deviation: 1.3854013493398154,
volatility: 0.05999869242065375
}
]