single-transferable-vote
v0.0.14
Published
<!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
Downloads
81
Readme
Classes
Class: Ballot
A single voter's ballot, in order of preference
Constructors
constructor
• new Ballot(votes, weight?): Ballot
Parameters
| Name | Type | Default value |
| :------ | :------ | :------ |
| votes | string[] | undefined |
| weight | number | 1 |
Returns
Defined in
Properties
votes
• votes: string[]
Defined in
weight
• weight: number
Defined in
Methods
toJSON
▸ toJSON(): Object
Returns
Object
| Name | Type |
| :------ | :------ |
| votes | string[] |
| weight | number |
Defined in
Class: Election
Run instant runoff tabulations for each round, adding calculated rounds to rounds.
Use single transferable vote (STV) to elect winnersCount candidates.
- Count the first choices for each candidate
- While there are still seats available, run the following:
- sort candidates by votes descending
- if a candidate has more votes than the threshold, they are elected, then analyze their second-choice votes
- update the threshold based on how many votes are left after votes from the over-threshold candidate are non-transferable (no second-choice candidate selected)
- redistribute the votes of each candidate who has more votes than the threshold
Constructors
constructor
• new Election(inputBallots, «destructured»?): Election
Parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| inputBallots | Ballot[] | input votes |
| «destructured» | Object | - |
| › availableSeats? | number | - |
| › dynamicThreshold? | boolean | - |
| › transferType? | TransferType | - |
Returns
Defined in
Properties
NO_PREFERENCE
• NO_PREFERENCE: string = "No Preference"
Defined in
availableSeats
• availableSeats: number = 1
Defined in
ballots
• ballots: Ballot[] = []
Defined in
dynamicThreshold
• dynamicThreshold: boolean = true
Defined in
elected
• elected: Set<string>
Defined in
eliminated
• eliminated: Set<string>
Defined in
fractionalThreshold
• fractionalThreshold: boolean = true
Defined in
inputBallots
• inputBallots: Ballot[]
input votes
Defined in
rounds
• rounds: Round[] = []
Defined in
transferType
• transferType: TransferType = "fractional"
Defined in
Accessors
allCandidates
• get allCandidates(): string[]
Deduped list of all candidates
Returns
string[]
Defined in
errorMessage
• get errorMessage(): undefined | "No ballots were provided"
Returns
undefined | "No ballots were provided"
Defined in
events
• get events(): string[][]
Returns
string[][]
Defined in
isValid
• get isValid(): boolean
If the runner should run
Returns
boolean
Defined in
links
• get links(): { source: string ; target: string ; value: number }[][]
Returns
{ source: string ; target: string ; value: number }[][]
Defined in
Methods
run
▸ run(): void
Process given ballots
Returns
void
Defined in
Class: Round
A single round's result, including active candidates, total votes, and the winner
Constructors
constructor
• new Round(parent?): Round
Parameters
| Name | Type |
| :------ | :------ |
| parent? | Election |
Returns
Defined in
Properties
ballots
• ballots: Ballot[] = []
Input ballots
Defined in
electedAtStart
• electedAtStart: Set<string>
Elected candidates from the previous round
Defined in
eliminatedAtStart
• eliminatedAtStart: Set<string>
Eliminated candidates from the previous round
Defined in
events
• events: string[] = []
Log of events in this round
Defined in
index
• index: number = 0
Index of round in parent Election. Needed for links
Defined in
links
• links: { source: string ; target: string ; value: number }[] = []
Links between candidates in this round. Useful for sankey visualization.
Defined in
parent
• parent: Election
Defined in
Accessors
candidates
• get candidates(): string[]
Deduped list of candidates in the ballots
Returns
string[]
Defined in
currentlyAvailableSeats
• get currentlyAvailableSeats(): number
Returns
number
Defined in
hopefulCandidates
• get hopefulCandidates(): string[]
Returns
string[]
Defined in
losers
• get losers(): string[]
Returns
string[]
Defined in
newWinners
• get newWinners(): string[]
Candidates that surpassed the threshold in this round
Returns
string[]
Defined in
sortedCandidates
• get sortedCandidates(): string[]
Candidates sorted from most votes to fewest
Returns
string[]
Defined in
threshold
• get threshold(): number
Threshold needed to be elected in this round
Returns
number
Defined in
totalActiveVotes
• get totalActiveVotes(): number
Same as totalVotes, but ignores "No preference"
Returns
number
Defined in
totalVotes
• get totalVotes(): number
Number of votes in this round
Returns
number
Defined in
votes
• get votes(): Object
Calculate votes by adding the current this.ballots[i].votes[0] * this.ballots[i].weight
Returns
Object
Defined in
Methods
eliminateCandidate
▸ eliminateCandidate(candidate): Ballot[]
Removes a candidate from subsequent rounds and redistributes all of their votes
Parameters
| Name | Type |
| :------ | :------ |
| candidate | string |
Returns
Ballot[]
Defined in
redistributeVotes
▸ redistributeVotes(candidate, percentage, keep?): Ballot[]
for ballots that have the candidate in 1st, splice out the first item and redistribute the votes with weighting
Parameters
| Name | Type | Default value |
| :------ | :------ | :------ |
| candidate | string | undefined |
| percentage | number | undefined |
| keep | boolean | false |
Returns
Ballot[]
Todo
prevent votes from being redistributed to the an already-winning candidate
Defined in
toJSON
▸ toJSON(): Object
Returns
Object
| Name | Type |
| :------ | :------ |
| total | number |
| votes | { [candidate: string]: number; } |
Defined in
transferSurplus
▸ transferSurplus(candidate, percentage): Ballot[]
Transfers votes from a winning candidate to their voters' next preference
Parameters
| Name | Type |
| :------ | :------ |
| candidate | string |
| percentage | number |
Returns
Ballot[]
Defined in
single-transferable-vote - v0.0.8
This module provides classes and functions for tabulating STV (Single Transferable Vote) elections.
Installation
npm install single-transferable-voteUsage
import { Election, Ballot } from 'single-transferable-vote'Classes
Type Aliases
Candidate
Ƭ Candidate: string
The name of a candidate
Defined in
ThresholdType
Ƭ ThresholdType: "Droop" | "Hare" | "ERS97"
Defined in
TransferType
Ƭ TransferType: "random" | "fractional"
Fractional is deterministic, while random or other sampling methods could unfairly weight certain votes.
Defined in
Functions
calculateThreshold
▸ calculateThreshold(ballotCount, seats, type?, fractional?): number
Returns the threshold for a given number of votes and seats. ERS97 is identical to Droop during this calculation—it only affects the number of votes transferred in dynamic threshold systems.
Parameters
| Name | Type | Default value |
| :------ | :------ | :------ |
| ballotCount | number | undefined |
| seats | number | undefined |
| type | ThresholdType | "ERS97" |
| fractional | boolean | true |
Returns
number
Defined in
getFlatUniqueArray
▸ getFlatUniqueArray<T>(array): T[]
Flattens an array of simple objects (eg. strings) and makes them unique
Type parameters
| Name |
| :------ |
| T |
Parameters
| Name | Type |
| :------ | :------ |
| array | T[][] |
Returns
T[]
Defined in
getVoterPreferencesForCandidate
▸ getVoterPreferencesForCandidate(ballots, candidate, roundIndex?): Object
Gets next preferences for a candidate from a list of votes.
Parameters
| Name | Type | Default value | Description |
| :------ | :------ | :------ | :------ |
| ballots | Ballot[] | undefined | All votes |
| candidate | string | undefined | Candidate to analyze next preference for |
| roundIndex | number | 0 | Current round to filter results by |
Returns
Object
Example
input:
getVoterPreferencesForCandidate(
[
["A", "B", "C"],
["A", "B", "C"],
["A", "C"]
],
"A")output:
{
B: 2/3,
C: 1/3
}