stv: Implement STV counting system.

In chandrasaksham/STV: Single Transferable Vote Counting

Description

stv returns a list containing a data.frame with rows containing detailed results from each round of STV counting, and a vector containing the elected candidates.

Usage

stv(x, seats = 1, file = "", surplusMethod = "Cambridge",
  quotaMethod = "Droop")

Arguments

x	a data.frame with rows as ballots and columns as candidates. x must pass all checks from validateBallots().
seats	a number indicating candidates to elect. (default = 1)
file	a character string naming a file. "" indicates output to the console only (default). Saves a CSV file. Its name should end with ".csv".
surplusMethod	a character string indicating which method to use for surplus allocation. Currently supports "Cambridge" (default) and "Fractional".
quotaMethod	a character string indicating which method to use for calculation of quota. Currently supports "Droop" (default) and "Hare".

Details

stv() first validates x by running the validateBallots() function. Once validation is complete, it implements the selected single transferable vote counting method. Each round of counting starts with idetification of active ballots. Then a quota is calculated (currently only supports Droop method floor(votes/(seats + 1)) + 1 and Hare method floor(votes/seats)). A tally of each candidate's vote share is obtained using top choices of active ballots, where a ballot stays active until it runs out of marked choices or gets removed during surplus reallocation. If a candidate reaches the quota, she/he is elected and associated surplus ballots are reallocated (currently only supports Cambridge and Fractional methods). If multiple candidates reach the quota, all of them are elected and their surpluses are all reallocated. If no candidate reaches the quota, then the candidate with the minimum number of votes is eliminated. If multiple candidates tie for minimum number of votes, one of them is selected at random and eliminated. The process is repeated until all of the seats are filled or the number of candidates still in race equals the number of unfilled seats. In the later case, all of the active candidates are elected.

Value

a list consisting of a data.frame with rows containing detailed results from each round of STV counting, and a vector of election winners. For any given round of counting, a row of the detailed information contains: number of active ballots, seats to fill, quota, maximum and minimum votes obtained by any candidate, who was eliminated (if any), if there was a tie for elimination (if yes, how many tied), who was elected (if any), surplus if elected, and each candidate's votes tally for that round.

Examples

data(ballots)
cballots <- cleanBallots(ballots)
result <- stv(cballots, seats = 4)
names(result)
result$elected

chandrasaksham/STV documentation built on May 20, 2019, 2:24 p.m.