simplify access to full results - now available as voteobject.results,
[rubyvote] / README
1 RubyVote: Election Methods Library in Ruby
2 =============================================
3
4 .. Caution::
5
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
11    the code.
12
13 Overview
14 ---------
15
16 **Latest Version:** 0.2
17
18 **Download Latest Version:** `here
19 <http://rubyforge.org/projects/rubyvote>`__
20
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
25 decision making.
26
27 New Versions
28 *************
29
30 `RubyVote` is graciously hosted by `RubyForge
31 <http://rubyforge.org/>`__.
32
33 You can visit the `RubyVote` homepage (a version of this file) here:
34
35  http://rubyvote.rubyforge.org/
36
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
41 is here:
42
43  http://rubyforge.org/projects/rubyvote
44
45
46 More Information
47 *****************
48
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).
53
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:
57
58 * `Plurality`__ or "winner-take-all"
59 * `Approval`__
60 * `Borda`__
61 * `Simple Condorcet`__
62 * `Condorcet with Cloneproof SSD`__
63 * `Instant Runnoff Voting`__ (Thanks Alexis Darrasse!)
64
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
71
72 Writing support for a currently unsupported voting method is a fantastic
73 way to to contribute to this module.
74
75 How To Use This Library
76 -------------------------
77
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.
83
84
85 .. Note::
86
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.
95
96 Examples of each type of election currently supported can be seen in
97 the test.rb file distributed in this archive.
98
99 ElectionVote Objects
100 *********************
101
102 Each ElectionVote object has the following exposed attributions:
103
104 * ElectionVote#votes -- returns a list of votes that have been tallied
105 * ElectionVote#candidates -- returns a list of candidates
106
107 Additionally, each subclass will create a #results method which will
108 return an ElectionResult subclass of the appropriate type.
109
110 Currently, you use this module by creating any of the following types
111 of vote objects:
112
113 Plurality
114 ^^^^^^^^^^
115
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.
119
120 Example::
121
122  require 'election'
123  vote_array = [ "A", "B", "B", "A" ]
124  resultobject = PluralityVote.new(vote_array).result
125
126 Approval
127 ^^^^^^^^^
128
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
131 approve of.
132
133 Example::
134
135  require 'election'
136  vote_array = [ ["A", "B"],  ["B", "A"], ["B"] ]
137  resultobject = ApprovalVote.new(vote_array).result
138
139 Borda
140 ^^^^^^
141
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.
147
148 Currently, all candidates should be ranked in each ballot.
149
150 Example::
151
152  require 'positional'
153  vote_array = [ ["A", "B"],  ["B", "A"], ["B", "A"] ]
154  resultobject = BordaVote.new(vote_array).result
155
156 Pure Condorcet
157 ^^^^^^^^^^^^^^^^
158
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.
163
164 Example::
165
166  require 'condorcet'
167  vote_array = [ ["A", "B"],  ["B", "A"], ["B", "A"] ]
168  resultobject = PureCondorcetVote.new(vote_array).result
169
170 Cloneproof Schwartz Sequential Dropping
171 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
172
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
176 Pure Condorcet.
177
178 Example::
179
180  require 'condorcet'
181  vote_array = [ ["A", "B"],  ["B", "A"], ["B", "A"] ]
182  resultobject = CloneproofSSDVote.new(vote_array).result
183
184 Instant Runnoff Voting (IRV)
185 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
186
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
192 remaining votes.
193
194 Example::
195
196  require 'runoff'
197  vote_array = [ ["A", "B"],  ["B", "A"], ["B", "A"] ]
198  resultobject = InstantRunoffVote.new(vote_array).result
199
200
201 ElectionResult Objects
202 ***********************
203
204 Each election result object will have the following methods:
205
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
209
210
211 License
212 --------
213
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.
218
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.
223
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
227 02110-1301, USA.
228
229 Look in the COPYING file for the text of the GNU GPL.
230
231 Authors
232 --------
233
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.
237
238 For more information about Mako and his programs, you can see his
239 homepage here:
240
241  http://mako.cc
242
243 For more information about the MIT Media Lab, you can see its homepage
244 here:
245
246  http://www.media.mit.edu
247

Benjamin Mako Hill || Want to submit a patch?