votesim.votesystems.condcalcs

Functions for calculating Condorcet-related voting methods

Contents

• votesim.votesystems.condcalcs

  • Class Summary

  • Function Summary

  • Module Classes

  • Module Functions

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