R: Create a vote Object that can be used in counting methods

create_vote {votesys}

R Documentation

Create a vote Object that can be used in counting methods

Description

Some counting methods in this package only accept vote object created by this function. So the first step should always be using this function. The function will return the modified ballots and some other helpful information. See Details and Values.

Usage

create_vote(x, xtype = 2, candidate = NULL, isna = NULL)

Arguments

`x`	a data.frame, matrix or list of raw ballots. See Details.
`xtype`	should be 1, 2 (default) or 3, designating the type of `x`. See Details.
`candidate`	if `xtype` is 1, this argument is ignored. If `xtype` is 2 or 3, candidate names must be given as a character or numeric vector. If a name is not given, but is still on a ballot, then the name is ignored !
`isna`	entries which should be taken as NAs. `NA` in `x` will always be taken as missing value, however, you can add more (e.g., you may use 99, 999 as missing values). If x contains characters, this argument should also be provided with a character vector, and if numeric, then numeric vector. Do not add `NA` to `isna`, because the default (NULL) means `NA` is already included.

Details

The function accepts the following input:

(1) when xtype is 1, x must be a matrix. Column names are candidate names (if column names are NULL, they will be created: x1, x2, x3...). Candidate number is the number of columns of the matrix. Entry ij is the numeric score assigned by the ith voter to the jth candidate.
(2) when xtype is 2, x can be a matrix or data.frame. Candidate number is the length of candidate. Entries are names (character or numeric) of candidates. The i1, i2, i3... entries are the 1st, 2nd, 3rd... preferences of voter i.
(3) when xtype is 3, x should be a list. Each element of the list is a ballot, a vector contains the names (character or numeric) of candidates. The 1st preference is in the 1st position of the vector, the 2nd preference is in the 2nd position... The number of candidates is the length of candidate; as a result, a ballot with number of names larger than candidate number is labelled as wrong.

The function also returns Condorcet matrix. Suppose candidates are i, j, k. The voter likes i best, so he assigns 1 to i. The 2nd choice is j, so he assigns 2 to j, leaving k as NA. Now computing the Condorcet matrix: since i's score is smaller than j' score, we add 1 to the ij cell of the matrix, and add 0 to the ji cell. Candidate k's NA is automatically set to the highest (that is, the worst) score: 3 (since there are 3 candidates); i < k, so we add 1 to the ik cell and add 0 to ki cell. Besides, there is also a score difference matrix: we add 2 - 1 = 1 to the ij cell of score difference matrix, and add 3 - 1 = 2 to the ik cell. If tie appears, both sides acquire 0.

Note the ways we calculate the Condorcet matrix. (1) It allow ties, that is, duplicated score values. (2) NA is deems as the worst, which means: if a voter does not mention a candidate, the candidate will be given the highest (worst) score. (3) Ballots mention only one name are assumed to express preference, since unmentioned candidates are assumed to be equally hated. (4) The Condorcet matrix returned by create_vote uses ballots that may have duplicated values and have only one valid entry. However, Condorcet family methods in this package provide possibility to recalculate the matrix. And, the simplest way to get rid of duplicated values and NAs is to delete some ballots.

Value

an object of class vote is returned, which is essentially a list. It has the following elements.

(1) call the call.
(2) ballot the returned ballot. It is always a score matrix. The column names are candidate names; entries are numeric scores assigned by voters. Missing values are all set to NA.
(3) nas those which are taken as NA in data cleaning.
(4) candidate candidate names.
(5) candidate_num number of candidates.
(6) ballot_num number of ballots.
(7) ballot_at_least_one number of ballots that mention at least one candidate.
(8) cdc the Condorcet matrix calculated with ballots that have no NA entries.
(9) cdc_with_na the Condorcet matrix calculated with ballots that have at least one valid entry.
(10) dif the score difference matrix calculated with ballots that have no NA entries.
(11) dif_with_na the score difference matrix calculated with ballots that have at least one valid entry.
(12) row_with_na rows of ballot with NAs.
(13) row_non_na for rows with NAs, the number of non-NA entries of them.
(14) row_with_dup rows of ballot with duplicated score values.
(15) approval_able if length of row_non_dup is 0, then it is TRUE, else, FALSE. It indicates whether approval method can be used. When xtype is 2 or 3, it is always TRUE.

Examples

# xtype is 2
raw <- c(
    rep(c('m', 'n', 'c', 'k'), 42), 
    rep(c('n', 'c', 'k', 'm'), 26), 
    rep(c('c', 'k', 'n', 'm'), 15), 
    rep(c('k', 'c', 'n', 'm'), 17)
) 
raw <- matrix(raw, ncol = 4, byrow = TRUE)
vote <- create_vote(raw, xtype = 2, candidate = c('m', 'n', 'k', 'c'))

# xtype is 3
raw <- list(
    c('a', 'e', 'c', 'd', 'b'), 
    c('b', 'a', 'e'), 
    c('c', 'd', 'b'), 
    c('d', 'a', 'b'), 
    c('a', 'a', 'b', 'b', 'b'), 
    c(NA, NA, NA, NA), 
    v7 = NULL, 
    v8 = c('a', NA, NA, NA, NA, NA, NA), 
    v9 = rep(" ", 3)
)
y <- check_dup_wrong(raw, xtype = 3, candidate = letters[1: 4])
raw2 <- raw[-y$row_with_wrong]
vote <- create_vote(raw2, xtype = 3, candidate = letters[1: 4])

# xtype is 1
raw <- rbind(
    c(1, 2, 5, 3, 3), 	
    c(2, 1, 1, 3, 5), 	
    c(1, 2, 5, 3, 4), 
    c(1, 2, 5, 3, 4), 
    c(NA, NA, NA, NA, NA),		
    c(NA, 3, 5, 1, 2), 
    c(NA, 999, NA, 1, 5)
)
vote <- create_vote(raw, xtype = 1, isna = 999)

[Package votesys version 0.1.1 Index]