glicko2 0.0.1 → 0.1.0

data/README.md

@@ -28,15 +28,11 @@ Rating = Struct.new(:rating, :rating_deviation, :volatility)
 rating1 = Rating.new(1400, 30, 0.06)
 rating2 = Rating.new(1550, 100, 0.06)
 
-# Create players based on Glicko ratings
-player1 = Glicko2::Player.from_obj(rating1)
-player2 = Glicko2::Player.from_obj(rating2)
+# Rating period with all participating ratings
+period = Glicko2::RatingPeriod.from_objs [rating1, rating2]
 
-# Rating period with all participating players
-period = Glicko2::RatingPeriod.new [player1, player2]
-
-# Register a game in this rating period
-period.game([player1, player2], [1,2])
+# Register a game where rating1 wins against rating2
+period.game([rating1, rating2], [1,2])
 
 # Generate the next rating period with updated players
 next_period = period.generate_next

data/lib/glicko2.rb

@@ -1,119 +1,43 @@
 require "glicko2/version"
+require "glicko2/player"
+require "glicko2/rating_period"
 
 module Glicko2
-  TOLERANCE = 0.0000001
   DEFAULT_VOLATILITY = 0.06
   DEFAULT_GLICKO_RATING = 1500.0
   DEFAULT_GLICKO_RATING_DEVIATION = 350.0
 
-  GLICKO_GRADIENT = 173.7178
-  GLICKO_INTERCEPT = DEFAULT_GLICKO_RATING
-
   VOLATILITY_CHANGE = 0.5
 
-  class Player
-    attr_reader :mean, :sd, :volatility, :obj
-
-    def self.from_obj(obj)
-      mean = (obj.rating - GLICKO_INTERCEPT) / GLICKO_GRADIENT
-      sd = obj.rating_deviation / GLICKO_GRADIENT
-      new(mean, sd, obj.volatility, obj)
-    end
-
-    def initialize(mean, sd, volatility, obj)
-      @mean = mean
-      @sd = sd
-      @volatility = volatility
-      @obj = obj
-    end
-
-    def g
-      1 / Math.sqrt(1 + 3 * sd ** 2 / Math::PI ** 2)
-    end
-
-    def e(other)
-      1 / (1 + Math.exp(-other.g * (mean - other.mean)))
-    end
-
-    def variance(others)
-      return 0.0 if others.length < 1
-      others.reduce(0) do |v, other|
-        v + other.g ** 2 * e(other) * (1 - e(other))
-      end ** -1
-    end
-
-    def delta(others, scores)
-      others.zip(scores).reduce(0) do |d, (other, score)|
-        d + other.g * (score - e(other))
-      end * variance(others)
-    end
-
-    def f_part1(x, others, scores)
-      sd_sq = sd ** 2
-      v = variance(others)
-      _x = Math.exp(x)
-      (_x * (delta(others, scores) ** 2 - sd_sq - v - _x)) / (2 * (sd_sq + v + _x) ** 2)
-    end
- 
-    def f_part2(x)
-      (x - Math::log(volatility ** 2)) / VOLATILITY_CHANGE ** 2
-    end
- 
-    def f(x, others, scores)
-      f_part1(x, others, scores) - f_part2(x)
-    end
- 
-    def generate_next(others, scores)
-      if others.length < 1
-        sd_pre = Math.sqrt(sd ** 2 + volatility ** 2)
-        return self.class.new(mean, sd_pre, volatility, obj) if others.length < 1
-      end
-      _v = variance(others)
-      a = Math::log(volatility ** 2)
-      if delta(others, scores) > sd ** 2 + _v
-        b = Math.log(_delta - sd ** 2 - _v)
-      else
-        k = 1
-        k += 1 while f(a - k * VOLATILITY_CHANGE, others, scores) < 0
-        b = a - k * VOLATILITY_CHANGE
-      end
-      fa = f(a, others, scores)
-      fb = f(b, others, scores)
-      while (b - a).abs > TOLERANCE
-        c = a + (a - b) * fa / (fb - fa)
-        fc = f(c, others, scores)
-        if fc * fb < 0
-          a = b
-          fa = fb
-        else
-          fa /= 2.0
-        end
-        b = c
-        fb = fc
-      end
-      volatility1 = Math.exp(a / 2.0)
-      sd_pre = Math.sqrt(sd ** 2 + volatility1 ** 2)
-      sd1 = 1 / Math.sqrt(1 / sd_pre ** 2 + 1 / _v)
-      mean1 = mean + sd1 ** 2 * others.zip(scores).reduce(0) {|x, (other, score)| x + other.g * (score - e(other)) }
-      self.class.new(mean1, sd1, volatility1, obj)
-    end
-
-    def update_obj
-      @obj.rating = GLICKO_GRADIENT * mean + GLICKO_INTERCEPT
-      @obj.rating_deviation = GLICKO_GRADIENT * sd
-      @obj.volatility = volatility
-    end
-
-    def to_s
-      "#<Player mean=#{mean}, sd=#{sd}, volatility=#{volatility}, obj=#{obj}>"
-    end
-  end
-
-  class RatingPeriod
-    def initialize(players)
-      @players = players.reduce({}) { |memo, player| memo[player] = []; memo }
-    end
-
+  # Collection of helper methods
+  class Util
+    GLICKO_GRADIENT = 173.7178
+    GLICKO_INTERCEPT = DEFAULT_GLICKO_RATING
+
+    # Convert from the original Glicko scale to Glicko2 scale
+    #
+    # @param [Numeric] r Glicko rating
+    # @param [Numeric] rd Glicko rating deviation
+    # @return [Array<Numeric>]
+    def self.to_glicko2(r, rd)
+      [(r - GLICKO_INTERCEPT) / GLICKO_GRADIENT, rd / GLICKO_GRADIENT]
+    end
+
+    # Convert from the Glicko2 scale to the original Glicko scale
+    #
+    # @param [Numeric] m Glicko2 mean
+    # @param [Numeric] sd Glicko2 standard deviation
+    # @return [Array<Numeric>]
+    def self.to_glicko(m, sd)
+      [GLICKO_GRADIENT * m + GLICKO_INTERCEPT, GLICKO_GRADIENT * sd]
+    end
+
+    # Convert from a rank, where lower numbers win against higher numbers,
+    # into Glicko scores where wins are `1`, draws are `0.5` and losses are `0`.
+    #
+    # @param [Integer] rank players rank
+    # @param [Integer] other opponents rank
+    # @return [Numeric] Glicko score
     def self.ranks_to_score(rank, other)
       if rank < other
         1.0
@@ -123,31 +47,5 @@ module Glicko2
         0.0
       end
     end
-
-    def game(game_players, ranks)
-      game_players.zip(ranks).each do |player, rank|
-        game_players.zip(ranks).each do |other, other_rank|
-          next if player == other
-          @players[player] << [other, self.class.ranks_to_score(rank, other_rank)]
-        end
-      end
-    end
-
-    def generate_next
-      p = []
-      @players.each do |player, games|
-        p << player.generate_next(*games.transpose)
-      end
-      self.class.new(p)
-    end
-
-    def players
-      @players.keys
-    end
-
-    def to_s
-      "#<RatingPeriod players=#{@players.keys}"
-    end
   end
-
 end

data/lib/glicko2/player.rb

@@ -0,0 +1,189 @@
+module Glicko2
+  # Calculates a new Glicko2 ranking based on a seed object and game outcomes.
+  #
+  # The example from the Glicko2 paper, where a player wins against the first
+  # opponent, but then looses against the next two:
+  #
+  #   Rating = Struct.new(:rating, :rating_deviation, :volatility)
+  #
+  #   player_seed = Rating.new(1500, 200, 0.06)
+  #   opponent1_seed = Rating.new(1400, 30, 0.06)
+  #   opponent2_seed = Rating.new(1550, 100, 0.06)
+  #   opponent3_seed = Rating.new(1700, 300, 0.06)
+  #
+  #   player = Glicko2::Player.from_obj(player_seed)
+  #   opponent1 = Glicko2::Player.from_obj(opponent1_seed)
+  #   opponent2 = Glicko2::Player.from_obj(opponent2_seed)
+  #   opponent3 = Glicko2::Player.from_obj(opponent3_seed)
+  #
+  #   new_player = player.generate_next([opponent1, opponent2, opponent3],
+  #                                     [1, 0, 0])
+  #   new_player.update_obj
+  #
+  #   puts player_seed
+  #
+  class Player
+    TOLERANCE = 0.0000001
+
+    attr_reader :mean, :sd, :volatility, :obj
+
+    # Create a {Player} from a seed object, converting from Glicko
+    # ratings to Glicko2.
+    #
+    # @param [#rating,#rating_deviation,#volatility] obj seed values object
+    # @return [Player] constructed instance.
+    def self.from_obj(obj)
+      mean, sd = Util.to_glicko2(obj.rating, obj.rating_deviation)
+      new(mean, sd, obj.volatility, obj)
+    end
+
+    # @param [Numeric] mean player mean
+    # @param [Numeric] sd player standard deviation
+    # @param [Numeric] volatility player volatility
+    # @param [#rating,#rating_deviation,#volatility] obj seed values object
+    def initialize(mean, sd, volatility, obj=nil)
+      @mean = mean
+      @sd = sd
+      @volatility = volatility
+      @obj = obj
+      @e = {}
+    end
+
+    # Calculate `g(phi)` as defined in the Glicko2 paper
+    #
+    # @return [Numeric]
+    def g
+      @g ||= 1 / Math.sqrt(1 + 3 * sd ** 2 / Math::PI ** 2)
+    end
+
+    # Calculate `E(mu, mu_j, phi_j)` as defined in the Glicko2 paper
+    #
+    # @param [Player] other the `j` player
+    # @return [Numeric]
+    def e(other)
+      @e[other] ||= 1 / (1 + Math.exp(-other.g * (mean - other.mean)))
+    end
+
+    # Calculate the estimated variance of the team's/player's rating based only
+    # on the game outcomes.
+    #
+    # @param [Array<Player>] others other participating players.
+    # @return [Numeric]
+    def variance(others)
+      return 0.0 if others.length < 1
+      others.reduce(0) do |v, other|
+        e_other = e(other)
+        v + other.g ** 2 * e_other * (1 - e_other)
+      end ** -1
+    end
+
+    # Calculate the estimated improvement in rating by comparing the
+    # pre-period rating to the performance rating based only on game outcomes.
+    #
+    # @param [Array<Player>] others list of opponent players
+    # @param [Array<Numeric>] scores list of correlating scores (`0` for a loss,
+    #   `0.5` for a draw and `1` for a win).
+    # @return [Numeric]
+    def delta(others, scores)
+      others.zip(scores).reduce(0) do |d, (other, score)|
+        d + other.g * (score - e(other))
+      end * variance(others)
+    end
+
+    # Calculate `f(x)` as defined in the Glicko2 paper
+    #
+    # @param [Numeric] x
+    # @param [Numeric] d the result of calculating {#delta}
+    # @param [Numeric] v the result of calculating {#variance}
+    # @return [Numeric]
+    def f(x, d, v)
+      f_part1(x, d, v) - f_part2(x)
+    end
+
+    # Calculate the new value of the volatility
+    #
+    # @param [Numeric] d the result of calculating {#delta}
+    # @param [Numeric] v the result of calculating {#variance}
+    # @return [Numeric]
+    def volatility1(d, v)
+      a = Math::log(volatility ** 2)
+      if d > sd ** 2 + v
+        b = Math.log(d - sd ** 2 - v)
+      else
+        k = 1
+        k += 1 while f(a - k * VOLATILITY_CHANGE, d, v) < 0
+        b = a - k * VOLATILITY_CHANGE
+      end
+      fa = f(a, d, v)
+      fb = f(b, d, v)
+      while (b - a).abs > TOLERANCE
+        c = a + (a - b) * fa / (fb - fa)
+        fc = f(c, d, v)
+        if fc * fb < 0
+          a = b
+          fa = fb
+        else
+          fa /= 2.0
+        end
+        b = c
+        fb = fc
+      end
+      Math.exp(a / 2.0)
+    end
+
+    # Create new {Player} with updated values.
+    #
+    # This method will not modify any objects that are passed into it.
+    #
+    # @param [Array<Player>] others list of opponent players
+    # @param [Array<Numeric>] scores list of correlating scores (`0` for a loss,
+    #   `0.5` for a draw and `1` for a win).
+    # @return [Player]
+    def generate_next(others, scores)
+      if others.length < 1
+        generate_next_without_games
+      else
+        generate_next_with_games(others, scores)
+      end
+    end
+
+    # Update seed object with this player's values
+    def update_obj
+      @obj.rating, @obj.rating_deviation = Util.to_glicko(mean, sd)
+      @obj.volatility = volatility
+    end
+
+    def to_s
+      "#<Player mean=#{mean}, sd=#{sd}, volatility=#{volatility}, obj=#{obj}>"
+    end
+
+    private
+
+    def generate_next_without_games
+      sd_pre = Math.sqrt(sd ** 2 + volatility ** 2)
+      self.class.new(mean, sd_pre, volatility, obj)
+    end
+
+    def generate_next_with_games(others, scores)
+      _v = variance(others)
+      _d = delta(others, scores)
+      _volatility = volatility1(_d, _v)
+      sd_pre = Math.sqrt(sd ** 2 + _volatility ** 2)
+      _sd = 1 / Math.sqrt(1 / sd_pre ** 2 + 1 / _v)
+      _mean = mean + _sd ** 2 * others.zip(scores).reduce(0) {
+        |x, (other, score)| x + other.g * (score - e(other))
+      }
+      self.class.new(_mean, _sd, _volatility, obj)
+    end
+
+    def f_part1(x, d, v)
+      exp_x = Math.exp(x)
+      sd_sq = sd ** 2
+      (exp_x * (d ** 2 - sd_sq - v - exp_x)) / (2 * (sd_sq + v + exp_x) ** 2)
+    end
+
+    def f_part2(x)
+      (x - Math::log(volatility ** 2)) / VOLATILITY_CHANGE ** 2
+    end
+  end
+end

data/lib/glicko2/rating_period.rb

@@ -0,0 +1,66 @@
+module Glicko2
+  # Glicko ratings are calculated in bulk at the end of arbitrary, but fixed
+  # length, periods named rating periods. Where a period is fixed to be long
+  # enough that the average number of games that each player has played in is
+  # about 5 to 10 games. It could be weekly, monthly or more as required.
+  class RatingPeriod
+    attr_reader :players
+
+    # @param [Array<Player>] players
+    def initialize(players)
+      @players = players
+      @games = Hash.new { |h, k| h[k] = [] }
+      @cache = players.reduce({}) { |memo, player| memo[player.obj] = player; memo }
+    end
+
+    # Create rating period from list of seed objects
+    #
+    # @param [Array<#rating,#rating_deviation,#volatility>] objs seed value objects
+    # @return [RatingPeriod]
+    def self.from_objs(objs)
+      new(objs.map { |obj| Player.from_obj(obj) })
+    end
+
+    # Register a game with this rating period
+    #
+    # @param [Array<#rating,#rating_deviation,#volatility>] game_seeds ratings participating in a game
+    # @param [Array<Integer>] ranks corresponding ranks
+    def game(game_seeds, ranks)
+      game_seeds.zip(ranks).each do |seed, rank|
+        game_seeds.zip(ranks).each do |other, other_rank|
+          next if seed == other
+          @games[player(seed)] << [player(other),
+                                 Util.ranks_to_score(rank, other_rank)]
+        end
+      end
+    end
+
+    # Generate a new {RatingPeriod} with a new list of updated {Player}
+    #
+    # @return [RatingPeriod]
+    def generate_next
+      p = []
+      @players.each do |player|
+        games = @games[player]
+        if games.length > 0
+          p << player.generate_next(*games.transpose)
+        else
+          p << player.generate_next([], [])
+        end
+      end
+      self.class.new(p)
+    end
+
+    # Fetch the player associated with a seed object
+    #
+    # @param [#rating,#rating_deviation,#volatility] obj seed object
+    # @return [Player]
+    def player(obj)
+      @cache[obj]
+    end
+
+    def to_s
+      "#<RatingPeriod players=#{@players}"
+    end
+  end
+end

data/lib/glicko2/version.rb

@@ -1,3 +1,3 @@
 module Glicko2
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/spec/minitest_helper.rb

@@ -1,2 +1,3 @@
+require 'minitest/benchmark'
 require 'minitest/autorun'
 require 'glicko2'

data/spec/player_spec.rb

@@ -92,6 +92,10 @@ describe Glicko2::Player do
       p.volatility.must_equal @player.volatility
       p.sd.must_be_close_to Math.sqrt(@player.sd ** 2 + @player.volatility ** 2)
     end
+
+    bench_performance_linear "default" do |n|
+      @player.generate_next(@others * n, @scores * n)
+    end
   end
 
   describe "#update_obj" do

data/spec/rating_period_spec.rb

@@ -2,47 +2,36 @@ require 'minitest_helper'
 
 describe Glicko2::RatingPeriod do
   before do
-    @player = Glicko2::Player.from_obj(Rating.new(1500, 200, 0.06))
-    @player1 = Glicko2::Player.from_obj(Rating.new(1400, 30, 0.06))
-    @player2 = Glicko2::Player.from_obj(Rating.new(1550, 100, 0.06))
-    @player3 = Glicko2::Player.from_obj(Rating.new(1700, 300, 0.06))
+    @player = Rating.new(1500, 200, 0.06)
+    @player1 = Rating.new(1400, 30, 0.06)
+    @player2 = Rating.new(1550, 100, 0.06)
+    @player3 = Rating.new(1700, 300, 0.06)
     @players = [@player, @player1, @player2, @player3]
-    @period = Glicko2::RatingPeriod.new(@players)
+    @period = Glicko2::RatingPeriod.from_objs(@players)
   end
 
-  describe ".new" do
-    it "must assign players" do
-      @period.players.must_include @player
-      @period.players.must_include @player1
-      @period.players.must_include @player2
-      @period.players.must_include @player3
-    end
-  end
-
-  describe ".ranks_to_score" do
-    it "must return 1.0 when rank is less" do
-      Glicko2::RatingPeriod.ranks_to_score(1, 2).must_equal 1.0
-    end
-
-    it "must return 0.5 when rank is equal" do
-      Glicko2::RatingPeriod.ranks_to_score(1, 1).must_equal 0.5
-    end
-
-    it "must return 0.0 when rank is more" do
-      Glicko2::RatingPeriod.ranks_to_score(2, 1).must_equal 0.0
-    end
-  end
-
-  describe "complete rating period" do
+  describe "#generate_next" do
     it "must be close to example" do
       @period.game([@player, @player1], [1, 2])
       @period.game([@player, @player2], [2, 1])
       @period.game([@player, @player3], [2, 1])
       @period.generate_next.players.each { |p| p.update_obj }
-      obj = @player.obj
+      obj = @player
       obj.rating.must_be_close_to 1464.06, 0.01
       obj.rating_deviation.must_be_close_to 151.52, 0.01
       obj.volatility.must_be_close_to 0.05999, 0.00001
     end
+
+    it "must process non-competing players" do
+      @period.game([@player, @player1], [1, 2])
+      @period.generate_next
+    end
+
+    bench_performance_linear "default" do |n|
+      n.times do
+        @period.game(@players.sample(2), [1, 2])
+      end
+      @period.generate_next
+    end
   end
 end

data/spec/util_spec.rb

@@ -0,0 +1,17 @@
+require 'minitest_helper'
+
+describe Glicko2::Util do
+  describe ".ranks_to_score" do
+    it "must return 1.0 when rank is less" do
+      Glicko2::Util.ranks_to_score(1, 2).must_equal 1.0
+    end
+
+    it "must return 0.5 when rank is equal" do
+      Glicko2::Util.ranks_to_score(1, 1).must_equal 0.5
+    end
+
+    it "must return 0.0 when rank is more" do
+      Glicko2::Util.ranks_to_score(2, 1).must_equal 0.0
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: glicko2
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-12 00:00:00.000000000 Z
+date: 2012-12-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -41,10 +41,13 @@ files:
 - Rakefile
 - glicko2.gemspec
 - lib/glicko2.rb
+- lib/glicko2/player.rb
+- lib/glicko2/rating_period.rb
 - lib/glicko2/version.rb
 - spec/minitest_helper.rb
 - spec/player_spec.rb
 - spec/rating_period_spec.rb
+- spec/util_spec.rb
 homepage: https://github.com/proglottis/glicko2
 licenses: []
 post_install_message: 
@@ -73,3 +76,5 @@ test_files:
 - spec/minitest_helper.rb
 - spec/player_spec.rb
 - spec/rating_period_spec.rb
+- spec/util_spec.rb
+has_rdoc: