votesim.votesystems.tools¶
Some common functions shared by many voting systems
Function Summary¶

Make sure rankings are sequential integers from [1 to b], with 0 meaning eliminated or unranked. 

Threshold of votes required to get elected for STV. 

Retrieve firstchoice plurality votes, given either ratings or rankings data 

If ties are found, choose random tied candidate to break tie 



Convert scores or ratings to rankings starting from 1. 

Check for winner and handle ties, considering results, where the greatest result results in a win. 
Module Functions¶
RCV_reorder¶

votesim.votesystems.tools.
RCV_reorder
(data)¶ Make sure rankings are sequential integers from [1 to b], with 0 meaning eliminated or unranked.
 Parameters
data (array shaped (a, b)) –
Election voter rankings, from [1 to b]. Data composed of candidate rankings, with
Voters as the rows
Candidates as the columns.
 Returns
out – Conversion of scores to integer ranked sequenced data from [1 to b].
 Return type
array shaped (a,b)
droop_quota¶

votesim.votesystems.tools.
droop_quota
(votes, seats)¶ Threshold of votes required to get elected for STV.
 Parameters
votes (int) – Total number of votes cast in election
seats (int) – Total number of seats needed to be filled.
 Returns
out – Droop quota; number of votes required to get elected.
 Return type
int
getplurality¶

votesim.votesystems.tools.
getplurality
(ratings=None, ranks=None)¶ Retrieve firstchoice plurality votes, given either ratings or rankings data
 Parameters
ratings (array shape (a, b)) – Ratings data. Mutually exlusive with ranks
ranks (array shape (a, b)) – Rankings data. Mutually exclusive with ratings
 Returns
out – Rank/ratings data converted into singlevote plurality ballots.
 Return type
array shape (a, b)
handle_ties¶

votesim.votesystems.tools.
handle_ties
(winners, ties, numwinners, rstate=None)¶ If ties are found, choose random tied candidate to break tie
 Parameters
winners (array shaped (a,)) – Winning candidate indices
ties (array shaped (b,)) – Candidates that almost won but have received a tie with other candidates.
numwinners (int) – Total number of required winners for this election
 Returns
winner – Winners of election. Tiebroken by random choice.
 Return type
array shaped (numwinners,)
score2rank¶

votesim.votesystems.tools.
score2rank
(data, cutoff=None)¶ Convert scores or ratings to rankings starting from 1.
 Parameters
data (array shaped (a, b)) –
Election voter rating, 0 to max. Data composed of candidate ratings, with
anumber of Voters as the rows
bnumber of Candidates as the columns.
Use 0 to specify unranked (and therefore not to be counted) ballots.
a : number of voters dimension.
b : number of candidates. A score is assigned for each candidate from 0 to b1.
cutoff (None or float) – If float, specify a cutoff rating where ratings below this value are unranked as ranking=0.
 Returns
rank – Election rankings of each voter for each candidate
a : voters dimension
b : candidates dimension
 Return type
array shaped (a, b)
winner_check¶

votesim.votesystems.tools.
winner_check
(results, numwin=1)¶ Check for winner and handle ties, considering results, where the greatest result results in a win.
This function is used as a fundamental building block for other voting methods suchas plurality, score, STAR, etc.
 Parameters
results (array of shape (a,)) –
Result quantities for a # of candidates. Candidate index with the greatest result wins.
Each element is the candidate “score” as int or float.
Set an element to np.NAN to ignore a particular candidate.
numwin (int) – Number of winners to return
 Returns
winners (array of shape(b,)) –
 Index locations of each winner.
b = numwin if no ties detected
b > 1 if ties are detected.
ties (array of shape (c,)) – Index locations of ties
Example
We have run a plurality election for 4 candidates. The final tallies for each candidate are
>>> counts = [2, 10, 4, 5]
To determine the index location of the winner, use
>>> w, t = winner_check(counts, numwin=1)