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 first-choice 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 first-choice 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 single-vote 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. Tie-broken 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
a-number of Voters as the rows
b-number 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 b-1.
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)