1 RubyVote: Election Methods Library in Ruby
2 =============================================
6 This software is pre release software. The authors of this software
7 are neither expert Ruby programmers or elections in election
8 methods. We are hackers and enthusiasts in both. This software has
9 bugs and it's quite possible that is has bugs that may skew
10 results. If you understand Ruby or election methods, please audit
16 **Latest Version:** 0.2
18 **Download Latest Version:** `here
19 <http://rubyforge.org/projects/rubyvote>`__
21 `RubyVote` is an election methods library implemented in Ruby. It is
22 designed to make it very easy to implement a variety of different types
23 of elections in Ruby including relatively complex election methods like
24 Condorcet. It could be useful for any sort of election, poll, or
30 `RubyVote` is graciously hosted by `RubyForge
31 <http://rubyforge.org/>`__.
33 You can visit the `RubyVote` homepage (a version of this file) here:
35 http://rubyvote.rubyforge.org/
37 You can visit the RubyForge project page to download the latest
38 version of software, get access to the latest development version from
39 Subversion, to file or bug, to look through documentation, to
40 participate in the forums, or to contribute in other ways. That page
43 http://rubyforge.org/projects/rubyvote
49 `RubyVote` is a library -- not an application or a voting machine. It
50 simply takes the raw "tallies" of votes and computes the results.
51 Currently, it does not include any sample interfaces (although if
52 contributed, these may be included).
54 `RubyVote` current includes a set of classes to tally votes and compute
55 winners in elections or votes using a series of different methods.
56 Currently these include:
58 * `Plurality`__ or "winner-take-all"
61 * `Simple Condorcet`__
62 * `Condorcet with Cloneproof SSD`__
63 * `Instant Runnoff Voting`__ (Thanks Alexis Darrasse!)
65 __ http://en.wikipedia.org/wiki/Plurality_electoral_system
66 __ http://en.wikipedia.org/wiki/Approval_voting
67 __ http://en.wikipedia.org/wiki/Borda_count
68 __ http://en.wikipedia.org/wiki/Condorcet_method
69 __ http://en.wikipedia.org/wiki/Schulze_method
70 __ http://en.wikipedia.org/wiki/Instant_Runoff_Voting
72 Writing support for a currently unsupported voting method is a fantastic
73 way to to contribute to this module.
75 How To Use This Library
76 -------------------------
78 Using this library is relatively simple but will differ per election
79 methods. In each case, you will need to ``require`` the appropriate
80 file for the type of election you will be running and then create a
81 new vote object. You should then either pass an array of votes to the
82 object upon creation or pass votes in one at at a time.
87 *You* are responsible for ensuring that the votes are in correct
88 form before you hand them to this module. This will not currently
89 check for most types of invalid votes and does not (currently)
90 accept a list of candidates at creation from which it checks all
91 votes. As such, new candidates will be created when seen. If you
92 think this is a meaningful addition to this library, please send a
93 patch. Otherwise, please check for the validity of votes BEFORE you
94 pass them to this election module.
96 Examples of each type of election currently supported can be seen in
97 the test.rb file distributed in this archive.
100 *********************
102 Each ElectionVote object has the following exposed attributions:
104 * ElectionVote#votes -- returns a list of votes that have been tallied
105 * ElectionVote#candidates -- returns a list of candidates
107 Additionally, each subclass will create a #results method which will
108 return an ElectionResult subclass of the appropriate type.
110 Currently, you use this module by creating any of the following types
116 This is the most simple "winner-take-all" system. The array passed to
117 the new vote object should be an array of strings. Each string is
118 counted as one vote for a candidate.
123 vote_array = [ "A", "B", "B", "A" ]
124 resultobject = PluralityVote.new(vote_array).result
129 Approval is similar to plurality voting except that users can vote for
130 more than one candidate at once naming all of the candidates that they
136 vote_array = [ ["A", "B"], ["B", "A"], ["B"] ]
137 resultobject = ApprovalVote.new(vote_array).result
142 Borda is a positional voting system and, as a result, takes a list of
143 ranked candidates and assigns points to each candidates based on their
144 order. In Borda, there are *n* candidate and the first candidates is
145 assigned *n* - 1 points and each subsequent candidate is assigned one
146 less point. The candidate is assigned no points.
148 Currently, all candidates should be ranked in each ballot.
153 vote_array = [ ["A", "B"], ["B", "A"], ["B", "A"] ]
154 resultobject = BordaVote.new(vote_array).result
159 Condorcet is a preferential system and, as such, each vote must list
160 of ranked preferences from most to least preferred. Currently, all
161 candidates must be listed. No ties are allowed on ballots with the
162 current implementation.
167 vote_array = [ ["A", "B"], ["B", "A"], ["B", "A"] ]
168 resultobject = PureCondorcetVote.new(vote_array).result
170 Cloneproof Schwartz Sequential Dropping
171 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
173 `Cloneproof SSD` is a Condorcet variant with the ability to create
174 winners in circular defeats (e.g., A beats B, B beats C, C beats A)
175 where this is no clear winner in Condorcet. It is used identically to
181 vote_array = [ ["A", "B"], ["B", "A"], ["B", "A"] ]
182 resultobject = CloneproofSSDVote.new(vote_array).result
184 Instant Runnoff Voting (IRV)
185 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
187 IRV is a preferential voting system used widely for government elections
188 in Australia and New Zealand and elsewhere. IRV asks voters to rank
189 candidates in preference and then holds a series of "runoff" elections
190 by eliminating the weakest candidate and recomputing the election
191 results until there exists a candidate who has a majority of the
197 vote_array = [ ["A", "B"], ["B", "A"], ["B", "A"] ]
198 resultobject = InstantRunoffVote.new(vote_array).result
201 ElectionResult Objects
202 ***********************
204 Each election result object will have the following methods:
206 * #winner? -- return Boolean as to the winner or winners of an election
207 * #winners -- an array of winners of the election
208 * #ranked_candidates -- (where available) a list of ranked candidates
214 This program is free software; you can redistribute it and/or modify
215 it under the terms of the GNU General Public License as published by
216 the Free Software Foundation; either version 2 of the License, or (at
217 your option) any later version.
219 This program is distributed in the hope that it will be useful, but
220 WITHOUT ANY WARRANTY; without even the implied warranty of
221 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
222 General Public License for more details.
224 You should have received a copy of the GNU General Public License
225 along with this program; if not, write to the Free Software
226 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
229 Look in the COPYING file for the text of the GNU GPL.
234 Currently, the only contributor to this program is Benjamin Mako Hill
235 working at the MIT Media Lab. Please feel free to contribute to this
236 module and get your name added here.
238 For more information about Mako and his programs, you can see his
243 For more information about the MIT Media Lab, you can see its homepage
246 http://www.media.mit.edu