elo v0.1.0 Elo

The Elo module is used to calculate Elo ratings.

The Elo rating system is used to represent relative skill levels in head-to-head competitive games. A “match” pairs two ratings along with a result (win, loss, or draw); based on the expected result, points are transferred between the two parties.

The point exchange in an Elo match is always zero-sum (all points subtracted from one party are awarded to the other); therefore, it is not possible to improve a rating with a loss. A larger difference between the actual and expected result will result in a larger point transfer (e.g., an “upset,” where the heavily favored rating loses).

The primary function for calculating Elo ratings is rate/4. You can also get the expected result for a given match with expected_result/2.

K-factor

The “K-factor” is a constant applied in the Elo formula that determines the sensitivity (amount of swing) in a given match. The higher the k-factor, the more points will be exchanged. Generally, the K-factor can decrease over time as a rating approaches its “true” value.

Summary

Functions

expected_result(player, opponent)

Calculate the expected result for the given player and opponent ratings

rate(player, opponent, result, opts \\ [])

Calculate new Elo ratings for two given existing ratings (player and opponent) and a given result

Functions

expected_result(player, opponent)

Calculate the expected result for the given player and opponent ratings.

The expected result is expressed as a winning percentage (probability that player will win, plus half the probability of a draw).

Examples

iex(1)> Elo.expected_result(1000, 500)
0.9467597847979775

rate(player, opponent, result, opts \\ [])

Calculate new Elo ratings for two given existing ratings (player and opponent) and a given result.

Result must be :win (first rating wins), :draw (a draw), or :loss (first rating loses). These are converted to the Elo values 1.0, 0.5, and 0.0, respectively. You can also pass the numeric value directly.

Available options for opts:

round: One of :up, :down, or true (half-up), or false. By default, rounding occurs only when both player and opponent are passed as integers. Using the up or down method consistently will lead to point drift, as point exchange is no longer zero-sum.
k_factor: Value to use for the K-factor (see module documentation for an explanation). If not specified, @default_k_factor is used.

Examples

iex> Elo.rate 1600, 1200, :win
{1602, 1198}
iex> Elo.rate 1238.0, 1656.5, :loss
{1236.0204093743623, 1658.4795906256377}
iex> Elo.rate 1238.0, 1656.5, :draw, round: true
{1236, 1658}
iex> Elo.rate 1238.0, 1656.5, :draw, round: true, k_factor: 100
{1230, 1665}