1 RubyVote: Election Methods Library in Ruby
2 ===========================================
4 :Author: Benjamin Mako Hill
5 :Copyright: MIT Media Lab and MIT
13 This software includes an set of classes to tally votes and compute
14 winners in elections or votes using a series of different
15 methods. Currrently these include:
17 * Plurality or "winner-take-all"
21 * Condorcet with Cloneproof SSD
23 More information can be found at the following pages:
25 * http://en.wikipedia.org/wiki/Plurality_electoral_system
26 * http://en.wikipedia.org/wiki/Approval_voting
27 * http://en.wikipedia.org/wiki/Borda_count
28 * http://en.wikipedia.org/wiki/Condorcet_method
29 * http://en.wikipedia.org/wiki/Shulze_method
31 Writing support for a new module (e.g., instant runnof voting) is a
32 fantastic way to to contribute to this module.
34 This software is prerelease software. I am both a relatively new Ruby
35 progreammming and relatively new to election methods. These election
36 methods have bugs and may have bugs that skew results. If you are
37 understand Ruby and election methods, please do me a favor and audit
42 How To Use This Library
43 -------------------------
45 Using this library is relatively simple but will differ per election
46 methods. In each case, you will need to ``require`` the appropriate
47 file for the type of election you will be running and then create a
48 new vote object. You should then either pass an array of votes to the
49 object upon creation or pass votes in one at at a time.
52 .. Note:: *You* are responsible for ensuring that the votes are in
53 correct form before you hand them to this module. This will
54 not currently check for most types of invalid votes and does
55 not (currently) accept a list of candidates at creation from
56 which it checks all votes. As such, new candidates will be
57 created when seen. If you think this is a meaningful
58 addition to this library, please send a patch. Otherwise,
59 please check for the validity of votes BEFORE you pass them
60 to this election module.
62 Examples of each type of election currently supported can be seen in
63 the test.rb file distributed in this archive.
68 Each ElectionVote object has the following exposed attributions:
70 * ElectionVote#votes -- returns a list of votes that have been tallied
71 * ElectionVote#candidates -- returns a list of candidates
73 Additionally, each subclass will create a #results method which will
74 return an ElectionResult subclass of the appropriate type.
76 Currently, you use this module by creating any of the following types
82 This is the most simple "winner-take-all" system. The array passed to
83 the new vote object should be an array of strings. Each string is
84 counted as one vote for a candidate.
89 vote_array = [ "A", "B", "B", "A" ]
90 resultobject = PluralityVote.new(vote_array).result
95 Approval is similar to plurality voting except that users can vote for
96 more than one candidate at once naming all of the candidates that they
102 vote_array = [ ["A", "B"], ["B", "A"], ["B"] ]
103 resultobject = ApprovalVote.new(vote_array).result
108 Borda is a positional voting system and, as a result, takes a list of
109 ranked candidates and assigns points to each candidates based on their
110 order. In Borda, there are *n* candidate and the first candidates is
111 assigned *n* - 1 points and each subsequent candidate is assigned one
112 less point. The candidate is assigned no points.
114 Currently, all candidates should be ranked in each ballot.
119 vote_array = [ ["A", "B"], ["B", "A"], ["B", "A"] ]
120 resultobject = BordaVote.new(vote_array).result
125 Condorcet is a preferential system and, as such, each vote must list
126 of ranked preferences from most to least preferred. Currently, all
127 candidates must be listed. No ties are allowed on ballots with the
128 current implementation.
133 vote_array = [ ["A", "B"], ["B", "A"], ["B", "A"] ]
134 resultobject = PureCondorcetVote.new(vote_array).result
136 Cloneproof Schwartz Sequential Dropping
137 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
139 `Cloneproof SSD` is a Condorcet variant with the ability to create
140 winners in circular defeats (e.g., A beats B, B beats C, C beats A)
141 where this is no clear winner in Condorcet. It is used identically to
147 vote_array = [ ["A", "B"], ["B", "A"], ["B", "A"] ]
148 resultobject = CloneproofSSDVote.new(vote_array).result
150 ElectionResult Objects
151 ***********************
153 Each election result object will have the following methods:
155 * #winner? -- return boolean as to the winner or winners of an election
156 * #winners -- an array of winners of the election
157 * #ranked_candidates -- (where available) a list of ranked candidates
163 This program is free software; you can redistribute it and/or modify
164 it under the terms of the GNU General Public License as published by
165 the Free Software Foundation; either version 2 of the License, or (at
166 your option) any later version.
168 This program is distributed in the hope that it will be useful, but
169 WITHOUT ANY WARRANTY; without even the implied warranty of
170 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
171 General Public License for more details.
173 You should have received a copy of the GNU General Public License
174 along with this program; if not, write to the Free Software
175 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
178 Look in the COPYING file for the text of the GNU GPL.
183 Currently, the only contributor to this program is Benjamin Mako Hill
184 working at the MIT Media Lab. Please feel free to contribute to this
185 module and get your name added here.
187 For more information about Mako and his programs, you can seee his
192 For more information about the MIT Media Lab, you can see its homepage
195 http://www.media.mit.edu