iq-scm / elo

The Elo rating system is a method for calculating the relative skill levels of players in two-player games such as chess and Go.

Elo¶ ↑

From Wikipedia:

The Elo rating system is a method for calculating the relative skill levels of players in two-player games such as chess and Go. It is named after its creator Arpad Elo, a Hungarian-born American physics professor.

The Elo system was invented as an improved chess rating system, but today it is also used in many other games. It is also used as a rating system for multiplayer competition in a number of computer games, and has been adapted to team sports including association football, American college football and basketball, and Major League Baseball.

Links¶ ↑

• API documentation

• Source Code

Usage¶ ↑

You need to have at least two players that can play a game (duh).

bob  = Elo::Player.new
jane = Elo::Player.new(:rating => 1500)

Once you have players, you can register games in a variaty of ways. There is more than one way to do it, choose whatever works from your other code:

game1 = bob.wins_from(jane)
game2 = bob.loses_from(jane)
game3 = bob.plays_draw(jane)

game4 = bob.versus(jane)
game4.winner = jane

game5 = bob.versus(jane)
game5.loser = jane

game6 = bob.versus(jane)
game6.draw

game7 = bob.versus(jane)
game7.result = 1 # result is in perspective of bob, so bob wins

game8 = bob.versus(jane, :result => 0) # jane wins

You can get all kinds of info from a player:

bob.rating       # => 1080
bob.pro?         # => false
bob.starter?     # => true
bob.games_played # => 8
bob.games        # => [ game1, game2, ... game8 ]

Configuration¶ ↑

You can configure Elo in many ways. In it’s default configuration, it is configured in the same way as the FIDE (World Chess Foundation).

Altering settings to your liking is very easy and very flexible. You can even specify your own K-factor rules. Have a look at the Rdoc in the code for a complete reference.

Here is an example:

Elo.configure do |config|

  # Every player starts with a rating of 1000
  config.default_rating = 1000

  # A player is considered a pro, when he/she has more than 2400 points
  config.pro_rating_boundry = 2400

  # A player is considered a new, when he/she has played less than 30 games
  config.starter_boundry = 30

end

About the K-factor¶ ↑

The Elo rating system knows a variable called the “K-factor”. The K-factor is used to reward new talent and stableize the rating once a player is participating longer.

FIDE (the World Chess Foundation), gives players with less than 30 played games a K-factor of 25. Normal players get a K-factor of 15 and pro’s get a K-factor of 10. Once you reach a pro status, you’re K-factor never changes, even if your rating drops.

You need to provide Elo the amount of games played, their rating and their pro-status.

bob = Elo::Player.new(:games_played => 29, :rating => 2399, :pro => true)
bob.k_factor == 10

You can define your own K-factors by adding K-factor rules. This code will change the K-factor to 12, for every player that played less than 10 games, and 16 for everybody else.

Elo.configure do |config|
  config.k_factor(12) { games_played < 10 }
  config.default_k_factor = 16
  config.use_FIDE_settings = false
end

Installation¶ ↑

gem install elo

Note on Patches/Pull Requests¶ ↑

• Fork the project.

• Make your feature addition or bug fix.

• Add tests for it. This is important so I don’t break it in a future version unintentionally.

• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

• Send me a pull request. Bonus points for topic branches.

Copyright¶ ↑

Copyright © 2010 Iain Hecker. Released under the MIT License