vote (version 1.2-1)

stv: Single Transferable Vote

Description

Count votes using the single transferable voting method, also known as ranked choice voting or instant runoff.

Usage

stv(votes, mcan = NULL, eps = 0.001, fsep = '\t', verbose = FALSE, seed = 1234, …)
# S3 method for vote.stv
summary(object, …)
# S3 method for vote.stv
view(object, …)

Arguments

votes

Matrix or data frame containing the votes. Rows correspond to the votes, columns correspond to the candidates. If it is a character string it is interpreted as a tab-separated file name from which the votes are to be read. See below for more details.

mcan

Number of candidates to be elected. By default it is half the number of candidates standing.

eps

Value added to the quota. I.e. the STV quota is computed as number_of_first_preferences/(number_of_seats + 1) + eps.

fsep

If votes is a file name, this argument gives the column separator in the file.

verbose

Logical. If TRUE the progress of the count will be printed.

seed

Integer. Seed of the random number generator. Only used if there are ties that cannot be resolved by the tie-breaking method. If set to NULL, the RNG is not initialized.

…

Not used.

object

Object of class vote.stv.

Value

Function stv returns an object of class vote.stv which is a list with the following objects:

elected

Vector of names of the elected candidates in the order in which they were elected.

preferences

Matrix of preferences. Columns correspond to the candidates and rows to the counts (i.e. voting rounds).

quotas

Vector of quotas, one for each count.

elect.elim

Matrix of the same shape as preferences. Value 1 means that the corresponding candidate was elected in that round; value -1 means an elimination.

data

Input data with invalid votes removed.

invalid.votes

Matrix of invalid votes that were removed from the original dataset.

Details

For a description of the single transferable vote system see https://imstat.org/elections/single-transferable-voting-system.

The input data votes is structured as follows: Row \(i\) contains the preferences of voter \(i\) numbered \(1, 2, \dots, r, 0,0,0,0\), in some order. The columns correspond to the candidates. The dimnames of the columns are the names of the candidates; if these are not supplied then the candidates are lettered A, B, C, …. If the dataset contains missing values (NA), they are replaced by zeros.

Ties are resolved using the forwards tie-breaking method, see Newland and Briton (Section 5.2.5).

References

R.A. Newland and F.S. Britton (1997). How to conduct an election by the Single Transferable Vote. ERS 3rd Edition. http://www.rosenstiel.co.uk/stvrules/index.html

https://imstat.org/elections/single-transferable-voting-system

https://en.wikipedia.org/wiki/Single_transferable_vote

Examples

# NOT RUN {
# Reproducing example from Wikipedia
# https://en.wikipedia.org/wiki/Single_transferable_vote#Example
# Uses eps=1
data(food_election)
stv.food <- stv(food_election, mcan = 3, eps = 1)
summary(stv.food)
# }
# NOT RUN {
view(stv.food)
# }
# NOT RUN {
# Example of the IMS Council voting
data(ims_election)
stv.ims <- stv(ims_election, mcan = 5)
# }
# NOT RUN {
view(stv.ims)

# write election results into a csv file
s <- summary(stv.ims)
write.csv(s, "myfile.csv")
# }
# NOT RUN {
# Example of a small committee dataset
# with four candidates (C) and four
# voting committee members (uses tie-breaking)
votes <- data.frame(C1=c(3,2,1,3), C2=c(2,1,2,4),
                    C3=c(4,3,3,1), C4=c(1,4,4,2))
stv(votes, mcan = 2, verbose = TRUE)                    
# }