icu_ratings 0.2.7 → 0.3.0

data/VERSION.yml

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

data/lib/icu_ratings/player.rb

@@ -91,6 +91,29 @@ all these parameters can be specified using strings, even when padded with white
   p.rating         # 2000.5 (Float)
   p.kfactor        # 20.5 (Float)
 
+== Calculation of K-factors
+
+Rather than pre-calculating the value to set for a rated player's K-factor, the RatedPlayer class can itself
+calculate K-factors if the releavant information is supplied. ICU K-factors depend not only on a player's
+rating, but also on their age and experience. Therefore, supply a hash, instead of a numerical value, for the
+_kfactor_ attribute with values set for date-of-birth (_dob_) and date joined (_joined_):
+
+  t = Tournament.new(:start => "2010-07-10")
+  p = t.add_player(1, :rating => 2225, :kfactor => { :dob => "1993-12-20", :joined => "2004-11-28" })
+  p.kfactor        # 16.0
+
+For this to work the tournament's optional start date must be set to enable the player's age and
+experience at the start of the tournament be to calculated. The ICU K-factor rules are:
+
+* 16 for players rated 2100 and over, otherwise
+* 40 for players aged under 21, otherwise
+* 32 for players who have been members for less than 8 years, otherwise
+* 24
+
+If you want to calculate K-factors accrding to some other, non-ICU scheme, then override the
+static method _kfactor_ of the RatedPlayer class and pass in a hash of whatever key-value pairs
+it requires as the value associated with _kfactor_ key in the _add_player_ method.
+
 == Description Parameter
 
 There is one other optional parameter, _desc_ (short for "description"). It has no effect on player
@@ -166,6 +189,20 @@ method.
       @type
     end
 
+    # Calculate a K-factor according to ICU rules.
+    def self.kfactor(args)
+      case
+      when args[:rating] >= 2100 then
+        16
+      when ICU::Util.age(args[:dob], args[:start]) < 21 then
+        40
+      when ICU::Util.age(args[:joined], args[:start]) < 8 then
+        32
+      else
+        24
+      end
+    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

data/lib/icu_ratings/tournament.rb

@@ -70,6 +70,7 @@ to be caught and handled in some suitable place in your code.
     # See ICU::RatedPlayer for details.
     def add_player(num, args={})
       raise "player with number #{num} already exists" if @player[num]
+      args[:kfactor] = ICU::RatedPlayer.kfactor(args[:kfactor].merge({ :start => start, :rating => args[:rating] })) if args[:kfactor].is_a?(Hash)
       @player[num] = ICU::RatedPlayer.new(num, args)
     end
 

data/lib/icu_ratings/util.rb

@@ -7,7 +7,7 @@ module ICU
 
 == Parsing dates
 
-Parse strings into date objects, interpreting nn/nn/nnnn as dd/mm/yyyy. Raises exception on error.
+The method _parsedate!_ parses strings into date objects, interpreting nn/nn/nnnn as dd/mm/yyyy. It raises an exception on error.
 
   Util.parsedate!('1955-11-09')       # => Date (1955-11-09)
   Util.parsedate!('02/03/2009')       # => Date (2009-03-02)
@@ -19,9 +19,19 @@ Note that the parse method of the Date class behaves differently in Ruby 1.8.7 a
 In 1.8.7 it assumes American dates and will raise ArgumentError on "30/03/2003".
 In 1.9.1 it assumes European dates and will raise ArgumentError on "03/30/2003".
 
+== Diffing dates
+
+The method _age_ returns the difference of two dates:
+
+  Util.age(born, date)               # age in years at the given date (Float)
+  Util.age(born)                     # age in years now (today)
+
+Internally it uses _parsedate!_ so can throw a exception if an invalid date is supplied.
+
 =end
 
     def self.parsedate!(date)
+      return date.clone if date.is_a?(Date)
       string = date.to_s.strip
       raise "invalid date (#{date})" unless string.match(/[1-9]/)
       string = [$3].concat($2.to_i > 12 ? [$1, $2] : [$2, $1]).join('-') if string.match(/^(\d{1,2}).(\d{1,2}).(\d{4})$/)
@@ -31,5 +41,11 @@ In 1.9.1 it assumes European dates and will raise ArgumentError on "03/30/2003".
         raise "invalid date (#{date})"
       end
     end
+
+    def self.age(born, date=Date.today)
+      born = parsedate!(born)
+      date = parsedate!(date)
+      date.year - born.year + (date.yday - born.yday) / 366.0
+    end
   end
-end
+end

data/spec/player_spec.rb

@@ -136,6 +136,30 @@ module ICU
       end
     end
 
+    context "calculation of K-factor" do
+      it "should return 16 for players 2100 and above" do
+        ICU::RatedPlayer.kfactor(:rating => 2101, :start => '2010-07-10', :dob => '1955-11-09', :joined => '1974-01-01').should == 16
+        ICU::RatedPlayer.kfactor(:rating => 2100, :start => '2010-07-10', :dob => '1955-11-09', :joined => '1974-01-01').should == 16
+        ICU::RatedPlayer.kfactor(:rating => 2099, :start => '2010-07-10', :dob => '1955-11-09', :joined => '1974-01-01').should_not == 16
+      end
+
+      it "should otherwise return 40 for players aged under 21 at the start of the tournament" do
+        ICU::RatedPlayer.kfactor(:rating => 2000, :start => '2010-07-10', :dob => '1989-07-11', :joined => '1999-01-01').should == 40
+        ICU::RatedPlayer.kfactor(:rating => 2000, :start => '2010-07-10', :dob => '1989-07-10', :joined => '1999-01-01').should_not == 40
+        ICU::RatedPlayer.kfactor(:rating => 2000, :start => '2010-07-10', :dob => '1989-07-09', :joined => '1999-01-01').should_not == 40
+      end
+
+      it "should otherwise return 32 for players with under 8 years experience at the start of the tournament" do
+        ICU::RatedPlayer.kfactor(:rating => 2000, :start => '2010-07-10', :dob => '1989-01-01', :joined => '2002-07-11').should == 32
+        ICU::RatedPlayer.kfactor(:rating => 2000, :start => '2010-07-10', :dob => '1989-01-01', :joined => '2002-07-10').should_not == 32
+        ICU::RatedPlayer.kfactor(:rating => 2000, :start => '2010-07-10', :dob => '1989-01-01', :joined => '2002-07-09').should_not == 32
+      end
+
+      it "should otherwise return 24" do
+        ICU::RatedPlayer.kfactor(:rating => 2000, :start => '2010-07-10', :dob => '1989-01-01', :joined => '2002-01-01').should == 24
+      end
+    end
+
     context "Rdoc examples" do
       before(:each) do
         @t = ICU::RatedTournament.new

data/spec/tournament_spec.rb

@@ -27,6 +27,32 @@ module ICU
       end
     end
 
+    context "#add_player and calculation of K-factor" do
+      before(:each) do
+        @t = ICU::RatedTournament.new(:start => "2010-07-10")
+      end
+
+      it "should set a K-factor of 16 for players with rating >= 2100" do
+        @p = @t.add_player(1, :rating => 2200, :kfactor => { :dob => "1955-11-09", :joined => "1976-09-01" })
+        @p.kfactor.should == 16
+      end
+
+      it "should set a K-factor of 40 for players with rating < 2100 and age < 21" do
+        @p = @t.add_player(1, :rating => 2000, :kfactor => { :dob => "1995-01-10", :joined => "2009-09-01" })
+        @p.kfactor.should == 40
+      end
+
+      it "should set a K-factor of 32 for players with rating < 2100, age >= 21 and experience < 8" do
+        @p = @t.add_player(1, :rating => 2000, :kfactor => { :dob => "1975-01-10", :joined => "2005-09-01" })
+        @p.kfactor.should == 32
+      end
+
+      it "should set a K-factor of 24 for players with rating < 2100, age >= 21 and experience >= 8" do
+        @p = @t.add_player(1, :rating => 2000, :kfactor => { :dob => "1975-01-10", :joined => "1995-09-01" })
+        @p.kfactor.should == 24
+      end
+    end
+
     context "#players and #player" do
       before(:each) do
         @t = ICU::RatedTournament.new

data/spec/util_spec.rb

@@ -45,5 +45,20 @@ module ICU
         Util.parsedate!(Date.parse('2013-07-01')).should == Date.parse('2013-07-01')
       end
     end
+
+    context "#age" do
+      it "should return age in years" do
+        Util.age('2001-01-01', '2001-01-01').should == 0.0
+        Util.age('2001-01-01', '2002-01-01').should == 1.0
+        Util.age('2001-01-01', '2001-01-02').should be_close(1/365.0, 0.01)
+        Util.age('2001-01-01', '2001-02-01').should be_close(1/12.0, 0.01)
+        Util.age('1955-11-09', '2010-01-17').should be_close(54.2, 0.01)
+        Util.age('2001-01-01', '2000-01-01').should == -1.0
+      end
+
+      it "should default second date to today" do
+        Util.age(Date.today).should == 0.0
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: icu_ratings
 version: !ruby/object:Gem::Version 
-  version: 0.2.7
+  version: 0.3.0
 platform: ruby
 authors: 
 - Mark Orr