projects.mako.cc - rubyvote/blob - README

   1 RubyVote: Election Methods Library in Ruby
   2 ===========================================
   3
   4 :Author: Benjamin Mako Hill
   5 :Copyright: MIT Media Lab and MIT
   6 :License: GNU GPL
   7
   8 Summary
   9 --------
  10
  11 **Version:** 0.1
  12
  13 This software includes an set of classes to tally votes and compute
  14 winners in elections or votes using a series of different
  15 methods. Currrently these include:
  16
  17 * Plurality or "winner-take-all"
  18 * Approval
  19 * Borda
  20 * Simple Condorcet
  21 * Condorcet with Cloneproof SSD
  22
  23 More information can be found at the following pages:
  24
  25 * http://en.wikipedia.org/wiki/Plurality_electoral_system
  26 * http://en.wikipedia.org/wiki/Approval_voting
  27 * http://en.wikipedia.org/wiki/Borda_count
  28 * http://en.wikipedia.org/wiki/Condorcet_method
  29 * http://en.wikipedia.org/wiki/Shulze_method
  30
  31 Writing support for a new module (e.g., instant runnof voting) is a
  32 fantastic way to to contribute to this module.
  33
  34 This software is prerelease software. I am both a relatively new Ruby
  35 progreammming and relatively new to election methods. These election
  36 methods have bugs and may have bugs that skew results. If you are
  37 understand Ruby and election methods, please do me a favor and audit
  38 my code.
  39
  40
  41
  42 How To Use This Library
  43 -------------------------
  44
  45 Using this library is relatively simple but will differ per election
  46 methods. In each case, you will need to ``require`` the appropriate
  47 file for the type of election you will be running and then create a
  48 new vote object. You should then either pass an array of votes to the
  49 object upon creation or pass votes in one at at a time.
  50
  51
  52 .. Note:: *You* are responsible for ensuring that the votes are in
  53           correct form before you hand them to this module. This will
  54           not currently check for most types of invalid votes and does
  55           not (currently) accept a list of candidates at creation from
  56           which it checks all votes. As such, new candidates will be
  57           created when seen. If you think this is a meaningful
  58           addition to this library, please send a patch. Otherwise,
  59           please check for the validity of votes BEFORE you pass them
  60           to this election module.
  61
  62 Examples of each type of election currently supported can be seen in
  63 the test.rb file distributed in this archive.
  64
  65 ElectionVote Objects
  66 *********************
  67
  68 Each ElectionVote object has the following exposed attributions:
  69
  70 * ElectionVote#votes -- returns a list of votes that have been tallied
  71 * ElectionVote#candidates -- returns a list of candidates
  72
  73 Additionally, each subclass will create a #results method which will
  74 return an ElectionResult subclass of the appropriate type.
  75
  76 Currently, you use this module by creating any of the following types
  77 of vote objects:
  78
  79 Plurality
  80 ^^^^^^^^^^
  81
  82 This is the most simple "winner-take-all" system. The array passed to
  83 the new vote object should be an array of strings. Each string is
  84 counted as one vote for a candidate.
  85
  86 Example::
  87
  88  require 'election'
  89  vote_array = [ "A", "B", "B", "A" ]
  90  resultobject = PluralityVote.new(vote_array).result
  91
  92 Approval
  93 ^^^^^^^^^
  94
  95 Approval is similar to plurality voting except that users can vote for
  96 more than one candidate at once naming all of the candidates that they
  97 approve of.
  98
  99 Example::
 100
 101  require 'election'
 102  vote_array = [ ["A", "B"],  ["B", "A"], ["B"] ]
 103  resultobject = ApprovalVote.new(vote_array).result
 104
 105 Borda
 106 ^^^^^^
 107
 108 Borda is a positional voting system and, as a result, takes a list of
 109 ranked candidates and assigns points to each candidates based on their
 110 order. In Borda, there are *n* candidate and the first candidates is
 111 assigned *n* - 1 points and each subsequent candidate is assigned one
 112 less point. The candidate is assigned no points.
 113
 114 Currently, all candidates should be ranked in each ballot.
 115
 116 Example::
 117
 118  require 'positional'
 119  vote_array = [ ["A", "B"],  ["B", "A"], ["B", "A"] ]
 120  resultobject = BordaVote.new(vote_array).result
 121
 122 Pure Condorcet
 123 ^^^^^^^^^^^^^^^^
 124
 125 Condorcet is a preferential system and, as such, each vote must list
 126 of ranked preferences from most to least preferred. Currently, all
 127 candidates must be listed. No ties are allowed on ballots with the
 128 current implementation.
 129
 130 Example::
 131
 132  require 'condorcet'
 133  vote_array = [ ["A", "B"],  ["B", "A"], ["B", "A"] ]
 134  resultobject = PureCondorcetVote.new(vote_array).result
 135
 136 Cloneproof Schwartz Sequential Dropping
 137 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 138
 139 `Cloneproof SSD` is a Condorcet variant with the ability to create
 140 winners in circular defeats (e.g., A beats B, B beats C, C beats A)
 141 where this is no clear winner in Condorcet. It is used identically to
 142 Pure Condorcet.
 143
 144 Example::
 145
 146  require 'condorcet'
 147  vote_array = [ ["A", "B"],  ["B", "A"], ["B", "A"] ]
 148  resultobject = CloneproofSSDVote.new(vote_array).result
 149
 150 ElectionResult Objects
 151 ***********************
 152
 153 Each election result object will have the following methods:
 154
 155 * #winner? -- return boolean as to the winner or winners of an election
 156 * #winners -- an array of winners of the election
 157 * #ranked_candidates -- (where available) a list of ranked candidates
 158
 159
 160 License
 161 --------
 162
 163 This program is free software; you can redistribute it and/or modify
 164 it under the terms of the GNU General Public License as published by
 165 the Free Software Foundation; either version 2 of the License, or (at
 166 your option) any later version.
 167
 168 This program is distributed in the hope that it will be useful, but
 169 WITHOUT ANY WARRANTY; without even the implied warranty of
 170 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 171 General Public License for more details.
 172
 173 You should have received a copy of the GNU General Public License
 174 along with this program; if not, write to the Free Software
 175 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 176 02110-1301, USA.
 177
 178 Look in the COPYING file for the text of the GNU GPL.
 179
 180 Authors
 181 --------
 182
 183 Currently, the only contributor to this program is Benjamin Mako Hill
 184 working at the MIT Media Lab. Please feel free to contribute to this
 185 module and get your name added here.
 186
 187 For more information about Mako and his programs, you can seee his
 188 homepage here:
 189
 190  http://mako.cc
 191
 192 For more information about the MIT Media Lab, you can see its homepage
 193 here:
 194
 195  http://www.media.mit.edu
 196