votesim.votesystems.condcalcs

Functions for calculating Condorcet-related voting methods

Class Summary

VoteMatrix([ranks, matrix])

Pairwise vote information

VotePairs(pairs)

Condorcet calculations for winner-loser pairs in head-to-head matchups.

VotePairsError

Special votepairs exception for condorcet methods

Function Summary

condorcet_check_one([ranks, scores])

Calculate condorcet winner from ranked data if winner exists.

condorcet_winners_check([ranks, matrix, …])

General purpose condorcet winner checker for multiple winners.

has_cycle(pairs)

Check if there is a condorcet cycle.

pairwise_rank_matrix(ranks)

Calculate total votes for a candidate against another candidate given ranked voter data.

pairwise_scored_matrix(scores)

Get head-to-head votes for a candidate against another candidate given scored voter data

smith_set([ranks, vm, wl])

Compute smith set.

Module Classes

VoteMatrix

class votesim.votesystems.condcalcs.VoteMatrix(ranks=None, matrix=None)

Pairwise vote information

Parameters
  • ranks (array shape (a, b)) – Ranking data

  • matrix (array shape (b, b)) – Head-to-head vote matrix

Method/Attribute Summary

VoteMatrix.matrix

VoteMatrix.cnum

Number of candidates

VoteMatrix.margin_matrix

VoteMatrix.pairs

array shaped (a, 3) Win-Loss candidate pairs

VoteMatrix.matrix()
VoteMatrix.cnum()

Number of candidates

VoteMatrix.margin_matrix()
VoteMatrix.pairs()

array shaped (a, 3) Win-Loss candidate pairs

  • column 0 = winning candidate

  • column 1 = losing candidate

  • column 2 = margin of victory

  • column 3 = votes for winner

VotePairs

class votesim.votesystems.condcalcs.VotePairs(pairs)

Condorcet calculations for winner-loser pairs in head-to-head matchups.

Method/Attribute Summary

VotePairs.pairs

winner loser pairs

VotePairs.winners

winners

VotePairs.losers

losers

VotePairs.condorcet_losers

Find Condorcet losers in pairs that lose all all other pairs

VotePairs.condorcet_winners

Find Condorcet winners in pairs

VotePairs.copy()

Return copy of VotePairs

VotePairs.remove_candidate(ilist)

Remove candidates from the pairs

VotePairs.prune_losers()

Prune condorcet losers out of the pairs list

VotePairs.prune_winners()

Prune condorcet winners out of the pairs list

VotePairs.has_cycle

Determine whether pairs have a Condorcet cycle

VotePairs.pairs()

array shape (a, 2) : winner loser pairs

VotePairs.winners()

array shape (a,) : winners

VotePairs.losers()

array shape (a,) : losers

VotePairs.condorcet_losers()

Find Condorcet losers in pairs that lose all all other pairs

VotePairs.condorcet_winners()

Find Condorcet winners in pairs

VotePairs.copy()

Return copy of VotePairs

VotePairs.remove_candidate(ilist)

Remove candidates from the pairs

VotePairs.prune_losers()

Prune condorcet losers out of the pairs list

Returns

out – New pruned pairs

Return type

VotePairs

Raises

VotePairsError – Raised if no Condorcet losers can be pruned.

VotePairs.prune_winners()

Prune condorcet winners out of the pairs list

VotePairs.has_cycle()

Determine whether pairs have a Condorcet cycle

VotePairsError

class votesim.votesystems.condcalcs.VotePairsError

Special votepairs exception for condorcet methods

Method/Attribute Summary

Module Functions

condorcet_check_one

votesim.votesystems.condcalcs.condorcet_check_one(ranks=None, scores=None)

Calculate condorcet winner from ranked data if winner exists. Partial election method; function does not handle outcomes when condorcet winner is not found.

Parameters

ranks (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.

Returns

out

  • Index location of condorcet winner.

  • Return -1 if no condorcet winner found.

Return type

int

condorcet_winners_check

votesim.votesystems.condcalcs.condorcet_winners_check(ranks=None, matrix=None, pairs=None, numwin=1, full_ranking=False)

General purpose condorcet winner checker for multiple winners. This check does not resolve cycles.

Parameters
  • ranks (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.

  • matrix (array shaped (b, b)) – Win minus Loss margin matrix

  • pairs (array shaped (c, 3)) –

    Win-Loss candidate pairs

    • column 0 = winning candidate

    • column 1 = losing candidate

    • column 2 = margin of victory

    • column 3 = votes for winner

  • full_ranking (bool (default False)) – If True evaluate entire ranking of candidates for score output

Returns

  • winners (array of shape(d,)) –

    Index locations of each winner.
    • b = numwin if no ties detected

    • b > 1 if ties are detected.

    • winners is empty if Condorcet cycle detected

  • ties (array of shape (e,)) – Index locations of ties

  • scores (array of shape (b,)) – Rankings of all candidates

has_cycle

votesim.votesystems.condcalcs.has_cycle(pairs)

Check if there is a condorcet cycle.

Parameters

pairs (array shaped (a, 3)) –

Win-Loss candidate pairs

  • column 0 = winning candidate

  • column 1 = losing candidate

  • column 2 = margin of victory

  • column 3 = votes for winner

Returns

out – True if cycle detected. False otherwise

Return type

bool

pairwise_rank_matrix

votesim.votesystems.condcalcs.pairwise_rank_matrix(ranks)

Calculate total votes for a candidate against another candidate given ranked voter data.

Parameters

ranks (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.

Returns

out – Vote matrix V[i,j]

  • Total votes for candidate i against candidate j

Return type

array shaped (b, b,)

pairwise_scored_matrix

votesim.votesystems.condcalcs.pairwise_scored_matrix(scores)

Get head-to-head votes for a candidate against another candidate given scored voter data

Parameters

scores (array shaped (a, b)) –

Election voter scores, 0 to max. Data of candidate ratings for each voter, with

  • a Voters represented as each rows

  • b Candidates represented as each column.

Returns

out – Vote matrix V[i,j]

  • Total wins for candidate i against candidate j

Return type

array shaped (b, b,)

smith_set

votesim.votesystems.condcalcs.smith_set(ranks=None, vm=None, wl=None)

Compute smith set. Based on Stack-Overflow code.

From https://stackoverflow.com/questions/55518900/seeking-pseudo-code-for-calculating-the-smith-and-schwartz-set Retrieved Dec 28, 2019

Parameters
  • ranks (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.

  • vm (array shaped (b, b)) – Votes matrix in favor of ith row candidate against jth column candidate

  • wl (array shaped (b, b)) – Win minus Loss matrix

Returns

out – Candidate indices of smith set

Return type

set