acts_as_meritocracy 0.2

data/Gemfile

@@ -0,0 +1,2 @@
+source 'http://rubygems.org'
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Nicolas Maisonneuve (n.maisonneuve@gmail.com)
+
+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.rdoc

@@ -0,0 +1,64 @@
+= meritocracy
+This plugin introduces a mixin to get a weigted voting system for qualitative (categorical) items.
+
+As a measure of the quality of the consensus/inter-rater agreement, you can choose between a weighted variant of fleiss kappa (http://en.wikipedia.org/wiki/Fleiss%27_kappa) (by default) or the entropy (http://en.wikipedia.org/wiki/Entropy_(information_theory)) of the vote distribution
+but you can change it.  The consensus score is in the interval [0,1]. very high consensus=1 , very low consensus=0
+
+NOTE: this voting system has been developed to take (collective) decision about items, not rank items (e.g. by popularity).
+i.e. generally once a certain level of consensus is reached on a given item, a decision is taken and the vote is close.
+
+== scenario example
+You have a set of items and would like to classify them according to 4 predefined categories. For that you ask the opinion to the public.
+As some people are better/more reliable than other, their votes can be weighted so they have more power in the collective decision
+
+== installation
+To use it, add it to your Gemfile:
+
+  gem 'acts_as_meritocracy'
+
+== Usage
+
+    class Item < ActiveRecord::Base
+
+      act_as_meritocracy
+    end
+
+    item= Item.create()
+    item.submit_vote(user1, 4) #user1 votes for the decision 4,  by default the vote_weight=1
+    item.submit_vote(user2, 1, 2) #user2 votes for the decision 1 with a vote_weight=2. A vote_weight=2 means that the voter has a vote equal to 2 normal voters (vote_weight=1)
+    item.submit_vote(user1, 1) #user1 can change/update her vote
+    item.submit_vote(user3, 2) #user3 vote for decision 2
+    item.submit_vote(user4, 3,5) #user3 vote for decision 2
+
+    item.best_decision #get the most (weighted) voted decision
+    =>3
+
+
+    item.nb_votes(true) # get the number of votes - with the weight
+    => 1+2+1+5= 9
+
+    item.nb_votes(false) # get the number of votes - without taking into account the weight
+    => 1+1+1+1= 4
+
+    item.vote_distribution # get the frequency distribution of the decisions [{:decision1=>freq1},{:decision1=>freq2}, ..,{:decision1=>freq3}]. the frequency takes into account the vote weight.
+    => [{1=>3},{2=1},{3=5}]
+
+    # compute the consensus score based on the vote distribution
+    # by default I used a variante of the Fleiss Kappa metrics
+    item.consensus
+    => 0.361
+    # An entropy-based computation of the consensus is also proposed
+    # (a perfect disagreement between 2 categories give a higher score than for 10 categories, less predictable)
+    item.consensus("entropy")
+    =>0.063
+
+    item.votes # retrieve the list of votes {decision, vote_weight) , so item.votes.where(:vote=>1) get the list of votes having decision=1
+
+    end
+
+
+
+== Copyright
+
+Copyright (c) 2012 nm. See MIT-LICENSE.txt for further details.
+

data/Rakefile

@@ -0,0 +1,35 @@
+# encoding: UTF-8
+require 'rubygems'
+require 'bundler' unless defined?(Bundler)
+
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+require 'acts_as_meritocracy/version'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.test_files = Dir.glob("test/**/*_test.rb")
+  test.verbose = true
+end
+
+task :build do
+  system "gem build acts_as_meritocracy.gemspec"
+end
+
+task :release => :build do
+
+  system "gem push acts_as_meritocracy-#{ActsAsMeritocracy::VERSION}.gem"
+  system "rm acts_as_meritocracy-#{ActsAsMeritocracy::VERSION}.gem"
+end
+
+task :default => :test

data/lib/acts_as_meritocracy.rb

@@ -0,0 +1,6 @@
+require "acts_as_meritocracy/model"
+
+
+if defined?(ActiveRecord::Base)
+  ActiveRecord::Base.send :include, ActsAsMeritocracy
+end

data/lib/acts_as_meritocracy/model.rb

@@ -0,0 +1,157 @@
+module ActsAsMeritocracy #:nodoc:
+
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+
+    # Example:
+    #   class User < ActiveRecord::Base
+    #     acts_as_meritocracy {:min_votes=>, :max_votes=>}}
+    #   end
+    def acts_as_meritocracy(options={})
+
+      # todo trigger action when decision is reliable
+      # acts_as_meritocracy {:quorum=>, :min_consensus=>}}
+      #adding class attribute
+      #class_attribute :_min_votes, :_max_votes, :_consensus, :_status_update_fct
+      #self._min_votes=options[:min_votes] || 3
+      #self._max_votes=options[:max_votes] || 6
+      #self._consensus=options[:consensus] || 0.7
+      #self._status_update_fct=options[:on_status_change] || :decision_updated
+
+      has_many :votes, :as => :voteable, :dependent => :destroy
+      has_many :voters, :through => :votes
+      attr_accessible :voters, :score, :num_votes, :entropy # entropy
+
+
+      scope :voted_by, lambda { |user|
+        joins(:votes).where("votes.voteable_type = ?", self.name).where("votes.voter_id=?", user.id)
+      }
+
+      include ActsAsMeritocracy::InstanceMethods
+      extend ActsAsMeritocracy::SingletonMethods
+    end
+  end
+
+  module SingletonMethods
+
+  end
+
+  module InstanceMethods
+
+
+    def voted_by?(user)
+      self.votes.exists?(:voter_id=>user.id)
+    end
+
+    # number of votes taking into account (or not) the weight of the vote
+    # 1 vote with vote_weight=2 ==>  2 votes
+    def nb_votes(weighted=true)
+      if (weighted)
+        self.votes.sum('vote_weight')
+      else
+        self.votes.count
+      end
+    end
+
+    # retrieve the vote distribution
+    def vote_distribution
+      Vote.select("vote, sum(vote_weight) as freq").where(:voteable_id=>self.id).group(:vote).order("freq DESC")
+    end
+
+    #majority vote (get the decision with the higher number of votes)
+    def best_decision(tie_method="random")
+      best=nil
+      tie=[]
+      nb_categories=0
+      self.vote_distribution.each { |category|
+        if ((best.nil?) || (category.freq>best.freq))
+          best=category
+          tie=[]
+          tie<<category
+          # managing tie
+        elsif (category.freq==best.freq)
+          tie<<category
+        end
+        nb_categories=nb_categories+1
+      }
+
+      # tie detected
+      if (tie.size>1)
+        case (tie_method)
+          when "random" then
+            tie[rand(tie.size)].vote
+          when "nodecision" then
+            nil
+        end
+        # no vote
+      elsif (best.nil?)
+        nil
+        # get the most chosen category
+      else
+        best.vote
+      end
+    end
+
+    # Consensus score  using the vote distribubtion
+    # very high consensus=1 , very low consensus=0
+    # could be used as an indicator to measure the difficulty of users to take collectively a decision
+    # 2 methods are proposed
+    # - Entropy
+    # - Fleiss Kappa taking into account the weight (NOTE: I removed the pb of chance in the computation)
+    def consensus(method="kappa")
+      consensus= case method
+                   when "entropy" then
+                     dist=self.vote_distribution
+                     nb_votes=dist.inject(0) { |sum, category| sum+category.freq }.to_f
+                     h=self.vote_distribution.inject(0) { |h, category|
+                       p_j=category.freq.to_f/nb_votes
+                       h + p_j*Math.log(p_j)
+                     }
+                     h=[h, -1].max
+                     1+h
+
+                   when "kappa" then
+                     dist=self.vote_distribution
+                     nb_votes=dist.inject(0) { |sum, category| sum+category.freq }.to_f
+                     fact=dist.inject(0) { |fact, category|
+                       fact+category.freq**2
+                     }
+                     (fact-nb_votes)/(nb_votes*(nb_votes-1))
+                   else
+                     0
+                 end
+      consensus
+    end
+
+    #submit or update the vote of someone
+    def submit_vote(user, vote, vote_weight=1)
+
+      #check existence
+      v=Vote.where(:voter_id=>user.id, :voteable_id=>self.id, :voteable_type => self.class.name).first
+
+      #if not create new vote
+      if (v.nil?)
+        v=Vote.create(:voter=>user,
+                      :voteable=>self,
+                      :vote=>vote,
+                      :vote_weight=>vote_weight)
+        #modify existing vote
+      else
+        v.update_attributes(:vote=>vote, :vote_weight=>vote_weight)
+      end
+      v
+    end
+
+    protected
+
+    def trigger_decision
+      # if we are enough sure of the decision  we trigger an action
+      if (nb_votes>=self.class._min_votes && consensus>self.class._consensus_ratio)
+         #we trigger an action
+      end
+    end
+  end
+end

data/lib/acts_as_meritocracy/version.rb

@@ -0,0 +1,3 @@
+module ActsAsMeritocracy
+	VERSION = '0.2'
+end

data/lib/generators/acts_as_meritocracy/migration/migration_generator.rb

@@ -0,0 +1,38 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module Model
+  class MigrationGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+
+    desc "Generates migration for Votes models"
+
+    def self.orm
+      Rails::Generators.options[:rails][:orm]
+    end
+
+    def self.source_root
+      File.join(File.dirname(__FILE__), 'templates', (orm.to_s unless orm.class.eql?(String)) )
+    end
+
+    def self.orm_has_migration?
+      [:active_record].include? orm
+    end
+
+    def self.next_migration_number(dirname)
+      if ActiveRecord::Base.timestamped_migrations
+        migration_number = Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
+        migration_number += 1
+        migration_number.to_s
+      else
+        "%.3d" % (current_migration_number(dirname) + 1)
+      end
+    end
+
+    def create_migration_file
+      if self.class.orm_has_migration?
+        migration_template 'migration.rb', 'db/migrate/acts_as_taggable_on_migration'
+      end
+    end
+  end
+end

data/lib/generators/acts_as_meritocracy/migration/templates/active_record/migration.rb

@@ -0,0 +1,20 @@
+class ActsAsTaggableOnMigration < ActiveRecord::Migration
+
+  def self.up
+    create_table :votes, :force => true do |t|
+      t.integer :voter_id, :limit => 11
+      t.references :voteable, :polymorphic=>true
+      t.integer :vote_weight, :default=>1
+      t.integer :vote, :default=>1
+      t.datetime :updated_at
+      t.datetime :created_at
+    end
+    add_index :votes, :tag_id
+    add_index :votes, [:voteable_id, :voteable_type]
+  end
+
+  def self.down
+    drop_table :votes
+  end
+
+end

data/lib/generators/acts_as_meritocracy/migration/templates/active_record/vote.rb

@@ -0,0 +1,21 @@
+
+# inspired by thumb_up gem
+# https://raw.github.com/brady8/thumbs_up/
+
+class Vote < ActiveRecord::Base
+
+  scope :for_voter, lambda { |*args| where(["voter_id = ?", args.first.id]) }
+  scope :for_voteable, lambda { |*args| where(["voteable_id = ? AND voteable_type = ?", args.first.id, args.first.class.base_class.name]) }
+  scope :recent, lambda { |*args| where(["created_at > ?", (args.first || 2.weeks.ago)]) }
+  scope :descending, order("created_at DESC")
+
+  belongs_to :voteable, :polymorphic => true
+
+  belongs_to :voter, :class_name=>"User"
+
+  attr_accessible :vote, :voter, :voteable, :vote_weight
+
+  # Comment out the line below to allow multiple votes per user.
+  validates_uniqueness_of :voteable_id, :scope => [:voteable_type, :voter_id]
+
+end

data/rails/init.rb

@@ -0,0 +1,10 @@
+RAILS_DEFAULT_LOGGER.info "** acts_as_meritocracy: setting up load paths **"
+
+%w{ models controllers helpers }.each do |dir|
+  path = File.join(File.dirname(__FILE__), 'lib', dir)
+  $LOAD_PATH << path
+  ActiveSupport::Dependencies.autoload_paths << path
+  ActiveSupport::Dependencies.autoload_once_paths.delete(path)
+end
+
+require 'acts_as_meritocracy'

data/test/meritocracy_test.rb

@@ -0,0 +1,55 @@
+require File.join(File.expand_path(File.dirname(__FILE__)), 'test_helper')
+
+class MeritocracyTest < Test::Unit::TestCase
+  def setup
+    Vote.delete_all
+    User.delete_all
+    Item.delete_all
+
+
+  end
+
+  def test_acts_as_meritocracy_methods
+    user1 = User.create!()
+    user2 = User.create!()
+    user3 = User.create!()
+    user4=User.create!()
+
+    item = Item.create!()
+
+    item.submit_vote(user1, 4) #user1 votes for the decision 4,  by default the vote_weight=1
+    item.submit_vote(user2, 1, 2) #user2 votes for the decision 1 with a vote_weight=2. A vote_weight=2 means that the voter has a vote equal to 2 normal voters (vote_weight=1)
+    item.submit_vote(user1, 1) #user1 can change/update her vote
+    item.submit_vote(user3, 2) #user3 vote for decision 2
+    item.submit_vote(user4, 3, 5) #user3 vote for decision 2
+
+    assert_equal 9, item.nb_votes
+
+    dist=item.vote_distribution
+
+    assert_equal 3, dist[0].vote
+    assert_equal 5, dist[0].freq
+    assert_equal 1, dist[1].vote
+    assert_equal 3, dist[1].freq
+
+    assert_equal 0.361, item.consensus.round(3) #fleiss kappa taking into account the weight
+    assert_equal 0.063, item.consensus("entropy").round(3)
+
+
+    #everyone agrees
+    item2 = Item.create!()
+    item2.submit_vote(user1, 1)
+    item2.submit_vote(user2, 1, 3)
+    item2.submit_vote(user3, 1, 2)
+    assert_equal 1, item2.consensus
+
+    #everyone disagrees
+    item3 = Item.create!()
+    item3.submit_vote(user1, 1)
+    item3.submit_vote(user2, 2)
+
+
+    assert_equal 0.0, item3.consensus #entropy
+
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,61 @@
+require 'test/unit'
+
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+
+#require 'simplecov'
+#SimpleCov.start
+
+require 'active_record'
+require 'logger'
+
+
+TEST_DATABASE_FILE = File.join(File.dirname(__FILE__), '..', 'test.sqlite3')
+File.unlink(TEST_DATABASE_FILE) if File.exist?(TEST_DATABASE_FILE)
+ActiveRecord::Base.establish_connection :adapter => 'sqlite3', :database => TEST_DATABASE_FILE
+
+ActiveRecord::Migration.verbose = true
+#ActiveRecord::Base.logger = Logger.new(STDOUT)
+ActiveRecord::Schema.define do
+
+  create_table :votes, :force => true do |t|
+    t.integer :voter_id, :default => false
+    t.integer :vote, :default => false
+    t.references :voteable, :polymorphic => true, :null => false
+    t.integer :vote_weight, :default=>1
+    t.timestamps
+  end
+
+  create_table :users, :force => true do |t|
+    t.timestamps
+  end
+
+  create_table :items, :force => true do |t|
+  end
+end
+
+
+require 'acts_as_meritocracy'
+
+class User < ActiveRecord::Base
+end
+
+
+class Vote < ActiveRecord::Base
+  belongs_to :voteable, :polymorphic => true
+  belongs_to :voter, :class_name=>"User"
+  attr_accessible :vote, :voter, :voteable, :vote_weight
+
+  # Comment out the line below to allow multiple votes per user.
+  validates_uniqueness_of :voteable_id, :scope => [:voteable_type, :voter_id]
+end
+
+class Item < ActiveRecord::Base
+  acts_as_meritocracy
+end
+
+
+class Test::Unit::TestCase
+end

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: acts_as_meritocracy
+version: !ruby/object:Gem::Version
+  version: '0.2'
+  prerelease: 
+platform: ruby
+authors:
+- Nicolas Maisonneuve
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-03-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Weighted majority voting system for qualitative (categorical) items (i.e.assuming
+  the set of decision has no natural ordering). As a measure of the quality of the
+  consensus/inter-agreement, you can choose between a weighted variant of fleiss Kappa  (by
+  default) or the entropy of the vote distribution
+email:
+- n.maisonneuve.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/acts_as_meritocracy/model.rb
+- lib/acts_as_meritocracy/version.rb
+- lib/acts_as_meritocracy.rb
+- lib/generators/acts_as_meritocracy/migration/migration_generator.rb
+- lib/generators/acts_as_meritocracy/migration/templates/active_record/migration.rb
+- lib/generators/acts_as_meritocracy/migration/templates/active_record/vote.rb
+- rails/init.rb
+- test/meritocracy_test.rb
+- test/test_helper.rb
+- Gemfile
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+homepage: https://github.com/nmaisonneuve/acts_as_meritocracy
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -127910143
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.0
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.21
+signing_key: 
+specification_version: 3
+summary: Weighted voting system for deliberation.
+test_files: []