acts_as_meritocracy

= 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.