X-Git-Url: https://projects.mako.cc/source/rubyvote/blobdiff_plain/e86f1766c33b3486c3fa8f8b3a497f1614e33055..7e0dfa29ded0609d46bdc685711ce866ad89e3c5:/README.rst diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..2d69455 --- /dev/null +++ b/README.rst @@ -0,0 +1,228 @@ +RubyVote: Election Methods Library in Ruby +============================================= + +.. Caution:: + + This software is pre release software. The authors of this software + are neither expert Ruby programmers or elections in election + methods. We are hackers and enthusiasts in both. This software has + bugs and it's quite possible that is has bugs that may skew + results. If you understand Ruby or election methods, please audit + the code. + +Overview +--------- + +**Latest Version:** 0.1 + +**Download Latest Version:** `here +`__ + +`RubyVote` is an election methods library implemented in Ruby. It is +designed to make it very easy to implement a variety of different types +of elections in Ruby including relatively complex election methods like +Condorcet. It could be useful for any sort of election, poll, or +decision making. + +New Versions +************* + +`RubyVote` is graciously hosted by `RubyForge +`__. + +You can visit the `RubyVote` homepage (a version of this file) here: + + http://rubyvote.rubyforge.org/ + +You can visit the RubyForge project page to download the latest +version of software, get access to the latest development version from +Subversion, to file or bug, to look through documentation, to +participate in the forums, or to contribute in other ways. That page +is here: + + http://rubyforge.org/projects/rubyvote + + +More Information +***************** + +`RubyVote` is a library -- not an application or a voting machine. It +simply takes the raw "tallies" of votes and computes the results. +Currently, it does not include any sample interfaces (although if +contributed, these may be included). + +`RubyVote` current includes a set of classes to tally votes and compute +winners in elections or votes using a series of different methods. +Currently these include: + +* `Plurality`__ or "winner-take-all" +* `Approval`__ +* `Borda`__ +* `Simple Condorcet`__ +* `Condorcet with Cloneproof SSD`__ + +__ http://en.wikipedia.org/wiki/Plurality_electoral_system +__ http://en.wikipedia.org/wiki/Approval_voting +__ http://en.wikipedia.org/wiki/Borda_count +__ http://en.wikipedia.org/wiki/Condorcet_method +__ http://en.wikipedia.org/wiki/Schulze_method + +Writing support for a currently unsupported voting method (e.g., instant +runoff voting) is a fantastic way to to contribute to this module. + +How To Use This Library +------------------------- + +Using this library is relatively simple but will differ per election +methods. In each case, you will need to ``require`` the appropriate +file for the type of election you will be running and then create a +new vote object. You should then either pass an array of votes to the +object upon creation or pass votes in one at at a time. + + +.. Note:: + + *You* are responsible for ensuring that the votes are in correct + form before you hand them to this module. This will not currently + check for most types of invalid votes and does not (currently) + accept a list of candidates at creation from which it checks all + votes. As such, new candidates will be created when seen. If you + think this is a meaningful addition to this library, please send a + patch. Otherwise, please check for the validity of votes BEFORE you + pass them to this election module. + +Examples of each type of election currently supported can be seen in +the test.rb file distributed in this archive. + +ElectionVote Objects +********************* + +Each ElectionVote object has the following exposed attributions: + +* ElectionVote#votes -- returns a list of votes that have been tallied +* ElectionVote#candidates -- returns a list of candidates + +Additionally, each subclass will create a #results method which will +return an ElectionResult subclass of the appropriate type. + +Currently, you use this module by creating any of the following types +of vote objects: + +Plurality +^^^^^^^^^^ + +This is the most simple "winner-take-all" system. The array passed to +the new vote object should be an array of strings. Each string is +counted as one vote for a candidate. + +Example:: + + require 'election' + vote_array = [ "A", "B", "B", "A" ] + resultobject = PluralityVote.new(vote_array).result + +Approval +^^^^^^^^^ + +Approval is similar to plurality voting except that users can vote for +more than one candidate at once naming all of the candidates that they +approve of. + +Example:: + + require 'election' + vote_array = [ ["A", "B"], ["B", "A"], ["B"] ] + resultobject = ApprovalVote.new(vote_array).result + +Borda +^^^^^^ + +Borda is a positional voting system and, as a result, takes a list of +ranked candidates and assigns points to each candidates based on their +order. In Borda, there are *n* candidate and the first candidates is +assigned *n* - 1 points and each subsequent candidate is assigned one +less point. The candidate is assigned no points. + +Currently, all candidates should be ranked in each ballot. + +Example:: + + require 'positional' + vote_array = [ ["A", "B"], ["B", "A"], ["B", "A"] ] + resultobject = BordaVote.new(vote_array).result + +Pure Condorcet +^^^^^^^^^^^^^^^^ + +Condorcet is a preferential system and, as such, each vote must list +of ranked preferences from most to least preferred. Currently, all +candidates must be listed. No ties are allowed on ballots with the +current implementation. + +Example:: + + require 'condorcet' + vote_array = [ ["A", "B"], ["B", "A"], ["B", "A"] ] + resultobject = PureCondorcetVote.new(vote_array).result + +Cloneproof Schwartz Sequential Dropping +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +`Cloneproof SSD` is a Condorcet variant with the ability to create +winners in circular defeats (e.g., A beats B, B beats C, C beats A) +where this is no clear winner in Condorcet. It is used identically to +Pure Condorcet. + +Example:: + + require 'condorcet' + vote_array = [ ["A", "B"], ["B", "A"], ["B", "A"] ] + resultobject = CloneproofSSDVote.new(vote_array).result + +ElectionResult Objects +*********************** + +Each election result object will have the following methods: + +* #winner? -- return Boolean as to the winner or winners of an election +* #winners -- an array of winners of the election +* #ranked_candidates -- (where available) a list of ranked candidates + + +License +-------- + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or (at +your option) any later version. + +This program is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA +02110-1301, USA. + +Look in the COPYING file for the text of the GNU GPL. + +Authors +-------- + +Currently, the only contributor to this program is Benjamin Mako Hill +working at the MIT Media Lab. Please feel free to contribute to this +module and get your name added here. + +For more information about Mako and his programs, you can see his +homepage here: + + http://mako.cc + +For more information about the MIT Media Lab, you can see its homepage +here: + + http://www.media.mit.edu +