README.md
1
2
3
4...is a Go library for conducting polls using various voting systems
5
6## Install
7Grab the package with:
8
9 $ go get github.com/Sam-Izdat/govote
10
11[](https://drone.io/github.com/Sam-Izdat/govote/latest)
12[](http://opensource.org/licenses/MIT)
13[](https://godoc.org/github.com/Sam-Izdat/govote)
14
15## How do I even...
16Behold.
17```go
18package main
19
20import(
21 "fmt"
22 "github.com/Sam-Izdat/govote"
23)
24
25func main() {
26 candidates := []string{"Kang", "Kodos"}
27 poll, _ := govote.Plurality.New(candidates)
28 poll.AddBallot("Kang")
29 poll.AddBallot("Kang")
30 poll.AddBallot("Kodos")
31 fmt.Println(poll.Evaluate())
32 // => [Kang] [{Kang 2} {Kodos 1}] <nil>
33}
34```
35There's a more interesting example [used on Wikipedia](http://en.wikipedia.org/wiki/Condorcet_method#Example:_Voting_on_the_location_of_Tennessee.27s_capital) for comparing voting systems, which shows how different methods can yield very different results.
36
37```go
38// Tennessee voting on capital, suppose all voters want it close, blah, blah, blah...
39candidates := []string{"Memphis", "Nashville", "Knoxville", "Chattanooga"}
40schulze, _ := govote.Schulze.New(candidates)
41plurality, _ := govote.Plurality.New(candidates)
42runoff, _ := govote.InstantRunoff.New(candidates)
43
44ballotMemphis := []string{"Memphis", "Nashville", "Chattanooga", "Knoxville"}
45ballotNashville := []string{"Nashville", "Chattanooga", "Knoxville", "Memphis"}
46ballotChattanooga := []string{"Chattanooga", "Knoxville", "Nashville", "Memphis"}
47ballotKnoxville := []string{"Knoxville", "Chattanooga", "Nashville", "Memphis"}
48
49for i := 0; i < 42; i++ {
50 schulze.AddBallot(ballotMemphis)
51 plurality.AddBallot(ballotMemphis[0])
52 runoff.AddBallot(ballotMemphis)
53}
54for i := 0; i < 26; i++ {
55 schulze.AddBallot(ballotNashville)
56 plurality.AddBallot(ballotNashville[0])
57 runoff.AddBallot(ballotNashville)
58}
59for i := 0; i < 15; i++ {
60 schulze.AddBallot(ballotChattanooga)
61 plurality.AddBallot(ballotChattanooga[0])
62 runoff.AddBallot(ballotChattanooga)
63}
64for i := 0; i < 17; i++ {
65 schulze.AddBallot(ballotKnoxville)
66 plurality.AddBallot(ballotKnoxville[0])
67 runoff.AddBallot(ballotKnoxville)
68}
69
70// Schulze scores are a tally of superior strongest-path comparisons for the candidate
71fmt.Println(schulze.Evaluate())
72// => [Nashville] [{Nashville 3} {Chattanooga 2} {Knoxville 1} {Memphis 0}] <nil>
73
74// Plurality scores are the number of votes for the candidate
75fmt.Println(plurality.Evaluate())
76// => [Memphis] [{Memphis 42} {Nashville 26} {Knoxville 17} {Chattanooga 15}] <nil>
77
78// Instant-runoff returns a slice of rounds, each an ordered slice of candidate scores
79fmt.Println(runoff.Evaluate())
80// => [Knoxville] [map[Memphis:42 Nashville:26 Chattanooga:15 Knoxville:17] \
81// => [ [{Memphis 42} {Nashville 26} {Knoxville 17} {Chattanooga 15}] \
82// => [{Memphis 42} {Knoxville 32} {Nashville 26}] \
83// => [{Knoxville 58} {Memphis 42}] \
84// => [{Knoxville 100}] ]
85// => <nil>
86```
87
88Keep in mind that multiple winners are possible.
89
90Condorcet polls may result in a tie and, in the event of a voting paradox, will return all candidates as winners.
91
92Instant runoff polls, in the event of loser ties at the end of a round, will either eliminate the tied candidates if the sum of their scores is lower than the score of the leader or else elimate a loser at random. If, in the final round, two or more candidates are tied for victory they will all be returned as winners.
93
94Plurality polls will return multiple winner in the event of a tie.
95
96# What still needs doin'
97
98Voting systems implemented:
99
100- [ ] Approval Method
101- [x] Instant Runoff Method
102- [ ] Minmax Method
103- [x] Plurality Method
104- [ ] Range Method
105- [x] Schulze Method (Condorcet)
106- [ ] Chain Method
107- [ ] Majority Choice Method
108
109Also need to:
110
111- [ ] Write unit tests
112
113# License
114
115MIT
116
){kind=link}
){kind=link}
){kind=link}