icu_ratings 0.2.0

data/lib/icu_ratings/tournament.rb

@@ -0,0 +1,114 @@
+module ICU
+
+=begin rdoc
+
+== Creating Tournaments
+
+ICU::RatedTournament object are created directly.
+
+  t = ICU::RatedTournament.new
+
+They have one optional parameter called _:desc_ (short for description) the value of which can be
+any object but will, if utilized, typically be the name of the tournament as a string.
+
+  t = ICU::RatedTournament.new(:desc => "Irish Championships 2008")
+  puts t.desc                         # "Irish Championships 2008"
+
+== Rating Tournaments
+
+To rate a tournament, first add the players (see ICU::RatedPlayer for details):
+
+  t.add_player(1, :rating => 2534, :kfactor => 16)
+  # ...
+
+Then add the results (see ICU::RatedResult for details):
+
+  t.add_result(1, 1, 2, 'W')
+  # ...
+
+Then rate the tournament by calling the <em>rate!</em> method:
+
+  t.rate!
+
+Now the results of the rating calculations can be retrieved from the players in the tournement
+or their results. For example, player 1's new rating would be:
+
+  t.player(1).new_rating
+
+See ICU::RatedPlayer and ICU::RatedResult for more details.
+
+== Error Handling
+
+Some of the above methods have the potential to raise RuntimeError exceptions.
+In the case of _add_player_ and _add_result_, the use of invalid arguments
+would cause such an error. Theoretically, the <em>rate!</em> method could also throw an
+exception if the iterative algorithm it uses to estimate performance ratings
+of unrated players failed to converge. However, practical experience has shown that
+this is highly unlikely.
+
+Since exception throwing is how errors are signalled, you should arrange for them
+to be caught and handled in some suitable place in your code.
+
+=end
+
+  class RatedTournament
+    attr_accessor :desc
+
+    # Add a new player to the tournament. Returns the instance of ICU::RatedPlayer created.
+    # See ICU::RatedPlayer for details.
+    def add_player(num, args={})
+      raise "player with number #{num} already exists" if @player[num]
+      @player[num] = ICU::RatedPlayer.new(num, args)
+    end
+
+    # Add a new result to the tournament. Two instances of ICU::RatedResult are
+    # created. One is added to the first player and the other to the second player.
+    # The method returns _nil_. See ICU::RatedResult for details.
+    def add_result(round, player, opponent, score)
+      n1 = player.is_a?(ICU::RatedPlayer) ? player.num : player.to_i
+      n2 = opponent.is_a?(ICU::RatedPlayer) ? opponent.num : opponent.to_i
+      p1 = @player[n1] || raise("no such player number (#{n1})")
+      p2 = @player[n2] || raise("no such player number (#{n2})")
+      r1 = ICU::RatedResult.new(round, p2, score)
+      r2 = ICU::RatedResult.new(round, p1, r1.opponents_score)
+      p1.add_result(r1)
+      p2.add_result(r2)
+      nil
+    end
+
+    # Rate the tournament. Called after all players and results have been added.
+    def rate!
+      performance_ratings
+      players.each { |p| p.rate! }
+    end
+
+    # Return an array of all players, in order of player number.
+    def players
+      @player.keys.sort.map{ |num| @player[num] }
+    end
+
+    # Return a player (ICU::RatedPlayer) given a player number (returns _nil_ if the number is invalid).
+    def player(num)
+      @player[num]
+    end
+
+    private
+
+    # Create a new, empty (no players, no results) tournament.
+    def initialize(opt={})
+      [:desc].each { |atr| self.send("#{atr}=", opt[atr]) unless opt[atr].nil? }
+      @player = Hash.new
+    end
+    
+    def performance_ratings
+      @player.values.each { |p| p.init_performance }
+      stable, count = false, 0
+      while !stable && count < 30
+        @player.values.each { |p| p.estimate_performance }
+        stable = @player.values.inject(true) { |ok, p| p.update_performance && ok }
+        count+= 1
+      end
+      raise "performance rating estimation did not converge" unless stable
+    end
+  end
+end

data/lib/icu_ratings.rb

@@ -0,0 +1,6 @@
+# :enddoc:
+
+icu_ratings_files = Array.new
+icu_ratings_files.concat %w{tournament player result}
+
+icu_ratings_files.each { |file| require "icu_ratings/#{file}" }

data/spec/player_spec.rb

@@ -0,0 +1,180 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+module ICU
+  describe RatedPlayer do
+    context "#new - different types of players" do
+      before(:all) do
+        @r = ICU::RatedPlayer.new(1, :rating => 2000, :kfactor => 10.0)
+        @p = ICU::RatedPlayer.new(2, :rating => 1500, :games => 10)
+        @f = ICU::RatedPlayer.new(3, :rating => 2500)
+        @u = ICU::RatedPlayer.new(4)
+      end
+      
+      it "rated players have a rating and k-factor" do
+        @r.num.should     == 1
+        @r.rating.should  == 2000
+        @r.kfactor.should == 10.0
+        @r.games.should   be_nil
+        @r.type.should    == :rated
+        @r.full_rating?.should be_true
+      end
+      
+      it "provisionally rated players have a rating and number of games" do
+        @p.num.should     == 2
+        @p.rating.should  == 1500
+        @p.kfactor.should be_nil
+        @p.games.should   == 10
+        @p.type.should    == :provisional
+        @p.full_rating?.should be_false
+      end
+      
+      it "foreign players just have a rating" do
+        @f.num.should     == 3
+        @f.rating.should  == 2500
+        @f.kfactor.should be_nil
+        @f.games.should   be_nil
+        @f.type.should    == :foreign
+        @f.full_rating?.should be_true
+      end
+      
+      it "unrated players just have nothing other than their number" do
+        @u.num.should     == 4
+        @u.rating.should  be_nil
+        @u.kfactor.should be_nil
+        @u.games.should   be_nil
+        @u.type.should    == :unrated
+        @u.full_rating?.should be_false
+      end
+      
+      it "other combinations are invalid" do
+        [
+          { :games => 10 },
+          { :games => 10, :kfactor => 10 },
+          { :games => 10, :kfactor => 10, :rating  => 1000 },
+          { :kfactor => 10 },
+        ].each { |opts| lambda { ICU::RatedPlayer.new(1, opts) }.should raise_error(/invalid.*combination/i) }
+      end
+    end
+    
+    context "#new - miscellaneous" do
+      it "attribute values can be given by strings, even when space padded" do
+        p = ICU::RatedPlayer.new(' 1 ', :kfactor => ' 10.0 ', :rating => ' 1000 ')
+        p.num.should     == 1
+        p.kfactor.should == 10.0
+        p.rating.should  == 1000
+      end
+    end
+
+    context "restrictions, or lack thereof, on attributes" do
+      it "the player number can be zero or even negative" do
+        lambda { ICU::RatedPlayer.new(-1) }.should_not raise_error
+        lambda { ICU::RatedPlayer.new(0)  }.should_not raise_error
+      end
+
+      it "k-factors must be positive" do
+        lambda { ICU::RatedPlayer.new(1, :kfactor =>  0) }.should raise_error(/invalid.*factor/i)
+        lambda { ICU::RatedPlayer.new(1, :kfactor => -1) }.should raise_error(/invalid.*factor/i)
+      end
+
+      it "the rating can be zero or even negative" do
+        lambda { ICU::RatedPlayer.new(1, :rating =>  0) }.should_not raise_error
+        lambda { ICU::RatedPlayer.new(1, :rating => -1) }.should_not raise_error
+      end
+      
+      it "ratings are stored as floats but can be specified with an integer" do
+        ICU::RatedPlayer.new(1, :rating => 1234.5).rating.should == 1234.5
+        ICU::RatedPlayer.new(1, :rating => 1234.0).rating.should == 1234
+        ICU::RatedPlayer.new(1, :rating =>   1234).rating.should == 1234
+      end
+      
+      it "the number of games shoud not exceed 20" do
+        lambda { ICU::RatedPlayer.new(1, :rating => 1000, :games => 19) }.should_not raise_error
+        lambda { ICU::RatedPlayer.new(1, :rating => 1000, :games => 20) }.should raise_error
+        lambda { ICU::RatedPlayer.new(1, :rating => 1000, :games => 21) }.should raise_error
+      end
+      
+      it "a description, such as a name, but can be any object, is optional" do
+        ICU::RatedPlayer.new(1, :desc => 'Fischer, Robert').desc.should == 'Fischer, Robert'
+        ICU::RatedPlayer.new(1, :desc => 1).desc.should be_an_instance_of(Fixnum)
+        ICU::RatedPlayer.new(1, :desc => 1.0).desc.should be_an_instance_of(Float)
+        ICU::RatedPlayer.new(1).desc.should be_nil
+      end
+    end
+
+    context "results" do
+      before(:each) do
+        @p  = ICU::RatedPlayer.new(1, :kfactor => 10, :rating => 1000)
+        @r1 = ICU::RatedResult.new(1, ICU::RatedPlayer.new(2), 'W')
+        @r2 = ICU::RatedResult.new(2, ICU::RatedPlayer.new(3), 'L')
+        @r3 = ICU::RatedResult.new(3, ICU::RatedPlayer.new(4), 'D')
+      end
+
+      it "should be returned in round order" do
+        @p.add_result(@r2)
+        @p.results.size.should == 1
+        @p.results[0].should == @r2
+        @p.add_result(@r3)
+        @p.results.size.should == 2
+        @p.results[0].should == @r2
+        @p.results[1].should == @r3
+        @p.add_result(@r1)
+        @p.results.size.should == 3
+        @p.results[0].should == @r1
+        @p.results[1].should == @r2
+        @p.results[2].should == @r3
+      end
+      
+      it "the total score should stay consistent with results as they are added" do
+        @p.score.should == 0.0
+        @p.add_result(@r1)
+        @p.score.should == 1.0
+        @p.add_result(@r2)
+        @p.score.should == 1.0
+        @p.add_result(@r3)
+        @p.score.should == 1.5
+      end
+    end
+    
+    context "Rdoc examples" do
+      before(:each) do
+        @t = ICU::RatedTournament.new
+        @t.add_player(1)
+      end
+      
+      it "the same player number can't be added twice" do
+        lambda { @t.add_player(2) }.should_not raise_error
+        lambda { @t.add_player(2) }.should raise_error
+      end
+      
+      it "parameters can be specified using strings, even with whitespace padding" do
+        p = @t.add_player("  0  ", :rating => "  2000.5  ", :kfactor => "  20.5  ")
+        p.num.should == 0
+        p.num.should be_an_instance_of(Fixnum)
+        p.rating.should == 2000.5
+        p.rating.should be_an_instance_of(Float)
+        p.kfactor.should == 20.5
+        p.kfactor.should be_an_instance_of(Float)
+        p = @t.add_player("  -1  ", :rating => "  2000.5  ", :games => "  15  ")
+        p.games.should == 15
+        p.games.should be_an_instance_of(Fixnum)
+      end
+      
+      it "the games parameter should not exceed 20" do
+        lambda { @t.add_player(2, :rating => 1500, :games => 20 ) }.should raise_error
+      end
+      
+      it "adding different player types" do
+        p = @t.add_player(3, :rating => 2000, :kfactor => 16)
+        p.type.should == :rated
+        p = @t.add_player(4, :rating => 1600, :games => 10)
+        p.type.should == :provisional
+        p = @t.add_player(5)
+        p.type.should == :unrated
+        p = @t.add_player(6, :rating => 2500)
+        p.type.should == :foreign
+        lambda { @t.add_player(7, :rating => 2000, :kfactor => 16, :games => 10) }.should raise_error
+        lambda { t.add_plater(7, :kfactor => 16) }.should raise_error
+      end
+    end
+  end
+end

data/spec/result_spec.rb

@@ -0,0 +1,106 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+module ICU
+  describe RatedResult do
+    context "a basic rated result" do
+      before(:all) do
+        @o = ICU::RatedPlayer.new(2)
+      end
+      
+      it "needs a round, opponent and score (win, loss or draw)" do
+        r = ICU::RatedResult.new(1, @o, 'W')
+        r.round.should == 1
+        r.opponent.should be_an_instance_of(ICU::RatedPlayer)
+        r.score.should == 1.0
+      end
+    end
+
+    context "restrictions, or lack thereof, on attributes" do
+      before(:each) do
+        @p = ICU::RatedPlayer.new(2)
+      end
+      
+      it "round numbers must be positive" do
+        lambda { ICU::RatedResult.new(0, 1, 'W') }.should raise_error(/invalid.*round number/i)
+        lambda { ICU::RatedResult.new(-1, 1, 'W') }.should raise_error(/invalid.*round number/i)
+      end
+
+      it "the opponent must be an object, not a number" do
+        lambda { ICU::RatedResult.new(1, 0,  'W') }.should raise_error(/invalid.*class.*Fixnum/)
+        lambda { ICU::RatedResult.new(1, @p, 'W') }.should_not raise_error
+      end
+
+      it "the score can be any of the usual suspects" do
+        ['W', 'w',  1,  1.0].each { |r| ICU::RatedResult.new(1, @p, r).score.should == 1.0 }
+        ['L', 'l',  0,  0.0].each { |r| ICU::RatedResult.new(1, @p, r).score.should == 0.0 }
+        ['D', 'd', '½', 0.5].each { |r| ICU::RatedResult.new(1, @p, r).score.should == 0.5 }
+        lambda { ICU::RatedResult.new(1, @p, '') }.should raise_error(/invalid.*score/)
+      end
+    end
+
+    context "#opponents_score" do
+      before(:each) do
+        @p = ICU::RatedPlayer.new(2)
+      end
+      
+      it "should give the score from the opponent's perspective" do
+        ICU::RatedResult.new(1, @p, 'W').opponents_score.should == 0.0
+        ICU::RatedResult.new(1, @p, 'L').opponents_score.should == 1.0
+        ICU::RatedResult.new(1, @p, 'D').opponents_score.should == 0.5
+      end
+    end
+
+    context "equality" do
+      before(:each) do
+        @p1 = ICU::RatedPlayer.new(1)
+        @p2 = ICU::RatedPlayer.new(2)
+        @r1 = ICU::RatedResult.new(1, @p1, 'W')
+        @r2 = ICU::RatedResult.new(1, @p1, 'W')
+        @r3 = ICU::RatedResult.new(2, @p1, 'W')
+        @r4 = ICU::RatedResult.new(1, @p2, 'W')
+        @r5 = ICU::RatedResult.new(1, @p1, 'L')
+      end
+
+      it "should return true only if all attributes match" do
+        (@r1 == @r2).should be_true
+        (@r1 == @r3).should be_false
+        (@r1 == @r4).should be_false
+        (@r1 == @r5).should be_false
+      end
+    end
+    
+    context "Rdoc examples" do
+      before(:each) do
+        @t = ICU::RatedTournament.new
+        @t.add_player(10)
+        @t.add_player(20)
+        @t.add_player(30)
+        @t.add_result(1, 10, 20, 'W')
+        [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') }
+      end
+
+      it "it is OK but unnecessary to add the same result from the other players perspective" do
+        @t.player(10).results.size.should == 1
+        @t.player(20).results.size.should == 1
+        lambda { @t.add_result(1, 20, 10, 'L') }.should_not raise_error
+        @t.player(10).results.size.should == 1
+        @t.player(20).results.size.should == 1
+      end
+      
+      it "adding results against other players in the same round will cause an exception" do
+        lambda { @t.add_result(1, 10, 30, 'W') }.should raise_error(/inconsistent/i)
+        lambda { @t.add_result(1, 10, 20, 'L') }.should raise_error(/inconsistent/i)
+      end
+      
+      it "a player cannot have a result against himself/herself" do
+        lambda { @t.add_result(2, 10, 10, 'D') }.should raise_error(/players.*cannot.*sel[fv]/i)
+      end
+      
+      it "results are returned in score order irrespecive of the order they're added in" do
+        @t.player(0).results.map{ |r| r.round }.join(',').should == "1,2,3,4"
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+require 'rubygems'
+require 'spec'
+require File.dirname(__FILE__) + '/../lib/icu_ratings'