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, representing lower preferences that were not expressed.
By default the preferences are not allowed to contain duplicates per vote. However, if the argument equal.ranking is set to TRUE, votes are allowed to have the same ranking for multiple candidates. The desired format is such that for each preference \(i\) that does not have any duplicate, there must be exactly \(i-1\) preferences \(j\) with \(0 < j < i\). For example, valid ordered preferences are \(1,1,3,4,\dots\), or \(1,2,3,3,3,6,\dots\), but NOT \(1,1,2,3,\dots\), or NOT \(1,2,3,3,3,5,6,\dots\). If the data contain such invalid votes, they are automatically corrected and a warning is issued by calling the correct.ranking function.
If equal ranking is not alowed (equal.ranking = FALSE), the argument invalid.partial can be used to make ballots containing duplicates or gaps partially valid. If it is TRUE, a ballot is considered valid up to a preference that is in normal case not allowed. For example, ballots \(1,2,3,4,4,6\) or \(1,2,3,5,6,7\) would be both converted into \(1,2,3,0,0,0\), because the ballots contain valid ranking only up to the third preference.
The correct.ranking function does the above corrections for all records, regardless if they contain duplicates or not. Its argument partial determines if ballots are partially set to 0 (TRUE), or if it is complete re-ranking, as allowed when equal.ranking = TRUE. It can either be used by calling it explicitly, otherwise it is called by stv if equal.ranking = TRUE or invalid.partial = TRUE. The function is also called from within the condorcet function. The remove.candidate function removes the given candidate(s) and adjusts the ranked votes accordingly by calling the correct.ranking function.
The function allows the user to impute missing values. It can be used for example, if a voter has a conflict of interest with one or more candidates and not voting for them would unfairly decrease the chances of those candidates being elected. (Note that missing values are not to be confused with lower preferences that are not expressed.) Preferences to be imputed should be set to \(-1\) and the argument impute.missing to TRUE. Each such preference is imputed using the median rank value over the remaining votes. When computing the median rank across the votes, any value of zero is replaced by the median of the ranks not used in the corresponding vote. For example, for a ballot \(1,2,3,0,0,0\), the three zeros are replaced by the median of \(4, 5, 6\), i.e. by \(5\), which is then used to compute the missing median rank. If the final imputed rank is larger than the number of non-zero preferences (e.g. if in a ballot \(1,2,0,-1,0\) the imputed value for the fourth candidate would be larger than 3), the preference is set to zero and a warning is issued.
The described functionality is implemented in the impute.ranking function, which is called automatically from stv if impute.missing = TRUE. It can be used explicitly as well.
By default, ties in the STV algorithm are resolved using the forwards tie-breaking method, see Newland and Briton (Section 5.2.5). Argument ties can be set to “b” in order to use the backwards tie-breaking method, see O'Neill (2004). In addition, both methods are complemented by the following “ordered” method: Prior to the STV election candidates are ordered by the number of 1st preferences. Equal ranks are resolved by moving to the number of 2nd preferences, then 3rd and so on. Remaining ties are broken by random draws. Such complete ordering is used to break any tie that cannot be resolved by the forwards or backwards method. If there is at least one tie during the processing, the output contains a row indicating in which count a tie-break happened (see the ties element in the Value section for an explanation of the symbols).
The ordered tiebreaking described above can be analysed from outside of the stv function by using the ordered.tiebreak function for viewing the a-priori ordering (the highest number is the best and lowest is the worst). Such ranking is produced by comparing candidates along the columns of the matrix returned by ordered.preferences.
The plot function shows the evolution of the total score for each candidate as well as the quota. The image function visualizes the joint distribution of two preferences (if all.pref=FALSE) as well as the marginal distribution of all preferences (if all.pref=TRUE). The joint distribution can be shown either as proportions (if proportion=TRUE) or raw vote counts (if proportion=FALSE).
Method complete.ranking produces a complete ranking of the candidates, conditioned on the number of seats selected in the nseats argument. It is called from the summary function if the complete.ranking argument is set to TRUE.