projects.mako.cc - rubyvote/blob - README.rst

   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/Schulze_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