elo_rating 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 234b746cfd73febb6fafd5c60bba73541f30bd98
-  data.tar.gz: 4a563d7890683bcdbf076d20e1440d4148f5030f
+  metadata.gz: 72c73870b99ccb9fa0eb8d5ada07c4104af74f33
+  data.tar.gz: f60fde89bad3ca68a36baf083dca5fa112da4a57
 SHA512:
-  metadata.gz: 019a19ba4502f0e88bfcefbdee250b7ab61295d0970fa6d79ebb20ff23e286e5fee2c9b88fcf5c306068fadec480eab929198581861bd45ea158b08c012bae12
-  data.tar.gz: 374d0bff359bdb950cddc367815ba32e4f6ea771d6cf6931ee8863036d9a6371872bd99a8917257f5a84cb2725b185eddfc64515927065a42da0ae38029d4988
+  metadata.gz: 059f1564f4fbbc9064660f6ae6be567faed7e3c0787f3340a62718923b4b9f224e69cb6bc8f5281d0834c7559490aa16370f0d45c2119d347fb37bca8eb893a3
+  data.tar.gz: f2c8fea968c72d13c49f00e77fb7a3934c3afe2f3c05d714ace015f7fbf5c3c113447772ef67cff9c3f92330d53d3cac4ce4dd172d0404349991c7f7a794595b

data/.gitignore

@@ -1,4 +1,3 @@
 Guardfile
-Gemfile
 Gemfile.lock
-doc/
+pkg

data/README.md

@@ -1,6 +1,6 @@
 # elo_rating
 
-`elo_rating` helps you calculate [Elo ratings](https://en.wikipedia.org/wiki/Elo_rating_system), a rating system used primary for Chess.
+`elo_rating` helps you calculate [Elo ratings](https://en.wikipedia.org/wiki/Elo_rating_system), a rating system used primary for Chess, but can be used anywhere you want to determine an absolute ordering of things by doing many comparisons of a small number of things.
 
 It can handle multiple players in one game and allows for custom K-factor functions.
 
@@ -20,9 +20,11 @@ gem 'elo_rating'
 
 ## Usage
 
-Say you have two players, both have ratings of 2000. The second player wins. To
-determine both player's updated ratings:
+Say you have two players playing against each other in a match, both with initial ratings of 2000.
 
+The second player wins.
+
+To determine both player's updated ratings:
 
 ```ruby
 match = EloRating::Match.new
@@ -31,13 +33,19 @@ match.add_player(rating: 2000, winner: true)
 match.updated_ratings # => [1988, 2012]
 ```
 
-The first player's rating goes down 12 points and the second player's goes up 12 points.
+This tells us that the first player's rating should go down 12 points and the second player's should go up 12 points.
+
+You can chain the same function calls to achieve the same result:
+
+```ruby
+EloRating::Match.new.add_player(rating: 2000).add_player(rating: 2000, winner: true).updated_ratings # => [1988, 2012]
+```
 
 ### >2 players
 
-Most Elo rating calculators only allow for matches of just 2 players, but the
-formula can be extended games with more players by calculating rating adjustments
-for each player against each of their opponents.
+Most Elo rating calculators only allow for matches of just 2 players, but the formula can be extended to games of any number of players.
+
+We can do this by combining the rating adjustments for each pairing of players into one big adjustment.
 
 Say you have three players, rated 1900, 2000, and 2000. They are playing a game
 like [Monopoly](https://en.wikipedia.org/wiki/Monopoly_(game)) where there is
@@ -52,21 +60,26 @@ match.add_player(rating: 2000)
 match.updated_ratings # => [1931, 1985, 1985]
 ```
 
+This is calculated as if the first player beat both of the other players and the other two players tied.
+
 ### Ranked games
 
-Some games like [Mario Kart](https://en.wikipedia.org/wiki/Mario_Kart) have
-multiple, ranked winners. Let's say you have three players like before, rated
-1900, 2000, and 2000. Instead of indicating the winner, you can specify the
-ranks:
+Some games like [Mario Kart](https://en.wikipedia.org/wiki/Mario_Kart) have multiple, ranked winners.
+
+Let's say you have three players like before, rated 1900, 2000, and 2000, who came in first place, second place, and third place respectively.
+
+Instead of indicating the winner, you can specify their places:
 
 ```ruby
 match = EloRating::Match.new
-match.add_player(rating: 1900, rank: 1)
-match.add_player(rating: 2000, rank: 2)
-match.add_player(rating: 2000, rank: 3)
+match.add_player(rating: 1900, place: 1)
+match.add_player(rating: 2000, place: 2)
+match.add_player(rating: 2000, place: 3)
 match.updated_ratings # => [1973, 1997, 1931]
 ```
 
+This is calculated as if the first player beat both of the other players and the second player beat the third.
+
 ## Elo rating functions
 
 The functions used in the above calculations are available for use directly:
@@ -83,10 +96,11 @@ The player rated 1900 has a 36% chance of winning.
 
 ### Rating adjustment
 
-You can use the expected score and the results of an actual match to determine
-how an Elo rating should change.
+You can use the expected score and the results of an actual match to determine how an Elo rating should change.
+
+The `EloRating.rating_adjustment` function takes an expected score and an actual score and returns how much a rating should go up or down.
 
-Let's say we have the expected rating from above of 0.36. If the first player rated 1900 won the match, their actual score would be 1.
+Let's say we have the expected rating from above of 0.36 and the first player rated 1900 won the match, making their actual score 1.
 
 We can use this to determine how much their rating should change:
 
@@ -94,7 +108,7 @@ We can use this to determine how much their rating should change:
 EloRating.rating_adjustment(0.36, 1) # => 15.36
 ```
 
-Their rating should go up about 15 points if they win.
+This means their rating should now be 1915.
 
 ## K-factor
 
@@ -106,18 +120,27 @@ It defaults to 24:
 EloRating::k_factor # => 24
 ```
 
-You can change this to any number. With a lower K-factor, ratings are less volatile and change slower:
+You can change this to any number. With a lower K-factor, ratings are less volatile and change slower. Compare:
 
 ```ruby
 EloRating::k_factor = 10
 match = EloRating::Match.new
 match.add_player(rating: 2000, winner: true)
 match.add_player(rating: 2000)
-match.updated_ratings # => [1995, 2005]
+match.updated_ratings # => [2005, 1995]
+```
+
+to:
+
+```ruby
+EloRating::k_factor = 20
+match = EloRating::Match.new
+match.add_player(rating: 2000, winner: true)
+match.add_player(rating: 2000)
+match.updated_ratings # => [2010, 1990]
 ```
 
-You can also pass a block to provide a custom function to calculate the K-factor
-based on the player's rating:
+You can also pass a block to provide a custom function to calculate the K-factor based on the player's rating:
 
 ```ruby
 EloRating::set_k_factor do |rating|
@@ -132,8 +155,7 @@ EloRating::set_k_factor do |rating|
 end
 ```
 
-You can provide a rating to `EloRating.rating_adjustment` that will be used in
-your custom K-factor function:
+Then you can provide a rating to `EloRating.rating_adjustment` that will be used in your custom K-factor function:
 
 ```ruby
 EloRating.rating_adjustment(0.75, 0) # => -24.0
@@ -141,13 +163,13 @@ EloRating.rating_adjustment(0.75, 0, rating: 2200) # => -18.0
 EloRating.rating_adjustment(0.75, 0, rating: 2500) # => -12.0
 ```
 
-You can also specify a K-factor for a single rating adjustment:
+You can also just specify a K-factor directly for a single rating adjustment:
 
 ```ruby
 EloRating.rating_adjustment(0.75, 0, k_factor: 24) # => -18.0
 ```
 
-Note: custom K-factor functions must not raise any exceptions when the rating is nil:
+*Note*: custom K-factor functions must not raise any exceptions when the rating is nil:
 
 ```ruby
 EloRating::set_k_factor do |rating|
@@ -155,3 +177,18 @@ EloRating::set_k_factor do |rating|
 end
 # => ArgumentError: Error encountered in K-factor block when passed nil rating: undefined method `/' for nil:NilClass
 ```
+
+## Thanks
+
+Thanks to:
+
+* Divergent Informatics for their [multiplayer Elo
+calculator](http://elo.divergentinformatics.com/) used to verify calculations used in the development of this gem
+* [Ian Hecker](https://github.com/iain) for the original [Elo](https://github.com/iain/elo).
+
+## License
+
+Copyright © 2014 Maxwell Holder.
+
+It is free software, and may be redistributed under the terms specified in the
+LICENSE file.

data/Rakefile

@@ -1,2 +1,6 @@
 require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
 

data/lib/elo_rating/match.rb

@@ -2,15 +2,16 @@
 # This class represents a single game between a number of players.
 class EloRating::Match
 
+  # All the players of the match.
   attr_reader :players
 
-  # Creates a new match
+  # Creates a new match with no players.
   def initialize
     @players = []
   end
 
   # Adds a player to the match
-  # 
+  #
   # ==== Attributes
   # * +rating+: the Elo rating of the player
   # * +winner+ (optional): boolean, whether this player is the winner of the match
@@ -86,7 +87,8 @@ class EloRating::Match
     def rating_adjustment_against(opponent)
       EloRating.rating_adjustment(
         expected_score_against(opponent),
-        actual_score_against(opponent)
+        actual_score_against(opponent),
+        rating: rating
       )
     end
 

data/lib/elo_rating/version.rb

@@ -1,3 +1,3 @@
 module EloRating
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/elo_rating.rb

@@ -29,7 +29,7 @@ module EloRating
   #     end
   #   end
   #
-  # Raises an ArgumentError if an exception is encountered when calling the provided block with nil as the argument
+  # Raises an +ArgumentError+ if an exception is encountered when calling the provided block with nil as the argument
   def self.set_k_factor(&k_factor)
     k_factor.call(nil)
     @k_factor = k_factor

data/spec/match_spec.rb

@@ -28,6 +28,20 @@ describe EloRating::Match do
         expect(match.updated_ratings).to eql [1931, 1997, 1973]
       end
     end
+    context 'custom K-factor function' do
+      it 'uses the custom K-factor function' do
+        EloRating::set_k_factor do |rating|
+          rating || 0
+        end
+
+        match = EloRating::Match.new
+        match.add_player(rating: 2000)
+        match.add_player(rating: 2000, winner: true)
+        expect(match.updated_ratings).not_to eql [2000, 2000]
+
+        EloRating::k_factor = 24
+      end
+    end
     context 'multiple winners specified' do
       it 'raises an error' do
         match = EloRating::Match.new

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: elo_rating
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Max Holder
@@ -90,8 +90,6 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - Gemfile
-- Gemfile.lock
-- Guardfile
 - LICENSE
 - README.md
 - Rakefile

data/Gemfile.lock

@@ -1,63 +0,0 @@
-PATH
-  remote: .
-  specs:
-    elo_rating (0.3.0)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    celluloid (0.15.2)
-      timers (~> 1.1.0)
-    coderay (1.1.0)
-    diff-lcs (1.2.5)
-    ffi (1.9.3)
-    formatador (0.2.5)
-    guard (2.6.1)
-      formatador (>= 0.2.4)
-      listen (~> 2.7)
-      lumberjack (~> 1.0)
-      pry (>= 0.9.12)
-      thor (>= 0.18.1)
-    guard-rspec (4.2.10)
-      guard (~> 2.1)
-      rspec (>= 2.14, < 4.0)
-    listen (2.7.9)
-      celluloid (>= 0.15.2)
-      rb-fsevent (>= 0.9.3)
-      rb-inotify (>= 0.9)
-    lumberjack (1.0.7)
-    method_source (0.8.2)
-    pry (0.10.0)
-      coderay (~> 1.1.0)
-      method_source (~> 0.8.1)
-      slop (~> 3.4)
-    rake (10.3.1)
-    rb-fsevent (0.9.4)
-    rb-inotify (0.9.5)
-      ffi (>= 0.5.0)
-    rspec (3.0.0)
-      rspec-core (~> 3.0.0)
-      rspec-expectations (~> 3.0.0)
-      rspec-mocks (~> 3.0.0)
-    rspec-core (3.0.2)
-      rspec-support (~> 3.0.0)
-    rspec-expectations (3.0.2)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.0.0)
-    rspec-mocks (3.0.2)
-      rspec-support (~> 3.0.0)
-    rspec-support (3.0.2)
-    slop (3.5.0)
-    thor (0.19.1)
-    timers (1.1.0)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  bundler (~> 1.6)
-  elo_rating!
-  guard
-  guard-rspec
-  rake
-  rspec

data/Guardfile

@@ -1,24 +0,0 @@
-# A sample Guardfile
-# More info at https://github.com/guard/guard#readme
-
-guard :rspec do
-  watch(%r{^spec/.+_spec\.rb$})
-  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
-  watch('spec/spec_helper.rb')  { "spec" }
-
-  # Rails example
-  watch(%r{^app/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
-  watch(%r{^app/(.*)(\.erb|\.haml|\.slim)$})          { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
-  watch(%r{^app/controllers/(.+)_(controller)\.rb$})  { |m| ["spec/routing/#{m[1]}_routing_spec.rb", "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb", "spec/acceptance/#{m[1]}_spec.rb"] }
-  watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
-  watch('config/routes.rb')                           { "spec/routing" }
-  watch('app/controllers/application_controller.rb')  { "spec/controllers" }
-
-  # Capybara features specs
-  watch(%r{^app/views/(.+)/.*\.(erb|haml|slim)$})     { |m| "spec/features/#{m[1]}_spec.rb" }
-
-  # Turnip features and steps
-  watch(%r{^spec/acceptance/(.+)\.feature$})
-  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$})   { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'spec/acceptance' }
-end
-