projects.mako.cc - rubyvote/blob - 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