votesim.votesystems.irv

Module for instant runoff voting.

Created on Sun Oct 13 22:11:08 2019

@author: John

Function Summary

hare_quota(votes, seats)

hare_reallocation(data, winners, quota[, rstate])

Re-allocate ranked data by random.

irv(data[, numwin, seed])

Calculate winners of an election using Instant Runoff Voting.

irv_eliminate(data)

Eliminate a candidate using ranked choice, instant runoff voting.

irv_stv(data[, numwin, reallocation, seed, …])

Calculate winners of an election using Single Transferable Vote

score2rank(data)

top2runoff(data[, numwin])

Emulate top two runoff using ranked data

Module Functions

hare_quota

votesim.votesystems.irv.hare_quota(votes, seats)

hare_reallocation

votesim.votesystems.irv.hare_reallocation(data, winners, quota, rstate=None)

Re-allocate ranked data by random.

Parameters

  • data (array shaped (a, b)) –

    Election voter rankings, from [1 to b]. Data composed of candidate rankings, with

    • Voters as the rows, with a total voters

    • Candidates as the columns, with b total candidates.

    Use 0 to specify unranked (and therefore not to be counted) ballots.

  • winners (array shaped (c,)) – The round winners’s data column indices

  • quota (int) – STV winning quota

  • rstate (numpy random.RandomState or None (default)) – Random number generating object.

Returns

data – Election voter rankings, with winning candidates surplus votes transferred to runner ups.

Return type

array shaped (a, b)

irv

votesim.votesystems.irv.irv(data, numwin=1, seed=None)

Calculate winners of an election using Instant Runoff Voting. Break 1st place ties using 2nd, 3rd, etc ranks. If ties still found at last place rank, return ties.

Parameters

  • data (array shaped (a, b)) –

    Election voter rankings, from [1 to b]. Data composed of candidate rankings, with

    • Voters as the rows, with a total voters

    • Candidates as the columns, with b total candidates.

    Use 0 to specify unranked (and therefore not to be counted) ballots.

  • numwin (int) – Number of winners

Returns

  • winners (array of shape (numwin,)) – Winning candidates index.

  • ties (array of shape (tienum,)) – Tied candidates index for the last round, numbering ‘tienum’.

  • output (dict) –

    round_historyarray of shape (numwin, b)

    Score summations for each candidate, for each round.

    dataarray of shape (a, b)

    Re-ordered ranking data after losers have been eliminated, retaining winner ranksings.

irv_eliminate

votesim.votesystems.irv.irv_eliminate(data)

Eliminate a candidate using ranked choice, instant runoff voting.

Parameters

data (array shaped (a, b)) –

Election voter rankings, from [1 to b]. Data composed of candidate rankings, with

  • Voters as the rows, with a total voters

  • Candidates as the columns, with b total candidates.

Use 0 to specify unranked (and therefore not to be counted) ballots.

Returns

  • data (array shaped (a, b)) – Election voter rankings, but with losing/eliminated candidate’s data zeroed.

  • loser (int) – Column integer index of data of losing candidate.

    • lower will be equal to -1 if no candidates can be eliminated.

    • loser will be 0 or larger, if a candidate can be eliminated.

  • ties (array shaped (c,)) – Index locations of tied losing candidates. Empty array if no ties.

irv_stv

votesim.votesystems.irv.irv_stv(data, numwin=1, reallocation='hare', seed=None, maxiter=500)

Calculate winners of an election using Single Transferable Vote

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.

    Use 0 to specify unranked (and therefore not to be counted) ballots.

    • a : number of voters dimension. Voters assign ranks for each candidate.

    • bnumber of candidates. A score is assigned for each candidate

      from 0 to b-1.

  • numwin (int) – Number of winners

  • reallocation (str) –

    Vote reallocation algorithm for vote transfer.

    • ’hare’ – randomized transfer of surplus votes.

  • rstate (None or numpy.random.RandomState) – Set to None to be truly random. Set RandomState to use deterministic pseudo-random number generator

Returns

  • winners (int array shaped (numwin,)) – Candidate index locations of winners.

  • ties (int array shaped (c,)) – Candidate index location of tied candidates.

  • history (int array shaped (d, b)) – Vote counting record for each round.

score2rank

votesim.votesystems.irv.score2rank(data)

top2runoff

votesim.votesystems.irv.top2runoff(data, numwin=1)

Emulate top two runoff using ranked data