icu_ratings 0.2.0

data/.autotest

@@ -0,0 +1,8 @@
+#
+# Since the default autotest mappings in gems/rspec-<version>/lib/autotest/rspec.rb
+# assume lib/ and spec/ are structured in the same way, we have to replace them.
+#
+Autotest.add_hook :initialize do |at|
+  at.remove_mapping %r%^lib/(.*)\.rb$%
+  at.add_mapping(%r%^lib/icu_ratings/(.*)\.rb$%) { |_, m| "spec/#{m[1]}_spec.rb" }
+end

data/.gitignore

@@ -0,0 +1,3 @@
+rdoc
+pkg
+tmp

data/LICENCE

@@ -0,0 +1,22 @@
+Copyright (c) 2010 Mark Orr
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,64 @@
+= ICU Chess Ratings
+
+For calculating the Elo ratings of players in a chess tournament. The software is a port
+the Irish Chess Union's existing rating software written in Microsoft Visual Basic and
+intended to replace it in the near future.
+
+The rating calculations are identical to FIDE's for tournaments that consist entirely
+of established players (with the exception of player bonuses, which can be turned off).
+However, the ICU has it's own peculiar way of dealing with unrated players (players
+with only a provisional rating or without any prior rating) which is not the same as
+FIDE's.
+
+== Install
+
+  sudo gem install icu_ratings
+
+== Usage
+
+First, create a new ICU::RatedTournament object:
+
+  t = ICU::RatedTournament.new(:desc => "Irish Championships 2008")
+
+Then add players (see ICU::RatedPlayer for details):
+
+  t.add_player(1, :rating => 2534, :desc => 'Alexander Baburin (7085)', :kfactor => 16)
+  t.add_player(2, :rating => 2525, :desc => 'Alon Greenfeld')  # foreign (non-ICU) rated player
+  t.add_player(8, :rating => 2084, :desc => 'Anthony Fox (456)', :kfactor => 24)
+  # ...
+
+Then add results (see ICU::RatedResult for details):
+
+  t.add_result(1, 1, 8, 'W')    # players 1 and 8 played in round 1, player 1 won
+  t.add_result(4, 2, 1, 'D')    # players 1 and 2 drew in round 4
+  # ...
+
+Then call the <em>rate!</em> method.
+
+  t.rate!
+
+If no exceptions have been raised yet, the tournament is now rated and the
+main results of the rating calculations can be extracted by querying the
+previously created player objects:
+
+  (1..32).each do |num|
+    player = t.player(num)
+    puts "Name: #{t.desc}"
+    puts "Score: #{p.score}/#{p.results.size}"
+    puts "New Rating: #{p.new_rating.round}"
+    puts "Performance Rating: #{p.performance.round}"
+  end
+  
+  # Name: Alexander Baburin (7085)
+  # Score: 8.0/9
+  # New Rating: 2558
+  # Performance Rating: 2607
+  # ...
+
+See ICU::RatedPlayer for further details. Further breakdown of the rating calculations
+are available, if desired, from the results belonging to each player. See ICU::RatedResult
+for more details.
+
+== Author
+
+Mark Orr, Irish Chess Union (ICU[http://icu.ie]) rating officer.

data/Rakefile

@@ -0,0 +1,44 @@
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name         = "icu_ratings"
+    gem.summary      = "For rating chess tournaments."
+    gem.description  = "Build an object that represents a chess tournament then get it to calculate ratings of all the players."
+    gem.homepage     = "http://github.com/sanichi/icu_ratings"
+    gem.authors      = ["Mark Orr"]
+    gem.email        = "mark.j.l.orr@googlemail.com"
+    gem.files        = FileList['[A-Z]*', '{lib,spec}/**/*', '.gitignore', '.autotest']
+    gem.has_rdoc     = true
+    gem.rdoc_options = ["--charset", "UTF-8"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install jeweler."
+end
+
+task :default => :spec
+
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+  spec.spec_opts = ['--colour --format nested']
+end
+
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "ICU Ratings #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION.yml

@@ -0,0 +1,5 @@
+--- 
+:patch: 0
+:build: 
+:major: 0
+:minor: 2

data/lib/icu_ratings/player.rb

@@ -0,0 +1,264 @@
+module ICU
+
+=begin rdoc
+
+== Adding Players to Tournaments
+
+You don't directly create players, rather you add them to tournaments with the _add_player_ method.
+
+  t = ICU::RatedTournament.new
+  t.add_player(1)
+
+There is only one mandatory parameter - the player number - which can be any integer value
+except player numbers must be unique in each tournament:
+
+  t.add_player(2)    # fine
+  t.add_player(2)    # attempt to add a second player with the same number - exception!
+
+== Retrieving Players from Tournaments
+
+Player objects can be retrieved from ICU::RatedTournament objects with the latter's _player_ method
+in conjunction with the appropriate player number:
+
+  p = t.player(2)
+  p.num              # 2
+
+Or the player object can be saved from the return value from _add_player_:
+
+  p = t.add_player(-2)
+  p.num             # -2
+
+If the number supplied to _player_ is an invalid player number, the method returns _nil_.
+
+Different types of players are signalled by different combinations of the three optional
+parameters: _rating_, _kfactor_ and _games_.
+
+== Full Ratings
+
+Rated players have a full rating and a K-factor and are added by including valid values for those two parameters:
+
+  p = t.add_player(3, :rating => 2000, :kfactor => 16)
+  p.type             # :rated
+
+== Provisional Ratings
+
+Players that don't yet have a full rating but do have a provisonal rating estimated on some number
+of games played prior to the tournament are indicated by values for the _rating_ and _games_ parameters:
+
+  p = t.add_player(4, :rating => 1600, :games => 10)
+  p.type             # :provisional
+
+The value for the number of games should not exceed 19 since players with 20 or more games
+should have a full rating.
+
+== Fixed Ratings
+
+Players with fixed ratings just have a rating - no K-factor or number of previous games.
+When the tournament is rated, these players will have their tournament performance ratings
+calculated but the value returned by the method _new_rating_ will just be the rating they
+started with. Typically these are foreign players with FIDE ratings who are not members of
+the ICU and for whom ICU ratings are not desired.
+
+  p = t.add_player(6, :rating => 2500)
+  p.type             # :foreign
+
+== No Rating
+
+Unrated players who do not have any rated games at all are indicated by leaving out any values for
+_rating_, _kfactor_ or _games_.
+
+  p = t.add_player(5)
+  p.type             # :unrated
+  
+== Invalid Combinations
+
+The above four types of players (_rated_, _provisional_, _unrated_, _foreign_) are the only
+valid ones and any attempt to add players with other combinations of the attributes
+_rating_, _kfactor_ and _games_ will cause an exception. For example:
+
+  t.add_player(7, :rating => 2000, :kfactor => 16, :games => 10)   # exception! - cannot have both kfactor and games
+  t.add_plater(7, :kfactor => 16)                                  # exception! - kfactor makes no sense without a rating
+
+== String Input Values
+
+Although _rating_ and _kfactor_ are held as Float values and _games_ and _num_ (the player number) as Fixnums,
+all these parameters can be specified using strings, even when padded with whitespace.
+
+  p = t.add_player("  0  ", :rating => "  2000.5  ", :kfactor => "  20.5  ")
+  p.num            # 0 (Fixnum)
+  p.rating         # 2000.5 (Float)
+  p.kfactor        # 20.5 (Float)
+
+== Description Parameter
+
+There is one other optional parameter, _desc_ (short for "description"). It has no effect on player
+type or rating calculations and it cannot be used to retrieve players from a tournament (only the
+player number can be used for that). Its only use is to attach additional arbitary data to players.
+Any object can be used and descriptions don't have to be unique. The attribute's typical use,
+if it's used at all, is expected to be for player names in the form of String values.
+
+  t.add_player(8, :rating => 2800, :desc => 'Gary Kasparov (4100018)')
+  t.player(8).desc    # "Gary Kasparov (4100018)"
+
+== After the Tournament is Rated
+
+After the <em>rate!</em> method has been called on the ICU::RatedTournament object, the results
+of the rating calculations are available via various methods of the player objects:
+_new_rating_, _rating_change_, _performance_, _expected_score_.
+
+== Unrateable Players
+
+If a tournament contains groups of provisonal or unrated players who play games
+only amongst themselves and not against any rated or foreign opponents, they can't
+be rated. This is indicated by a value of _nil_ returned from the _new_rating_
+method.
+
+=end
+
+  class RatedPlayer
+    attr_reader :num, :rating, :kfactor, :games
+    attr_accessor :desc
+
+    # After the tournament has been rated, this is the player's new rating. For rated players this is the old rating
+    # plus the _rating_change_. For provisional players it is their performance rating, including their previous
+    # games. For unrated players it is their tournament performance rating. For foreign players it is the same
+    # as their start _rating_.
+    def new_rating
+      full_rating? ? rating + rating_change : performance
+    end
+
+    # After the tournament has been rated, this is the difference between the old and new ratings for
+    # rated players, based on sum of expected scores in each games and the player's K-factor.
+    # Zero for all other types of players.
+    def rating_change
+      @results.inject(0.0) { |c, r| c + (r.rating_change || 0.0) }
+    end
+
+    # After the tournament has been rated, this returns the sum of expected scores over all results.
+    # Although this is calculated for provisional and unrated players it is not used to estimate their
+    # new ratings. For rated players, this number times the K-factor gives the change in rating.
+    def expected_score
+      @results.inject(0.0) { |e, r| e + (r.expected_score || 0.0) }
+    end
+    
+    # After the tournament has been rated, this returns the tournament rating performance for
+    # rated, unrated and foreign players. For provisional players it returns a weighted average
+    # of the player's tournament performance and their previous games. For provisional and
+    # unrated players it is the same as _new_rating_.
+    def performance
+      @performance
+    end
+    
+    # Returns an array of the player's results (ICU::RatedResult) in round order.
+    def results
+      @results
+    end
+
+    # The sum of the player's scores in all rounds in which they have a result.
+    def score
+      @results.inject(0.0) { |e, r| e + r.score }
+    end
+    
+    # Returns the type of player as a symbol: one of _rated_, _provisional_, _unrated_ or _foreign_.
+    def type
+      @type
+    end
+    
+    def add_result(result) # :nodoc:
+      raise "invalid result (#{result.class})" unless result.is_a? ICU::RatedResult
+      raise "players cannot score results against themselves" if self == result.opponent
+      duplicate = false
+      @results.each do |r|
+        if r.round == result.round
+          raise "inconsistent result in round #{r.round}" unless r == result
+          duplicate = true
+        end
+      end
+      return if duplicate
+      @results << result
+      @results.sort!{ |a,b| a.round <=> b.round }
+    end
+   
+    def rate! # :nodoc:
+      @results.each { |r| r.rate!(self) }
+    end
+
+    def full_rating? # :nodoc:
+      @type == :rated || @type == :foreign
+    end
+
+    def init_performance # :nodoc:
+      @performance = nil
+      @estimated_performance = nil
+    end
+
+    def estimate_performance # :nodoc:
+      new_games, new_performance = results.inject([0,0.0]) do |sum, result|
+        opponent = result.opponent
+        if opponent.full_rating? || opponent.performance
+          sum[0]+= 1
+          sum[1]+= (opponent.full_rating? ? opponent.rating : opponent.performance) + (2 * result.score - 1) * 400.0
+        end
+        sum
+      end
+      if new_games > 0
+        old_games, old_performance = type == :provisional ? [games, games * rating] : [0, 0.0]
+        @estimated_performance = (new_performance + old_performance) / (new_games + old_games)
+      end
+    end
+
+    def update_performance # :nodoc:
+      stable = case
+      when  @performance &&  @estimated_performance then (@performance - @estimated_performance).abs < 0.5
+      when !@performance && !@estimated_performance then true
+      else false
+      end
+      @performance = @estimated_performance if @estimated_performance
+      stable
+    end
+
+    def ==(other) # :nodoc:
+      return false unless other.is_a? ICU::RatedPlayer
+      num == other.num
+    end
+
+    private
+
+    def initialize(num, opt={}) # :nodoc:
+      self.num = num
+      [:rating, :kfactor, :games, :desc].each { |atr| self.send("#{atr}=", opt[atr]) unless opt[atr].nil? }
+      @results = []
+      @type = deduce_type
+    end
+
+    def num=(num)
+      @num = num.to_i
+      raise "invalid player num (#{num})" if @num == 0 && !num.to_s.match(/^\s*\d/)
+    end
+
+    def rating=(rating)
+      @rating = rating.to_f
+      raise "invalid player rating (#{rating})" if @rating == 0.0 && !rating.to_s.match(/^\s*\d/)
+    end
+
+    def kfactor=(kfactor)
+      @kfactor = kfactor.to_f
+      raise "invalid player k-factor (#{kfactor})" if @kfactor <= 0.0
+    end
+
+    def games=(games)
+      @games = games.to_i
+      raise "invalid number of games (#{games})" if @games <= 0 || @games >= 20
+    end
+
+    def deduce_type
+      case
+        when  @rating &&  @kfactor && !@games then :rated
+        when  @rating && !@kfactor &&  @games then :provisional
+        when  @rating && !@kfactor && !@games then :foreign
+        when !@rating && !@kfactor && !@games then :unrated
+        else  raise "invalid combination of player attributes"
+      end
+    end
+  end
+end

data/lib/icu_ratings/result.rb

@@ -0,0 +1,172 @@
+module ICU
+
+=begin rdoc
+
+== Adding Results to Tournaments
+
+You don't create results directly with a constructor, instead, you add them to a tournament
+using the _add_result_ method, giving the round number, the player numbers and the score
+of the first player relative to the second:
+
+  t = ICU::RatedTournament.new
+  t.add_player(10)
+  t.add_player(20)
+  t.add_result(1, 10, 20, 'W')
+
+The above example expresses the result that in round 1 player 10 won against player 20. An exception is raised
+if either of the two players does not already exist in the tournament, if either player already has a game
+with another opponent in that round or if the two players already have a different result against each other
+in that round. Note that the result is added to both players: in the above example a win in round 1 against
+player 20 is added to player 10's results and a loss against player 10 in round 1 is added to player 20's results.
+It's OK (but unnecessary) to add the same result again from the other player's prespective as long as
+the score is consistent.
+
+  t.add_result(1, 20, 10, 'L')   # unnecessary (nothing would change) but would not cause an exception
+  t.add_result(1, 20, 10, 'D')   # inconsistent result - would raise an exception
+
+== Specifying the Score
+
+The method _score_ will always return a Float value (either 0.0, 0.5 or 1.0).
+When specifying a score using the _add_result_ of ICU::Tourmanent the same values
+can be used as can other, equally valid alternatives:
+
+win:: "1", "1.0", "W", "w" (String), 1 (Fixnum), 1.0 (Float)
+loss:: "0", "0.0", "L", "l" (String), 0 (Fixnum), 0.0 (Float)
+draw:: "½", "D", "d" (String), 0.5 (Float)
+
+Strings padded with whitespace also work (e.g. "  1.0  " and "  W  ").
+
+== Specifying the Players
+
+As described above, one way to specify the two players is via player numbers. Equally possible is player objects:
+
+  t = ICU::RatedTournament.new
+  p = t.add_player(10)
+  q = t.add_plater(20)
+  t.add_result(1, p, q, 'W')
+
+Or indeed (although this is unnecessary):
+
+  t = ICU::RatedTournament.new
+  t.add_player(10)
+  t.add_plater(20)
+  t.add_result(1, t.player(10), t.player(20), 'W')
+
+A players cannot have a results against themselves:
+
+  t.add_player(2, 10, 10, 'D')   # exception!
+
+== Retrieving Results
+
+Results belong to players (ICU::RatedPlayer objects) and are stored in an array accessed by the method _results_.
+Each result has a _round_ number, an _opponent_ object (also an ICU::RatedPlayer object) and a _score_ (1.0, 0.5 or 0.0):
+
+  p = t.player(10)
+  p.results.size      # 1
+  r = p.results[0]
+  r.round             # 1
+  r.opponent.num      # 20
+  r.score             # 1.0 (Float)
+
+The _results_ method returns results in round order, irrespective of what order they were added in:
+
+  t = ICU::RatedTournament.new
+  [0,1,2,3,4].each { |num| t.add_player(num) }
+  [3,1].each { |rnd| t.add_result(rnd, 0, rnd, 'W') }
+  [4,2].each { |rnd| t.add_result(rnd, 0, rnd, 'L') }
+  t.player(0).results.map{ |r| r.round }.join(',')      # "1,2,3,4"
+
+== Unrated Results
+
+Results that are not for rating, such as byes, walkovers and defaults, should not be
+added to the tournament. Instead, players can simply have no results for certain rounds.
+Indeed, it's even valid for players not to have any results at all (although, in that
+case, for those players, no new rating can be calculated from the tournament).
+
+== After the Tournament is Rated
+
+The main rating calculations are avaiable from player methods (see ICU::RatedPlayer)
+but additional details are available via methods of each player's individual results:
+_expected_score_, _rating_change_.
+
+=end
+
+  class RatedResult
+    # The round number.
+    def round
+      @round
+    end
+    
+    # The player's opponent (an instance of ICU::RatedPlayer).
+    def opponent
+      @opponent
+    end
+    
+    # The player's score in this game (1.0, 0.5 or 0.0).
+    def score
+      @score
+    end
+    
+    # After the tournament has been rated, this returns the expected score (between 0 and 1)
+    # for the player based on the rating difference with the opponent scaled by 400.
+    # The standard Elo formula is used: 1/(1 + 10^(diff/400)).
+    def expected_score
+      @expected_score
+    end
+    
+    # After the tournament has been rated, returns the change in rating due to this particular
+    # result. Only for rated players (returns _nil_ for other types of players). Computed from
+    # the difference between actual and expected scores multiplied by the player's K-factor.
+    # The sum of these changes is the overall rating change for rated players.
+    def rating_change
+      @rating_change
+    end
+    
+    def rate!(player) # :nodoc:
+      player_rating   = player.full_rating?   ? player.rating   : player.performance
+      opponent_rating = opponent.full_rating? ? opponent.rating : opponent.performance
+      if (player_rating && opponent_rating)
+        @expected_score = 1 / (1 + 10 ** ((opponent_rating - player_rating) / 400.0))
+        @rating_change  = (@score - @expected_score) * player.kfactor if player.type == :rated
+      end
+    end
+
+    def ==(other) # :nodoc:
+      return false unless other.round    == round
+      return false unless other.opponent == opponent
+      return false unless other.score    == score
+      true
+    end
+
+    def opponents_score # :nodoc:
+      1.0 - score
+    end
+
+    private
+
+    def initialize(round, opponent, score) # :nodoc:
+      self.round    = round
+      self.opponent = opponent
+      self.score    = score
+    end
+
+    def round=(round)
+      @round = round.to_i
+      raise "invalid round number (#{round})" if @round <= 0
+    end
+
+    def opponent=(opponent)
+      raise "invalid opponent class (#{opponent.class})" unless opponent.is_a? ICU::RatedPlayer
+      @opponent = opponent
+    end
+
+    def score=(score)
+      @score = case score.to_s.strip
+        when /^(1\.0|1|\+|W|w)$/ then 1.0
+        when /^(0\.5|½|\=|D|d)$/ then 0.5
+        when /^(0\.0|0|\-|L|l)$/ then 0.0
+        else raise "invalid score (#{score})"
+      end
+    end
+  end
+end