https://github.com/lzear/votes
JS library for ranked voting systems
https://github.com/lzear/votes
borda condorcet election kemeny poll ranked-voting schulze vote voting-methods
Last synced: 3 months ago
JSON representation
JS library for ranked voting systems
- Host: GitHub
- URL: https://github.com/lzear/votes
- Owner: lzear
- License: mit
- Created: 2019-09-02T07:49:39.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-02-27T20:04:48.000Z (over 1 year ago)
- Last Synced: 2025-04-12T03:38:53.953Z (3 months ago)
- Topics: borda, condorcet, election, kemeny, poll, ranked-voting, schulze, vote, voting-methods
- Language: TypeScript
- Homepage: https://rank-votes.vercel.app
- Size: 1.99 MB
- Stars: 24
- Watchers: 2
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# votes
[](https://libraries.io/npm/votes)
[](https://github.com/lzear/votes/blob/master/LICENSE)
[](https://travis-ci.com/lzear/votes)
[](https://www.codacy.com/gh/lzear/votes/dashboard?utm_source=github.com&utm_medium=referral&utm_content=lzear/votes&utm_campaign=Badge_Coverage)
[](https://app.codacy.com/gh/lzear/votes?utm_source=github.com&utm_medium=referral&utm_content=lzear/votes&utm_campaign=Badge_Grade_Settings)
[](https://codeclimate.com/github/lzear/votes/test_coverage)
[](https://codeclimate.com/github/lzear/votes/maintainability)
[](https://www.codefactor.io/repository/github/lzear/votes)
[](https://rank-votes.vercel.app/)
## 🧑💻 Install
```sh
yarn add votes
```
## 🗳️ Use
```typescript
import { Borda } from 'votes'
const borda = new Borda({
candidates: ['Lion', 'Bear', 'Sheep'],
ballots: [
{ ranking: [['Lion'], ['Bear'], ['Sheep']], weight: 4 },
{ ranking: [['Sheep'], ['Bear'], ['Lion']], weight: 3 },
{ ranking: [['Bear', 'Sheep'], ['Lion']], weight: 2 },
],
})
const scores = borda.scores()
// -> { Bear: 10, Lion: 8, Sheep: 9}
const ranking = borda.ranking()
// -> [ [ 'Bear' ], [ 'Sheep' ], [ 'Lion' ] ]
```
## 📚 Documentation
- 🧪 Demo/Playground: [rank-votes.vercel.app](https://rank-votes.vercel.app/)
_(work in progress!)_
- 🧑🏫 Blog post on my website:
[🗳 Ranked voting systems](https://www.elzear.de/posts/2021-01-10-polls)
- 💩 Library documentation:
[lzear.github.io/votes](https://lzear.github.io/votes/)
- 🤓 Good Wikipedia article:
[Comparison of electoral systems](https://en.wikipedia.org/wiki/Comparison_of_electoral_systems)
## 📊 Voting systems
**Absolute majority**: Checks if a candidate is ranked first by more than 50% of
voters.
**Approval voting**: Each voter can select (“approve”) any number of candidates.
The winner is the most-approved candidate.
**Baldwin method**: Iterative Borda count in which, each round, candidates
scoring the lowest score are eliminated.
**Borda count**: For each voter, every candidate is given a number of points
which equals the number of candidates ranked lower in the voter's preference.
**Bottom-two-runoff**: take the two options with the fewest first preference
votes. The pairwise loser out of those two options is eliminated. Repeat.
**Contingent vote** (immediate Two-round system): If no candidate receives 50%
of the votes in the first round, then a second round of voting is held with only
the top two candidates.
**Coombs' method**: Each round, the candidate with the most last rank is
eliminated. The election repeats until there is a winner.
**Copeland's method**: Rank candidates by number of duels won against other
candidates.
**Instant-runoff**: Considering only the top choice of each voter, the candidate
with the fewest votes is eliminated. The election repeats until there is a
winner. This voting system is very similar to single transferable vote method.
**Kemeny–Young method**: A relatively complex computation generating a
preference order aiming to minimize dissatisfaction of the voters. Also known as
Kemeny rule, VoteFair popularity ranking, the maximum likelihood method, and the
median relation.
**Maximal lotteries & Randomized Condorcet**: Returns probabilities for each
candidate that should be used for a lottery between the Candidates. If a
candidate is the Condorcet winner, its probability will be 1. Despite being
non-deterministic, those methods are the fairest. Currently, these methods give
incorrect results in many cases because of mistakes in the codes!
**Majority Judgement**: (**⚠️ cardinal voting system**). Voters can rank
candidates in an array corresponding to 6 categories ("Excellent", "Very good",
"Good", "Passable", "Mediocre" and "Bad"). Candidates with the best median are
ranked first.
**Minimax Condorcet method**: Ranking the candidates by smallest pairwise
defeat.
**Minimax-TD**: Compute the [Smith set](https://en.wikipedia.org/wiki/Smith_set)
. Then compute the Minimax ranking on that set. TD stands for
Tideman-Darlington.
**Nanson method**: Iterative Borda count in which, each round, candidates
scoring the average score or less are eliminated.
**Plurality**: Simple voting method where only the preferred candidate of each
voter gets 1 point. AKA first-past-the-post.
**Random candidate**: Selects a random ranking, regardless of ballots.
**Random dictator**: Selects a random ballot that decides the ranking.
**Ranked pairs**: Using the duel results as edges, build an acyclic graph
starting by the strongest score differences. The roots of the graph are the
winners.
**Schulze method**: From the votes, compute the results of all possible duels.
Then remove the most indecisive (closest to 50/50) duels until there is an
undefeated candidate, the winner. This popular voting system is used by several
organizations (Ubuntu, Debian, Wikimedia...).
**Smith's method**: All members of the top cycle (a.k.a. Smith set): _"the
smallest non-empty set of candidates in a particular election such that each
member defeats every candidate outside the set in a pairwise election"_
## 🤝 Contributing
Contributions, issues and feature requests are welcome!
Feel free to check
[issues page](https://github.com/lzear/votes/issues).
The repository is split in 2 projects:
- **/votes** contains the source of the NPM package
[votes](https://www.npmjs.com/package/votes)
- **/demo** contains the source of the demo website