ranker 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+--- 
+SHA1: 
+  data.tar.gz: 00ce8440e7681886fd6ae2c93f4db5af94c5a655
+  metadata.gz: 691b75e03742cc6ca452f8fc9a45cec01a1fa9f2
+SHA512: 
+  data.tar.gz: 458a61a409e17288fb97b90dea58417b99426d627f61c9aaa5d9417e88a27944b6137b2dbed40390bd0e0d281c5b6277ca329dc0bdafa5067cd4964ca8d6ee8f
+  metadata.gz: 77454afb9e3c29d72a8e3c223f9a0d47df41d7841e00a933e9c7f3de0adeffa9c882a173c432178d1fc621fe45dae2e37b6cff2f950b8c6339d0a36f173355f2

data/README.md

@@ -0,0 +1,135 @@
+Ranker [![Build Status](https://travis-ci.org/quidproquo/ranker.png?branch=master)](http://travis-ci.org/quidproquo/ranker)
+======
+
+A Ruby library for ranking scorable types using various ranking strategies.
+
+Compatibility
+-------------
+
+Ranker is tested against MRI (1.8.7+) and JRuby (1.9.0+).
+
+Installation
+------------
+
+With bundler, add the `ranker` gem to your `Gemfile`.
+
+```ruby
+gem "ranker", "~> 1.0"
+```
+
+Require the `ranker` gem in your application.
+
+```ruby
+require "ranker"
+```
+
+Usage
+-----
+
+### Default Ranking
+
+Default ranking will assume values are numeric and rank them in descending order.
+
+```ruby
+scores = [1, 1, 2, 3, 3, 1, 4, 4, 5, 6, 8, 1, 0]
+rankings = Ranker.rank(scores)
+rankings.count #=> 8
+ranking_1 = rankings[0]
+ranking_1.rank #=> 1
+ranking_1.score #=> 8
+```
+
+### Custom Ranking
+
+Custom ranking allows for ranking of objects by using a symbol or a lambda.
+
+```ruby
+class Player
+  attr_accesor :score
+  
+  def initalize(score)
+    @score = score
+  end
+end
+
+players = [Player.new(0), Player.new(100), Player.new(1000), Player.new(25)]
+rankings = Ranker.rank(players, :by => lambda { |player| player.score })
+# or
+rankings = Ranker.rank(players, :by => :score)
+```
+
+In some cases objects need to be ranked by score in ascending order, for example, if you were ranking golf players.
+
+
+```ruby
+class GolfPlayer < Player
+end
+
+players = [GolfPlayer.new(72), GolfPlayer.new(100), GolfPlayer.new(138), GolfPlayer.new(54)]
+rankings = Ranker.rank(players, :by => :score, :desc => false)
+```
+
+### Ranking Strategies
+
+Ranker has a number of ranking strategies available to use, mostly based on the Wikipedia entry on [ranking](http://en.wikipedia.org/wiki/Ranking). Strategies can be passed in as an option to the rank method.
+
+```ruby
+rankings = Ranker.rank(players, :by => :score, :strategy => :ordinal)
+```
+
+#### Standard Competition Ranking ("1224" ranking)
+
+This is the default ranking strategy. For more info, see the Wikipedia entry on [Standard Competition Ranking](http://en.wikipedia.org/wiki/Ranking#Standard_competition_ranking_.28.221224.22_ranking.29).
+
+```ruby
+rankings = Ranker.rank(players, :by => :score, :strategy => :standard_competition)
+```
+
+#### Modified Competition Ranking ("1334" ranking)
+
+For more info, see the Wikipedia entry on [Modified Competition Ranking](http://en.wikipedia.org/wiki/Ranking#Modified_competition_ranking_.28.221334.22_ranking.29).
+
+```ruby
+rankings = Ranker.rank(players, :by => :score, :strategy => :modified_competition)
+```
+
+#### Dense Ranking ("1223" ranking)
+
+For more info, see the Wikipedia entry on [Dense Ranking](http://en.wikipedia.org/wiki/Ranking#Dense_ranking_.28.221223.22_ranking.29).
+
+```ruby
+rankings = Ranker.rank(players, :by => :score, :strategy => :dense)
+```
+
+#### Ordinal Ranking ("1234" ranking)
+
+For more info, see the Wikipedia entry on [Ordinal Ranking](http://en.wikipedia.org/wiki/Ranking#Ordinal_ranking_.28.221234.22_ranking.29).
+
+```ruby
+rankings = Ranker.rank(players, :by => :score, :strategy => :ordinal)
+```
+
+#### Custom Ranking
+
+If you find the current strategies not to your liking, you can write your own and pass the class into the rank method.
+
+```ruby
+class MyCustomStrategy < Ranker::Strategies::Strategy
+
+  def execute
+    # My code here
+  end
+
+end
+
+rankings = Ranker.rank(players, :by => :score, :strategy => MyCustomStrategy)
+```
+
+
+Copyright
+---------
+
+Copyright &copy; 2013 Ilya Scharrenbroich. Released under the MIT License.
+
+
+

data/lib/ranker.rb

@@ -0,0 +1,72 @@
+require 'ranker/ranking'
+require 'ranker/rankings'
+require 'ranker/strategies'
+require 'ranker/version'
+
+##
+# Ranks are based on: http://en.wikipedia.org/wiki/Ranking
+#
+module Ranker
+
+  class << self
+
+    # Properties:
+
+    def strategies
+      @strategies ||= {
+        :standard_competition => Ranker::Strategies::StandardCompetition,
+        :modified_competition => Ranker::Strategies::ModifiedCompetition,
+        :dense => Ranker::Strategies::Dense,
+        :ordinal => Ranker::Strategies::Ordinal
+      }
+    end
+
+    # Methods:
+
+    def rank(rankables, *args)
+      options = args.pop
+      if options && options.kind_of?(Hash)
+        options = default_options.merge(options)
+      else
+        options = default_options
+      end
+      strategy = get_strategy(rankables, options)
+      strategy.rank
+    end
+
+
+    protected
+
+    # Properties:
+
+    def default_options
+      {
+        :by => lambda { |rankable| rankable },
+        :desc => true,
+        :strategy => :standard_competition
+      }
+    end
+
+    # Methods:
+
+    def get_strategy(rankables, options)
+      strategy_class = get_strategy_class(options[:strategy])
+      strategy_class.new(rankables, options)
+    end
+
+    def get_strategy_class(strategy)
+      if strategy.kind_of?(Class)
+        strategy
+      else
+        if strategy = strategies[strategy]
+          strategy
+        else
+          raise ArgumentError.new("Unknown strategy: #{strategy}")
+        end
+      end
+    end
+
+  end # class methods
+
+end
+

data/lib/ranker/ranking.rb

@@ -0,0 +1,44 @@
+module Ranker
+
+  class Ranking
+
+    attr_reader :rankings, :index, :rank, :score, :rankables
+
+    def initialize(rankings, index, rank, score, rankables)
+      @rankings = rankings
+      @index = index
+      @rank = rank
+      @score = score
+      @rankables = rankables
+    end
+
+    # Properties:
+
+    def num_rankables
+      rankables.count
+    end
+
+    def percentile
+      @percentile ||= (num_scores_at_or_below.to_f / rankings.num_scores) * 100
+    end
+
+    def z_score
+      @z_score ||= if rankings.standard_deviation == 0
+        0
+      else
+        (score - rankings.mean) / rankings.standard_deviation
+      end
+    end
+
+    protected
+
+    def num_scores_at_or_below
+      @scores_at_or_below ||= rankings[index..rankings.num_scores].reduce(0) { |sum, ranking|
+        sum + ranking.num_rankables
+      }
+    end
+
+  end # class
+
+end # module
+

data/lib/ranker/rankings.rb

@@ -0,0 +1,56 @@
+module Ranker
+
+  class Rankings < Array
+
+    attr_reader :strategy, :scores
+
+    def initialize(strategy)
+      @strategy = strategy
+      @scores = []
+    end
+
+
+    # Properties:
+
+    def mean
+      @mean ||= total.to_f / num_scores
+    end
+
+    def standard_deviation
+      @standard_deviation ||= if variance.nan?
+        # For ruby-1.8.7 compatibility
+        variance
+      else
+        Math.sqrt(variance)
+      end
+    end
+
+    def num_scores
+      scores.size
+    end
+
+    def variance
+      @variance ||= total_difference.to_f / num_scores
+    end
+
+    def total
+      @total ||= scores.reduce(:+)
+    end
+
+    def total_difference
+      @total_difference ||= scores.reduce(0) { |sum, score|
+        sum + (score - mean) ** 2
+      }
+    end
+
+
+    # Methods:
+
+    def create(rank, score, rankables)
+      scores.concat(Array.new(rankables.count, score))
+      self << Ranking.new(self, self.count, rank, score, rankables)
+    end
+
+  end # class
+
+end # module

data/lib/ranker/strategies.rb

@@ -0,0 +1,9 @@
+require 'ranker/strategies/strategy.rb'
+require 'ranker/strategies/dense.rb'
+require 'ranker/strategies/modified_competition.rb'
+require 'ranker/strategies/standard_competition.rb'
+require 'ranker/strategies/ordinal.rb'
+
+module Ranker::Strategies
+
+end

data/lib/ranker/strategies/dense.rb

@@ -0,0 +1,20 @@
+module Ranker::Strategies
+
+  ##
+  # Ranks rankables according to: http://en.wikipedia.org/wiki/Ranking#Dense_ranking_.28.221223.22_ranking.29
+  #
+  class Dense < Strategy
+
+    # Methods:
+
+    def execute
+      scores_unique_sorted.each_with_index { |score, index|
+        rank = index + 1
+        rankables_for_score = rankables_for_score(score)
+        create_ranking(rank, score, rankables_for_score)
+      }
+    end
+
+  end # class
+
+end # module

data/lib/ranker/strategies/modified_competition.rb

@@ -0,0 +1,26 @@
+module Ranker::Strategies
+
+  ##
+  # Ranks rankables according to: http://en.wikipedia.org/wiki/Ranking#Modified_competition_ranking_.28.221334.22_ranking.29
+  #
+  class ModifiedCompetition < Strategy
+
+    # Methods:
+
+    def execute
+      rank = 0
+      scores_unique_sorted.each_with_index { |score, index|
+        rankables_for_score = rankables_for_score(score)
+        if rank == 0
+          create_ranking(1, score, rankables_for_score)
+          rank += rankables_for_score.count
+        else
+          rank += rankables_for_score.count
+          create_ranking(rank, score, rankables_for_score)
+        end
+      }
+    end
+
+  end # class
+
+end # module

data/lib/ranker/strategies/ordinal.rb

@@ -0,0 +1,23 @@
+module Ranker::Strategies
+
+  ##
+  # Ranks rankables according to: http://en.wikipedia.org/wiki/Ranking#Ordinal_ranking_.28.221234.22_ranking.29
+  #
+  class Ordinal < Strategy
+
+    # Methods:
+
+    def execute
+      rank = 1
+      scores_unique_sorted.each_with_index { |score, index|
+        rankables_for_score = rankables_for_score(score)
+        rankables_for_score.each { |value|
+          create_ranking(rank, score, [value])
+          rank += 1
+        }
+      }
+    end
+
+  end # class
+
+end # module

data/lib/ranker/strategies/standard_competition.rb

@@ -0,0 +1,21 @@
+module Ranker::Strategies
+
+  ##
+  # Ranks rankables according to: http://en.wikipedia.org/wiki/Ranking#Standard_competition_ranking_.28.221224.22_ranking.29
+  #
+  class StandardCompetition < Strategy
+
+    # Methods:
+
+    def execute
+      rank = 1
+      scores_unique_sorted.each_with_index { |score, index|
+        rankables_for_score = rankables_for_score(score)
+        create_ranking(rank, score, rankables_for_score)
+        rank += rankables_for_score.count
+      }
+    end
+
+  end # class
+
+end # module

data/lib/ranker/strategies/strategy.rb

@@ -0,0 +1,82 @@
+module Ranker::Strategies
+
+  class Strategy
+
+    attr_reader :rankables, :options
+
+    def initialize(rankables, *args)
+      @rankables = rankables
+      options = args.pop
+      if options && options.kind_of?(Hash)
+        @options = default_options.merge(options)
+      else
+        @options = default_options
+      end
+    end
+
+
+    # Properties:
+
+    def rankings
+      @rankings ||= Ranker::Rankings.new(self)
+    end
+
+
+    # Methods:
+
+
+    def rank
+      execute
+      rankings
+    end
+
+
+    protected
+
+    # Properties:
+
+    def default_options
+      {
+        :by => lambda { |rankable| rankable },
+        :desc => true
+      }
+    end
+
+    def score
+      options[:by]
+    end
+
+    def sort_desc?
+      options[:desc]
+    end
+
+    def rankables_grouped_by_score
+      @rankables_grouped_by_score ||= rankables.group_by(&score)
+    end
+
+    def scores_unique_sorted
+      @scores_unique_sorted ||= unless sort_desc?
+        rankables_grouped_by_score.keys.sort!
+      else
+        rankables_grouped_by_score.keys.sort!.reverse!
+      end
+    end
+
+
+    # Methods:
+
+    def create_ranking(rank, score, rankables)
+      rankings.create(rank, score, rankables)
+    end
+
+    def execute
+      raise NotImplementedError.new('You must implement the execute method.')
+    end
+
+    def rankables_for_score(score)
+      rankables_grouped_by_score[score]
+    end
+
+  end # class
+
+end # module