icu_ratings 1.0.4 → 1.0.5

data/lib/icu_ratings/player.rb

@@ -1,162 +1,158 @@
 # encoding: utf-8
 
 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)
-
-== 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
-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_::     This is the player's new rating. For rated players it is their old rating
-                   plus their _rating_change_. For provisional players it is their performance
-                   rating including their previous games. For unrated players it is their
-                   tournament performance rating. New rarings are not calculated for foreign
-                   players so this method just returned their start _rating_.
-_rating_change_::  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.
-_performance_::    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_.
-_expected_score_:: This returns the sum of expected scores over all results for all player types.
-                   For rated players, this number times the K-factor gives their rating change.
-                   It is calculated for provisional, unrated and foreign players but not actually
-                   used to estimate new ratings (for provisional and unrated players performance
-                   estimates are used instead).
-
-== 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
-
+  #
+  # == 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)
+  #
+  # == 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
+  # 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_::     This is the player's new rating. For rated players it is their old rating
+  #                    plus their _rating_change_. For provisional players it is their performance
+  #                    rating including their previous games. For unrated players it is their
+  #                    tournament performance rating. New rarings are not calculated for foreign
+  #                    players so this method just returned their start _rating_.
+  # _rating_change_::  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.
+  # _performance_::    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_.
+  # _expected_score_:: This returns the sum of expected scores over all results for all player types.
+  #                    For rated players, this number times the K-factor gives their rating change.
+  #                    It is calculated for provisional, unrated and foreign players but not actually
+  #                    used to estimate new ratings (for provisional and unrated players performance
+  #                    estimates are used instead).
+  #
+  # == 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.
+  #
   class RatedPlayer
     attr_reader :num, :rating, :kfactor, :games
     attr_accessor :desc, :bonus

data/lib/icu_ratings/result.rb

@@ -1,98 +1,94 @@
 # encoding: utf-8
 
 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
-
+  #
+  # == 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_.
+  #
   class RatedResult
     # The round number.
     def round

data/lib/icu_ratings/tournament.rb

@@ -1,78 +1,74 @@
 # encoding: utf-8
 
 module ICU
-
-=begin rdoc
-
-== Creating Tournaments
-
-ICU::RatedTournament objects are created directly.
-
-  t = ICU::RatedTournament.new
-
-They have some optional parameters which can be set via the constructor or by calling
-the same-named setter methods. One is 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 2010")
-  puts t.desc                         # "Irish Championships 2010"
-
-Another optional parameter is _start_ for the start date. A Date object or a string that can be
-parsed as a string can be used to set it. The European convention is preferred for dates like
-"03/06/2013" (3rd of June, not 6th of March). Attempting to set an invalid date will raise an
-exception.
-
-  t = ICU::RatedTournament.new(:start => "01/07/2010")
-  puts t.start.class                  # Date
-  puts t.start.to_s                   # "2010-07-01"
-
-Also, there is the option _no_bonuses_. Bonuses are a feature of the ICU rating system. If you are
-rating a non-ICU tournament (such as a FIDE tournament) where bonues are not awarded use this option.
-
-  t = ICU::RatedTournament.new(:desc => 'Linares', :start => "07/02/2009", :no_bonuses => true)
-
-Note, however, that the ICU system also has its own unique way of treating provisional, unrated and
-foreign players, so the only FIDE tournaments that can be rated using this software are those that
-consist solely of rated players.
-
-== 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 an instance of non-convergence
-has yet to be observed in practice.
-
-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
-
+  #
+  # == Creating Tournaments
+  #
+  # ICU::RatedTournament objects are created directly.
+  #
+  #   t = ICU::RatedTournament.new
+  #
+  # They have some optional parameters which can be set via the constructor or by calling
+  # the same-named setter methods. One is 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 2010")
+  #   puts t.desc                         # "Irish Championships 2010"
+  #
+  # Another optional parameter is _start_ for the start date. A Date object or a string that can be
+  # parsed as a string can be used to set it. The European convention is preferred for dates like
+  # "03/06/2013" (3rd of June, not 6th of March). Attempting to set an invalid date will raise an
+  # exception.
+  #
+  #   t = ICU::RatedTournament.new(:start => "01/07/2010")
+  #   puts t.start.class                  # Date
+  #   puts t.start.to_s                   # "2010-07-01"
+  #
+  # Also, there is the option _no_bonuses_. Bonuses are a feature of the ICU rating system. If you are
+  # rating a non-ICU tournament (such as a FIDE tournament) where bonues are not awarded use this option.
+  #
+  #   t = ICU::RatedTournament.new(:desc => 'Linares', :start => "07/02/2009", :no_bonuses => true)
+  #
+  # Note, however, that the ICU system also has its own unique way of treating provisional, unrated and
+  # foreign players, so the only FIDE tournaments that can be rated using this software are those that
+  # consist solely of rated players.
+  #
+  # == 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 an instance of non-convergence
+  # has yet to be observed in practice.
+  #
+  # 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.
+  #
   class RatedTournament
     attr_accessor :desc
     attr_reader :start, :no_bonuses

data/lib/icu_ratings/util.rb

@@ -3,33 +3,18 @@ require 'date' # needed for 1.9.1
 module ICU
   class Util
 
-=begin rdoc
-
-== Parsing dates
-
-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)
-  Util.parsedate!('02/23/2009')       # => Date (2009-02-23)
-  Util.parsedate!('16th June 1986')   # => Date (1986-06-16)
-  Util.parsedate!('not a date')       # exception raised
-
-Note that the parse method of the Date class behaves differently in Ruby 1.8.7 and 1.9.1.
-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
-
+    # 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)
+    #   Util.parsedate!('02/23/2009')       # => Date (2009-02-23)
+    #   Util.parsedate!('16th June 1986')   # => Date (1986-06-16)
+    #   Util.parsedate!('not a date')       # exception raised
+    #
+    # Note that the parse method of the Date class behaves differently in Ruby 1.8.7 and 1.9.1.
+    # 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".
+    #
     def self.parsedate!(date)
       return date.clone if date.is_a?(Date)
       string = date.to_s.strip
@@ -42,6 +27,12 @@ Internally it uses _parsedate!_ so can throw a exception if an invalid date is s
       end
     end
 
+    # 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.
     def self.age(born, date=Date.today)
       born = parsedate!(born)
       date = parsedate!(date)

data/lib/icu_ratings/version.rb

@@ -1,5 +1,7 @@
+# :enddoc:
+
 module ICU
   class Ratings
-    VERSION = "1.0.4"
+    VERSION = "1.0.5"
   end
 end

data/spec/tournament_spec.rb

@@ -160,20 +160,20 @@ module ICU
       it "after the tournament is rated" do
         @t.rate!
 
-        @t.player(1).expected_score.should be_close(2.249, 0.001)
-        @t.player(2).expected_score.should be_close(1.760, 0.001)
-        @t.player(3).expected_score.should be_close(1.240, 0.001)
-        @t.player(4).expected_score.should be_close(0.751, 0.001)
+        @t.player(1).expected_score.should be_within(0.001).of(2.249)
+        @t.player(2).expected_score.should be_within(0.001).of(1.760)
+        @t.player(3).expected_score.should be_within(0.001).of(1.240)
+        @t.player(4).expected_score.should be_within(0.001).of(0.751)
 
-        @t.player(1).rating_change.should be_close(7.51,   0.01)
-        @t.player(2).rating_change.should be_close(4.81,   0.01)
-        @t.player(3).rating_change.should be_close(-7.21,  0.01)
-        @t.player(4).rating_change.should be_close(-30.05, 0.01)
+        @t.player(1).rating_change.should be_within(0.01).of(7.51)
+        @t.player(2).rating_change.should be_within(0.01).of(4.81)
+        @t.player(3).rating_change.should be_within(0.01).of(-7.21)
+        @t.player(4).rating_change.should be_within(0.01).of(-30.05)
 
-        @t.player(1).new_rating.should be_close(2207.5, 0.1)
-        @t.player(2).new_rating.should be_close(2104.8, 0.1)
-        @t.player(3).new_rating.should be_close(1992.8, 0.1)
-        @t.player(4).new_rating.should be_close(1870.0, 0.1)
+        @t.player(1).new_rating.should be_within(0.1).of(2207.5)
+        @t.player(2).new_rating.should be_within(0.1).of(2104.8)
+        @t.player(3).new_rating.should be_within(0.1).of(1992.8)
+        @t.player(4).new_rating.should be_within(0.1).of(1870.0)
       end
     end
 
@@ -229,8 +229,8 @@ module ICU
         ].each do |item|
           num, expected_score, new_rating = item
           p = @t.player(num)
-          p.expected_score.should be_close(expected_score, 0.001)
-          p.new_rating.should be_close(new_rating, 0.5)
+          p.expected_score.should be_within(0.001).of(expected_score)
+          p.new_rating.should be_within(0.5).of(new_rating)
         end
       end
 
@@ -245,8 +245,8 @@ module ICU
         ].each do |item|
           num, ytd_performance, tournament_performance = item
           p = @t.player(num)
-          p.performance.should_not be_close(ytd_performance, 0.5)
-          p.performance.should be_close(tournament_performance, 0.5)
+          p.performance.should_not be_within(0.5).of(ytd_performance)
+          p.performance.should be_within(0.5).of(tournament_performance)
         end
       end
     end
@@ -263,10 +263,10 @@ module ICU
       end
 
       it "should get same results as ICU rating database" do
-        @t.player(1).expected_score.should be_close(1.689, 0.001)
-        @t.player(2).expected_score.should be_close(1.311, 0.001)
-        @t.player(1).new_rating.should be_close(1378, 0.5)
-        @t.player(2).new_rating.should be_close(1261, 0.5)
+        @t.player(1).expected_score.should be_within(0.001).of(1.689)
+        @t.player(2).expected_score.should be_within(0.001).of(1.311)
+        @t.player(1).new_rating.should be_within(0.5).of(1378)
+        @t.player(2).new_rating.should be_within(0.5).of(1261)
       end
     end
 
@@ -380,12 +380,12 @@ module ICU
         pc = @t.player(2)
 
         af.score.should == 4.5
-        af.expected_score.should be_close(6.054, 0.001)
-        af.new_rating.should be_close(2080, 0.5)
+        af.expected_score.should be_within(0.001).of(6.054)
+        af.new_rating.should be_within(0.5).of(2080)
 
         pc.score.should == 4.0
-        pc.expected_score.should be_close(3.685, 0.001)
-        pc.new_rating.should be_close(1984, 0.5)
+        pc.expected_score.should be_within(0.001).of(3.685)
+        pc.new_rating.should be_within(0.5).of(1984)
       end
     end
 
@@ -534,9 +534,9 @@ module ICU
         ].each do |item|
           num, expected_score, new_rating = item
           p = @t.player(num)
-          p.expected_score.should be_close(expected_score, 0.01)
-          p.new_rating.should be_close(new_rating, 0.5)
-          p.results.inject(p.rating){ |t,r| t + r.rating_change }.should be_close(new_rating, 0.5)
+          p.expected_score.should be_within(0.01).of(expected_score)
+          p.new_rating.should be_within(0.5).of(new_rating)
+          p.results.inject(p.rating){ |t,r| t + r.rating_change }.should be_within(0.5).of(new_rating)
         end
       end
 
@@ -547,8 +547,8 @@ module ICU
         ].each do |item|
           num, expected_score, new_rating = item
           p = @t.player(num)
-          p.expected_score.should be_close(expected_score, 0.01)
-          p.new_rating.should be_close(new_rating, 0.5)
+          p.expected_score.should be_within(0.01).of(expected_score)
+          p.new_rating.should be_within(0.5).of(new_rating)
         end
       end
 
@@ -608,8 +608,8 @@ module ICU
         ].each do |item|
           num, expected_score, new_rating = item
           p = @t.player(num)
-          p.expected_score.should be_close(expected_score, 0.01)
-          p.new_rating.should be_close(new_rating, 0.5)
+          p.expected_score.should be_within(0.01).of(expected_score)
+          p.new_rating.should be_within(0.5).of(new_rating)
         end
       end
     end
@@ -661,8 +661,8 @@ module ICU
           num, score, expected_score, new_rating, bonus = item
           p = @t.player(num)
           p.score.should == score
-          p.expected_score.should be_close(expected_score, 0.01)
-          p.new_rating.should be_close(new_rating, 0.5)
+          p.expected_score.should be_within(0.01).of(expected_score)
+          p.new_rating.should be_within(0.5).of(new_rating)
           p.bonus.should == bonus
         end
       end
@@ -713,10 +713,10 @@ module ICU
           num, score, expected_score, performance = item
           p = @t.player(num)
           p.score.should == score
-          p.expected_score.should be_close(expected_score, 0.01)
-          p.performance.should be_close(performance, 0.5)
+          p.expected_score.should be_within(0.01).of(expected_score)
+          p.performance.should be_within(0.5).of(performance)
           if num == 1
-            p.new_rating.should be_close(1836, 0.5)
+            p.new_rating.should be_within(0.5).of(1836)
             p.bonus.should == 71
           else
             p.new_rating.should == p.rating
@@ -773,9 +773,9 @@ module ICU
           p = @t.player(num)
           p.score.should == score
           p.bonus.should == bonus
-          p.performance.should be_close(performance, 0.5)
-          p.expected_score.should be_close(expected_score, 0.01)
-          p.new_rating.should be_close(new_rating, 0.5)
+          p.performance.should be_within(0.5).of(performance)
+          p.expected_score.should be_within(0.01).of(expected_score)
+          p.new_rating.should be_within(0.5).of(new_rating)
         end
       end
     end
@@ -833,9 +833,9 @@ module ICU
           p = @t.player(num)
           p.score.should == score
           p.bonus.should == bonus
-          p.performance.should be_close(performance, num == 2 ? 0.6 : 0.5)
-          p.expected_score.should be_close(expected_score, 0.01)
-          p.new_rating.should be_close(new_rating, 0.5)
+          p.performance.should be_within(num == 2 ? 0.6 : 0.5).of(performance)
+          p.expected_score.should be_within(0.01).of(expected_score)
+          p.new_rating.should be_within(0.5).of(new_rating)
         end
       end
 
@@ -846,9 +846,9 @@ module ICU
           p = @t.player(num)
           p.score.should == score
           p.bonus.should == bonus
-          p.performance.should be_close(performance, num == 2 ? 0.6 : 0.5)
-          p.expected_score.should be_close(expected_score, 0.01)
-          p.new_rating.should be_close(new_rating, 0.5)
+          p.performance.should be_within(num == 2 ? 0.6 : 0.5).of(performance)
+          p.expected_score.should be_within(0.01).of(expected_score)
+          p.new_rating.should be_within(0.5).of(new_rating)
         end
       end
 
@@ -860,9 +860,9 @@ module ICU
           p = @t.player(num)
           p.score.should == score
           p.bonus.should == 0
-          p.performance.should_not be_close(performance, 1.0)
-          p.expected_score.should_not be_close(expected_score, 0.01)
-          p.new_rating.should_not be_close(new_rating, 1.0)
+          p.performance.should_not be_within(1.0).of(performance)
+          p.expected_score.should_not be_within(0.01).of(expected_score)
+          p.new_rating.should_not be_within(1.0).of(new_rating)
         end
       end
     end
@@ -901,8 +901,8 @@ module ICU
         ].each do |item|
           num, expected_score, new_rating = item
           p = @t.player(num)
-          p.expected_score.should be_close(expected_score, 0.01)
-          p.new_rating.should be_close(new_rating, 0.5)
+          p.expected_score.should be_within(0.01).of(expected_score)
+          p.new_rating.should be_within(0.5).of(new_rating)
         end
       end
 

data/spec/util_spec.rb

@@ -50,9 +50,9 @@ module ICU
       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', '2001-01-02').should be_within(0.01).of(1/365)
+        Util.age('2001-01-01', '2001-02-01').should be_within(0.01).of(1/12.0)
+        Util.age('1955-11-09', '2010-01-17').should be_within(0.01).of(54.2)
         Util.age('2001-01-01', '2000-01-01').should == -1.0
       end
 

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 1
   - 0
-  - 4
-  version: 1.0.4
+  - 5
+  version: 1.0.5
 platform: ruby
 authors: 
 - Mark Orr
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-14 00:00:00 +01:00
+date: 2010-12-31 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -27,9 +27,9 @@ dependencies:
       - !ruby/object:Gem::Version 
         segments: 
         - 2
+        - 3
         - 0
-        - 0
-        version: 2.0.0
+        version: 2.3.0
   type: :development
   version_requirements: *id001
 description: Build an object that represents a chess tournament then get it to calculate ratings of all the players.
@@ -82,7 +82,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: "0"
 requirements: []
 
-rubyforge_project: 
+rubyforge_project: icu_ratings
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3