5a27dcd6f930939fe8b7b474334bdb8702a4a549
[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.1
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
64 __ http://en.wikipedia.org/wiki/Plurality_electoral_system
65 __ http://en.wikipedia.org/wiki/Approval_voting
66 __ http://en.wikipedia.org/wiki/Borda_count
67 __ http://en.wikipedia.org/wiki/Condorcet_method
68 __ http://en.wikipedia.org/wiki/Shulze_method
69
70 Writing support for a currently unsupported voting method (e.g., instant
71 runoff voting) is a fantastic way to to contribute to this module.
72
73 How To Use This Library
74 -------------------------
75
76 Using this library is relatively simple but will differ per election
77 methods. In each case, you will need to ``require`` the appropriate
78 file for the type of election you will be running and then create a
79 new vote object. You should then either pass an array of votes to the
80 object upon creation or pass votes in one at at a time.
81
82
83 .. Note::
84
85    *You* are responsible for ensuring that the votes are in correct
86    form before you hand them to this module. This will not currently
87    check for most types of invalid votes and does not (currently)
88    accept a list of candidates at creation from which it checks all
89    votes. As such, new candidates will be created when seen. If you
90    think this is a meaningful addition to this library, please send a
91    patch. Otherwise, please check for the validity of votes BEFORE you
92    pass them to this election module.
93
94 Examples of each type of election currently supported can be seen in
95 the test.rb file distributed in this archive.
96
97 ElectionVote Objects
98 *********************
99
100 Each ElectionVote object has the following exposed attributions:
101
102 * ElectionVote#votes -- returns a list of votes that have been tallied
103 * ElectionVote#candidates -- returns a list of candidates
104
105 Additionally, each subclass will create a #results method which will
106 return an ElectionResult subclass of the appropriate type.
107
108 Currently, you use this module by creating any of the following types
109 of vote objects:
110
111 Plurality
112 ^^^^^^^^^^
113
114 This is the most simple "winner-take-all" system. The array passed to
115 the new vote object should be an array of strings. Each string is
116 counted as one vote for a candidate.
117
118 Example::
119
120  require 'election'
121  vote_array = [ "A", "B", "B", "A" ]
122  resultobject = PluralityVote.new(vote_array).result
123
124 Approval
125 ^^^^^^^^^
126
127 Approval is similar to plurality voting except that users can vote for
128 more than one candidate at once naming all of the candidates that they
129 approve of.
130
131 Example::
132
133  require 'election'
134  vote_array = [ ["A", "B"],  ["B", "A"], ["B"] ]
135  resultobject = ApprovalVote.new(vote_array).result
136
137 Borda
138 ^^^^^^
139
140 Borda is a positional voting system and, as a result, takes a list of
141 ranked candidates and assigns points to each candidates based on their
142 order. In Borda, there are *n* candidate and the first candidates is
143 assigned *n* - 1 points and each subsequent candidate is assigned one
144 less point. The candidate is assigned no points.
145
146 Currently, all candidates should be ranked in each ballot.
147
148 Example::
149
150  require 'positional'
151  vote_array = [ ["A", "B"],  ["B", "A"], ["B", "A"] ]
152  resultobject = BordaVote.new(vote_array).result
153
154 Pure Condorcet
155 ^^^^^^^^^^^^^^^^
156
157 Condorcet is a preferential system and, as such, each vote must list
158 of ranked preferences from most to least preferred. Currently, all
159 candidates must be listed. No ties are allowed on ballots with the
160 current implementation.
161
162 Example::
163
164  require 'condorcet'
165  vote_array = [ ["A", "B"],  ["B", "A"], ["B", "A"] ]
166  resultobject = PureCondorcetVote.new(vote_array).result
167
168 Cloneproof Schwartz Sequential Dropping
169 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
170
171 `Cloneproof SSD` is a Condorcet variant with the ability to create
172 winners in circular defeats (e.g., A beats B, B beats C, C beats A)
173 where this is no clear winner in Condorcet. It is used identically to
174 Pure Condorcet.
175
176 Example::
177
178  require 'condorcet'
179  vote_array = [ ["A", "B"],  ["B", "A"], ["B", "A"] ]
180  resultobject = CloneproofSSDVote.new(vote_array).result
181
182 ElectionResult Objects
183 ***********************
184
185 Each election result object will have the following methods:
186
187 * #winner? -- return Boolean as to the winner or winners of an election
188 * #winners -- an array of winners of the election
189 * #ranked_candidates -- (where available) a list of ranked candidates
190
191
192 License
193 --------
194
195 This program is free software; you can redistribute it and/or modify
196 it under the terms of the GNU General Public License as published by
197 the Free Software Foundation; either version 2 of the License, or (at
198 your option) any later version.
199
200 This program is distributed in the hope that it will be useful, but
201 WITHOUT ANY WARRANTY; without even the implied warranty of
202 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
203 General Public License for more details.
204
205 You should have received a copy of the GNU General Public License
206 along with this program; if not, write to the Free Software
207 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
208 02110-1301, USA.
209
210 Look in the COPYING file for the text of the GNU GPL.
211
212 Authors
213 --------
214
215 Currently, the only contributor to this program is Benjamin Mako Hill
216 working at the MIT Media Lab. Please feel free to contribute to this
217 module and get your name added here.
218
219 For more information about Mako and his programs, you can see his
220 homepage here:
221
222  http://mako.cc
223
224 For more information about the MIT Media Lab, you can see its homepage
225 here:
226
227  http://www.media.mit.edu
228

Benjamin Mako Hill || Want to submit a patch?