elo_rating 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9b56895aa2ec414462c5b2480ed2ebe93fa9f642
+  data.tar.gz: 50b2f10121650d74f5344d28eb440663d3b3a672
+SHA512:
+  metadata.gz: 7bd15401b85f7c9b8a0b5414ed45d44755afbb70b15b3308ca5cede8f41775f108b00763a3521ce6b2a9856673ea39e3e5b94b3ed41cd79eb6a493d3c19d8d1a
+  data.tar.gz: 63b7eb3a19af7eccca15b9c07c9c93ee0d77b01b142d25dbcb17fc5575d8ddecaa3460f94f65cd292df50aa7dd3ca1327153886f2f63e0c13e4334c8b8e5faa6

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Maxwell Holder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,157 @@
+# elo_rating
+
+`elo_rating` helps you calculate [Elo ratings](https://en.wikipedia.org/wiki/Elo_rating_system), a rating system used primary for Chess.
+
+It can handle multiple players in one game and allows for custom K-factor functions.
+
+- [API Documentation]()
+
+## Getting started
+
+```ruby
+gem install elo_rating
+```
+
+or add it to your Gemfile and run `bundle`:
+
+```ruby
+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:
+
+
+```ruby
+match = EloRating::Match.new
+match.add_player(rating: 2000)
+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.
+
+### >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.
+
+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
+only one winner. The third player wins.
+To determine their new scores:
+
+```ruby
+match = EloRating::Match.new
+match.add_player(rating: 1900, winner: true)
+match.add_player(rating: 2000)
+match.add_player(rating: 2000)
+match.updated_ratings # => [1931, 1985, 1985]
+```
+
+### 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:
+
+```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.updated_ratings # => [1973, 1997, 1931]
+```
+
+## Elo rating functions
+
+The functions used in the above calculations are available for use directly:
+
+### Expected score
+
+Say you have 2 players, rated 1900 and 2000.
+
+```ruby
+EloRating.expected_score(1900, 2000) # => 0.360
+```
+
+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.
+
+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.
+
+We can use this to determine how much their rating should change:
+
+```ruby
+EloRating.rating_adjustment(0.36, 1) # => 15.36
+```
+
+Their rating should go up about 15 points if they win.
+
+## K-factor
+
+The K-factor is used in calculating the rating adjustment and determines how much impact the most recent game has on a player's rating.
+
+It defaults to 24:
+
+```ruby
+EloRating::k_factor # => 24
+```
+
+You can change this to any number. With a lower K-factor, ratings are less volatile and change slower:
+
+```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]
+```
+
+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|
+  rating ||= 2000
+  if rating < 2100
+    32
+  elsif 2100 <= rating && rating <= 2400
+    24
+  else
+    16
+  end
+end
+```
+
+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
+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:
+
+```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:
+
+```ruby
+EloRating::set_k_factor do |rating|
+  rating / 100
+end
+# => ArgumentError: Error encountered in K-factor block when passed nil rating: undefined method `/' for nil:NilClass
+```

data/lib/elo_rating/match.rb

@@ -0,0 +1,118 @@
+##
+# This class represents a single game between a number of players.
+class EloRating::Match
+
+  attr_reader :players
+
+  # Creates a new match
+  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
+  # * +place+ (optional): a number representing the rank of the player within the match; the lower the number, the higher they placed
+  #
+  # Raises an +ArgumentError+ if the rating or place is not numeric, or if
+  # both winner and place is specified.
+  def add_player(player_attributes)
+    players << Player.new(player_attributes.merge(match: self))
+    self
+  end
+
+  # Calculates the updated ratings for each of the players in the match.
+  #
+  # Raises an +ArgumentError+ if more than one player is marked as the winner or
+  # if some but not all players have +place+ specified.
+  def updated_ratings
+    validate_players!
+    players.map(&:updated_rating)
+  end
+
+  private
+
+  def validate_players!
+    raise ArgumentError, 'Only one player can be the winner' if multiple_winners?
+    raise ArgumentError, 'All players must have places if any do' if inconsistent_places?
+  end
+
+  def multiple_winners?
+    players.select { |player| player.winner? }.size > 1
+  end
+
+  def inconsistent_places?
+    players.select { |player| player.place }.any? &&
+      players.select { |player| !player.place }.any?
+  end
+
+  class Player
+  # :nodoc:
+    attr_reader :rating, :place, :match
+    def initialize(match:, rating:, place: nil, winner: nil)
+      validate_attributes!(rating: rating, place: place, winner: winner)
+      @match = match
+      @rating = rating
+      @place = place
+      @winner = winner
+    end
+
+    def winner?
+      @winner
+    end
+
+    def validate_attributes!(rating:, place:, winner:)
+      raise ArgumentError, 'Rating must be numeric' unless rating.is_a? Numeric
+      raise ArgumentError, 'Winner and place cannot both be specified' if place && winner
+      raise ArgumentError, 'Place must be numeric' unless place.nil? || place.is_a?(Numeric)
+    end
+
+    def opponents
+      match.players - [self]
+    end
+
+    def updated_rating
+      (rating + total_rating_adjustments).round
+    end
+
+    def total_rating_adjustments
+      opponents.map do |opponent|
+        rating_adjustment_against(opponent)
+      end.reduce(0, :+)
+    end
+
+    def rating_adjustment_against(opponent)
+      EloRating.rating_adjustment(
+        expected_score_against(opponent),
+        actual_score_against(opponent)
+      )
+    end
+
+    def expected_score_against(opponent)
+      EloRating.expected_score(rating, opponent.rating)
+    end
+
+    def actual_score_against(opponent)
+      if won_against?(opponent)
+        1
+      elsif opponent.won_against?(self)
+        0
+      else # draw
+        0.5
+      end
+    end
+
+    def won_against?(opponent)
+      winner? || placed_ahead_of?(opponent)
+    end
+
+    def placed_ahead_of?(opponent)
+      if place && opponent.place
+        place < opponent.place
+      end
+    end
+  end
+end
+

data/lib/elo_rating.rb

@@ -0,0 +1,73 @@
+# :main: README.md
+
+##
+# EloRating helps you calculate Elo ratings.
+#
+# See the README for an introduction.
+module EloRating
+
+  # Default K-factor.
+  @k_factor = Proc.new do |rating|
+    24
+  end
+
+  # Calls the K-factor function with the provided rating.
+  def self.k_factor(rating = nil)
+    @k_factor.call(rating)
+  end
+
+  # Sets the K-factor by providing a block that optionally takes a +rating+
+  # argument:
+  #
+  #   EloRating::set_k_factor do |rating|
+  #     if rating && rating > 2500
+  #       24
+  #     else
+  #       16
+  #     end
+  #   end
+  #
+  # 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
+  rescue => e
+    raise ArgumentError, "Error encountered in K-factor block when passed nil rating: #{e}"
+  end
+  
+  # Sets the K-factor to a number.
+  def self.k_factor=(k_factor)
+    @k_factor = Proc.new do
+      k_factor
+    end
+  end
+
+  # Calculates the expected score of a player given their rating (+player_rating+)
+  # and their opponent's rating (+opponent_rating+).
+  #
+  # Returns a float between 0 and 1 where 0.999 represents high certainty of the
+  # first player winning.
+  def self.expected_score(player_rating, opponent_rating)
+    1.0/(1 + (10 ** ((opponent_rating - player_rating)/400.0)))
+  end
+
+  # Calculates the amount a player's rating should change.
+  #
+  # ==== Arguments
+  # * +expected_score+: a float between 0 and 1, representing the probability of
+  # the player winning
+  # * +actual_score+: 0, 0.5, or 1, whether the outcome was a loss, draw, or win
+  # (respectively)
+  # * +rating+ (optional): the rating of the player, used by the K-factor function
+  # * +k_factor+ (optional): the K-factor to use for this calculation to be used
+  # instead of the normal K-factor or K-factor function
+  #
+  # Returns a positive or negative float representing the amount the player's
+  # rating should change.
+  def self.rating_adjustment(expected_score, actual_score, rating: nil, k_factor: nil)
+    k_factor ||= k_factor(rating)
+    k_factor * (actual_score - expected_score)
+  end
+end
+
+require 'elo_rating/match'

data/spec/elo_rating_spec.rb

@@ -0,0 +1,84 @@
+require_relative '../lib/elo_rating.rb'
+
+describe EloRating do
+  after(:each) do
+    EloRating::k_factor = 24
+  end
+  describe '::k_factor' do
+    it 'defaults to 24' do
+      expect(EloRating::k_factor).to eql(24)
+    end
+  end
+  describe '::k_factor=' do
+    it 'sets the K-factor to an integer' do
+      EloRating::k_factor = 10
+      expect(EloRating::k_factor).to eql(10)
+    end
+  end
+  describe '::set_k_factor' do
+    it 'takes a block to determine the K-factor based on a player\'s rating' do
+      EloRating::set_k_factor do |rating|
+        if rating && rating > 1000
+          15
+        else
+          24
+        end
+      end
+      expect(EloRating::k_factor(1001)).to eql 15
+    end
+    context 'given a block that doesn\'t handle nil ratings' do
+      it 'raises an error' do
+        expect do
+          EloRating::set_k_factor do |rating|
+            rating * 10
+          end
+        end.to raise_error ArgumentError
+      end
+    end
+  end
+  describe '.expected_score' do
+    it 'returns the odds of a player winning given their rating and their opponent\'s rating' do
+      expect(EloRating.expected_score(1200, 1000)).to be_within(0.0001).of(0.7597)
+    end
+  end
+  describe '.rating_adjustment' do
+    it 'returns the amount a rating should change given an expected score and an actual score' do
+      expect(EloRating.rating_adjustment(0.75, 0)).to be_within(0.0001).of(-18.0)
+    end
+    it 'uses the K-factor' do
+      expect(EloRating).to receive(:k_factor).and_return(24)
+
+      EloRating.rating_adjustment(0.75, 0)
+    end
+    context 'custom numeric k-factor' do
+      it 'uses the custom k-factor' do
+        EloRating::k_factor = 10
+
+        expect(EloRating.rating_adjustment(0.75, 0)).to be_within(0.0001).of(-7.5)
+      end
+    end
+    context 'custom k-factor function' do
+      it 'calls the function with the provided rating to determine the k-factor' do
+        EloRating::set_k_factor do |rating|
+          rating ||= 2000
+          if rating < 2100
+            32
+          elsif 2100 <= rating && rating <= 2400
+            24
+          else
+            16
+          end
+        end
+
+        expect(EloRating.rating_adjustment(0.75, 0)).to be_within(0.0001).of(-24.0)
+        expect(EloRating.rating_adjustment(0.75, 0, rating: 2200)).to be_within(0.0001).of(-18.0)
+        expect(EloRating.rating_adjustment(0.75, 0, rating: 2500)).to be_within(0.0001).of(-12.0)
+      end
+    end
+    context 'provided with a nonce numeric k-factor' do
+      it 'uses the provided k-factor' do
+        expect(EloRating.rating_adjustment(0.75, 0, k_factor: 24)).to be_within(0.0001).of(-18.0)
+      end
+    end
+  end
+end

data/spec/match_spec.rb

@@ -0,0 +1,95 @@
+require_relative '../lib/elo_rating.rb'
+
+describe EloRating::Match do
+  describe '#updated_ratings' do
+    context 'simple match with two players and one winner' do
+      it 'returns the updated ratings of all the players' do
+        match = EloRating::Match.new
+        match.add_player(rating: 2000)
+        match.add_player(rating: 2000, winner: true)
+        expect(match.updated_ratings).to eql [1988, 2012]
+      end
+    end
+    context 'match with 3 players and one winner' do
+      it 'returns the updated ratings of all the players' do
+        match = EloRating::Match.new
+        match.add_player(rating: 1900, winner: true)
+        match.add_player(rating: 2000)
+        match.add_player(rating: 2000)
+        expect(match.updated_ratings).to eql [1931, 1985, 1985]
+      end
+    end
+    context 'ranked game with 3 players' do
+      it 'returns the updated ratings of all the players' do
+        match = EloRating::Match.new
+        match.add_player(rating: 1900, place: 1)
+        match.add_player(rating: 2000, place: 2)
+        match.add_player(rating: 2000, place: 3)
+        expect(match.updated_ratings).to eql [1931, 1997, 1973]
+      end
+    end
+    context 'multiple winners specified' do
+      it 'raises an error' do
+        match = EloRating::Match.new
+        match.add_player(rating: 1000, winner: true)
+        match.add_player(rating: 1000, winner: true)
+        expect { match.updated_ratings }.to raise_error ArgumentError
+      end
+    end
+    context 'place specified for one player but not all' do
+      it 'raises an error' do
+        match = EloRating::Match.new
+        match.add_player(rating: 1000)
+        match.add_player(rating: 1000, place: 2)
+        expect { match.updated_ratings }.to raise_error ArgumentError
+      end
+    end
+  end
+
+  describe '#add_player' do
+    context 'adding a player with a rating' do
+      it 'creates a new player with the specified rating' do
+        match = EloRating::Match.new
+        expect(EloRating::Match::Player).to receive(:new).with(rating: 2000, match: match)
+
+        match.add_player(rating: 2000)
+      end
+      it 'appends the new player to the match\'s player' do
+        match = EloRating::Match.new
+        match.add_player(rating: 2000)
+
+        expect(match.players.size).to eql 1
+      end
+      it 'returns the match itself so multiple calls can be chained' do
+        match = EloRating::Match.new
+        match.add_player(rating: 1000).add_player(rating: 2000)
+
+        expect(match.players.size). to eql 2
+      end
+    end
+
+    context 'adding a player with a non-numeric rating' do
+      it 'raises an error' do
+        match = EloRating::Match.new
+
+        expect { match.add_player(rating: :foo) }.to raise_error(ArgumentError)
+      end
+    end
+
+    context 'adding a player with a non-numeric place' do
+      it 'raises an error' do
+        match = EloRating::Match.new
+
+        expect { match.add_player(rating: 1000, place: :foo) }.to raise_error(ArgumentError)
+      end
+    end
+
+    context 'adding a player with both winner and place specified' do
+      it 'raises an error' do
+        match = EloRating::Match.new
+
+        expect { match.add_player(rating: 1000, place: 2, winner: true) }.to raise_error ArgumentError
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: elo_rating
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Max Holder
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-06-28 00:00:00.000000000 Z
+dependencies: []
+description: Tiny library for calculating Elo ratings. Handles multiplayer matches
+  and allows for custom k-factor functions.
+email: mxhold@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/elo_rating.rb
+- lib/elo_rating/match.rb
+- spec/elo_rating_spec.rb
+- spec/match_spec.rb
+homepage: http://github.com/mxhold/elo_rating
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.0
+signing_key: 
+specification_version: 4
+summary: Tiny library for calculating Elo ratings
+test_files:
+- spec/elo_rating_spec.rb
+- spec/match_spec.rb