interregnum.methods.preferential.condorcet package

Condorcet methods.

class interregnum.methods.preferential.condorcet.CondorcetAllocator(ranking_f, allow_ties=True, fill_truncated=False)

Bases: MultiWinnerAdapter[AnyName, MultiWinnerResultData, list[Preference[AnyName]], Iterable[Preference[AnyName] | PrefDict[AnyName] | tuple[int | Fraction, Sequence[AnyName | Tuple[AnyName, …] | list[AnyName]] | tuple[AnyName | Tuple[AnyName, …] | list[AnyName], …]]]]

An allocator for Condorcet methods.

Create a Condorcet method.

Parameters:

  • ranking_f (Callable[..., Ranking[AnyName]]) – ranking list

  • allow_ties (bool) – allow more than one candidate at the same preference position

  • fill_truncated (bool) – fill a truncated ballot with a tie of the remaining candidates

calc(preferences, seats=1, candidate_list=None, random_seed=None, filter_f=None)

Allocate seats to candidates.

Parameters:

  • preferences (Iterable[Preference[AnyName] | PrefDict[AnyName] | tuple[int | Fraction, Sequence[AnyName | Tuple[AnyName, ...] | list[AnyName]] | tuple[AnyName | Tuple[AnyName, ...] | list[AnyName], ...]]]) – list of grouped preference ballots

  • seats (int) – seats to allocate

  • candidate_list (Iterable[AnyName] | None) – full list of allowed candidates

  • random_seed (int | Random | None) – used to resolve candidates ties

  • filter_f (CandidateFilter[AnyName, Event] | None) – filter candidates that can win a seats

Return type:

NonDeterministicResult[AnyName, MultiWinnerResultData]

class interregnum.methods.preferential.condorcet.CondorcetCopelandAllocator(allow_ties=True, fill_truncated=False)

Bases: CondorcetAllocator[AnyName]

Copeland’s pairwise aggregation method.

See https://en.wikipedia.org/wiki/Copeland%27s_method

allocators collection keys:

  • copeland

  • condorcet_copeland

Create a Copeland allocator.

Parameters:

  • allow_ties (bool) – allow more than one candidate at the same preference position

  • fill_truncated (bool) – fill a truncated ballot with a tie of the remaining candidates

class interregnum.methods.preferential.condorcet.CondorcetMinimaxAllocator(margin=False, allow_ties=True, fill_truncated=False)

Bases: CondorcetAllocator[AnyName]

Minimax / Simpson-Kramer method.

See https://en.wikipedia.org/wiki/Minimax_Condorcet

allocators collection keys:

  • minimax

  • condorcet_minimax

Create a Minimax allocator.

Parameters:

  • margin (bool) – If margin is True, use vote margins instead of difference of votes as the inner score.

  • allow_ties (bool) – allow more than one candidate at the same preference position

  • fill_truncated (bool) – fill a truncated ballot with a tie of the remaining candidates

class interregnum.methods.preferential.condorcet.CondorcetRankedPairsAllocator(allow_ties=True, fill_truncated=False)

Bases: NonDeterministicAllocator[AnyName, RPResultData]

Ranked pairs Condorcet allocator.

allocators collection keys:

  • ranked_pairs

  • condorcet_ranked_pairs

Create a ranked pairs allocator.

Parameters:

  • allow_ties (bool) – allow more than one candidate at the same preference position

  • fill_truncated (bool) – fill a truncated ballot with a tie of the remaining candidates

calc(preferences, seats=1, random_seed=None, candidate_list=None)

Allocate seats to candidates.

Parameters:

  • preferences (Iterable[Preference[AnyName] | PrefDict[AnyName] | tuple[int | Fraction, Sequence[AnyName | Tuple[AnyName, ...] | list[AnyName]] | tuple[AnyName | Tuple[AnyName, ...] | list[AnyName], ...]]]) – list of grouped preference ballots

  • seats (int) – seats to allocate

  • random_seed (int | Random | None) – used to break ties

  • candidate_list (Iterable[AnyName] | None) – full list of allowed candidates

Return type:

NonDeterministicResult[AnyName, RPResultData]

Submodules

interregnum.methods.preferential.condorcet.pairwise module

Table for Condorcet methods’ auxiliary operations.

References

class interregnum.methods.preferential.condorcet.pairwise.PairwiseTable(nodes)

Bases: WeightedGraph[AnyName, int | Fraction]

Bi-dimensional sparse table for Condorcet.

Create a table with this nodes.

Parameters:

nodes (ipt.INames[AnyName])

classmethod from_preferences(preferences, *, fill_truncated=False, all_nodes=None)

Create a PairwiseTable from a list of preferential votes.

Each preferential vote is preceded by the number of occurrences.

>>> votes = [
        (42, ('Memphis', 'Nashville', 'Chattanooga', 'Knoxville')),
        (26, ('Nashville', 'Chattanooga', 'Knoxville', 'Memphis')),
        (15, ('Chattanooga', 'Knoxville', 'Nashville', 'Memphis')),
        (17, ('Knoxville', 'Chattanooga', 'Nashville', 'Memphis'))
    ]
>>> t = PairwiseTable.from_preferences(votes)
Parameters:

  • preferences (Iterable[Preference[AnyName]])

  • fill_truncated (bool)

  • all_nodes (Iterable[AnyName] | None)

Return type:

PairwiseTable[AnyName]

compare(cand1, cand2)

Compare the elements at cand1-cand2 and cand2-cand1.

If the value of (x,y) is greater than the value of (y, x), return (x, y). If both values are equal, return None. Otherwise, return (y, x).

>>> t = PairwiseTable()
>>> t['Alice', 'Bob'] = 5
>>> t['Bob', 'Alice'] = 7
>>> t['Bob', 'Charles'] = 3
>>> # ('Bob', 'Alice')
>>> t.compare('Alice', 'Bob')
>>> # ('Bob', 'Charles')
>>> t.compare('Bob', 'Charles')
>>> # None
>>> t.compare('Alex', 'Zoe')
Parameters:
Return type:

tuple[AnyName, AnyName] | None

margin(cand1, cand2)

Return margin value between cand1 and cand2.

Return value at (cand1, cand2) minus value at (cand2, cand1)

>>> t = PairwiseTable()
>>> t['Alice', 'Bob'] = 5
>>> t['Bob', 'Alice'] = 7
>>> # -2
>>> t.margin('Alice', 'Bob')
Parameters:
Return type:

int | Fraction

margins()

Return a weighted graph from margin values.

The weight of an edge (x, y) will be margin(x, y).

Return type:

WeightedGraph[AnyName, int | Fraction | float]

purge(cand)

Purge candidate from table.

Parameters:

cand (AnyName)

Return type:

None

schwartz_set()

Compute Schwartz set.

Return type:

set[AnyName]

smith_set()

Compute Smith set.

Return type:

set[AnyName]

win(cand1, cand2)

Winner votes of (cand1, cand2) against (cand2, cand1).

If cand1 does not win cand2, return 0.

>>> t = PairwiseTable()
>>> t['Alice', 'Bob'] = 5
>>> t['Bob', 'Alice'] = 7
>>> # 0
>>> t.win('Alice', 'Bob')
>>> # 7
>>> t.win('Bob', 'Alice')
Parameters:
Return type:

int | Fraction

wins()

Return a weighted graph from win values.

The weight of an edege (x, y) will be win(x, y)

Return type:

WeightedGraph[AnyName, int | Fraction | float]

interregnum.methods.preferential.condorcet.ranked_pairs module

Ranked pairs Condorcet allocator.

class interregnum.methods.preferential.condorcet.ranked_pairs.CondorcetRankedPairsAllocator(allow_ties=True, fill_truncated=False)

Bases: NonDeterministicAllocator[AnyName, RPResultData]

Ranked pairs Condorcet allocator.

allocators collection keys:

  • ranked_pairs

  • condorcet_ranked_pairs

Create a ranked pairs allocator.

Parameters:

  • allow_ties (bool) – allow more than one candidate at the same preference position

  • fill_truncated (bool) – fill a truncated ballot with a tie of the remaining candidates

calc(preferences, seats=1, random_seed=None, candidate_list=None)

Allocate seats to candidates.

Parameters:

  • preferences (Iterable[Preference[AnyName] | PrefDict[AnyName] | tuple[int | Fraction, Sequence[AnyName | Tuple[AnyName, ...] | list[AnyName]] | tuple[AnyName | Tuple[AnyName, ...] | list[AnyName], ...]]]) – list of grouped preference ballots

  • seats (int) – seats to allocate

  • random_seed (int | Random | None) – used to break ties

  • candidate_list (Iterable[AnyName] | None) – full list of allowed candidates

Return type:

NonDeterministicResult[AnyName, RPResultData]

class interregnum.methods.preferential.condorcet.ranked_pairs.RPResultData(log=<factory>, threshold=0, remaining_seats=0, rounds=0)

Bases: MultiWinnerResultData

Result data for ranked pairs.

Parameters:

  • log (list[Event])

  • threshold (int | Fraction)

  • remaining_seats (int)

  • rounds (int)

rounds: int = 0
class interregnum.methods.preferential.condorcet.ranked_pairs.RPState(data=<factory>, *, random_seed)

Bases: NonDeterministicState

Ranked-pairs allocator state.

Parameters:

  • data (RPResultData)

  • random_seed (dataclasses.InitVar[Union[int, random.Random, NoneType]])

break_tie(candidates, limit)

Break a candidates tie.

Parameters:

  • candidates (Iterable[AnotherName]) – list of tied candidates

  • limit (int) – number of desired winners

Return type:

tuple[str, list[AnotherName]]

find_winners(score)

Find winners given a ranked pairs score.

Parameters:

score (RankedPairs[AnyName])

Return type:

list[Candidate[AnyName]]

iter_pairs(score)

Iterate ranked pairs.

Parameters:

score (RankedPairs[AnyName])

Return type:

Iterator[Candidate[tuple[AnyName, AnyName]]]

data: RPResultData

interregnum.methods.preferential.condorcet.rankings module

Ranking list object for Condorcet methods.

class interregnum.methods.preferential.condorcet.rankings.Copeland(candidates, candidate_list=None)

Bases: Ranking[AnyName]

Copeland’s pairwise aggregation method.

See https://en.wikipedia.org/wiki/Copeland%27s_method

Create a Copeland ranking.

Parameters:

  • candidates (Iterable[Preference[AnyName]]) – list of preferences

  • candidate_list (ipt.INames[AnyName] | None) – full list of allowed candidates

empty()

Return True if the score is empty.

Return type:

bool

remove_name(name)

Remove candidate by name.

Parameters:

name (AnyName)

Return type:

None

winners()

Get winners sorted by score.

Return type:

list[Candidate[AnyName]]

class interregnum.methods.preferential.condorcet.rankings.Minimax(candidates, margin=False, candidate_list=None)

Bases: Ranking[AnyName]

Minimax / Simpson-Kramer method.

See https://en.wikipedia.org/wiki/Minimax_Condorcet

Create a Minimax ranking.

Parameters:

  • candidates (Iterable[Preference[AnyName]]) – list of preferences

  • candidate_list (ipt.INames[AnyName] | None) – full list of allowed candidates

  • margin (bool)

empty()

Return True if there is no contender.

Return type:

bool

remove_name(name)

Remove candidate by name.

Parameters:

name (AnyName)

Return type:

None

winners()

Get winners sorted by score.

Return type:

list[Candidate[AnyName]]

class interregnum.methods.preferential.condorcet.rankings.RankedPairs(candidates, candidate_list=None)

Bases: Ranking[tuple[AnyName, AnyName]]

Ranked pairs / Tideman method.

See https://en.wikipedia.org/wiki/Ranked_pairs

Create a ranked pairs ranking.

Parameters:

  • candidates (Sequence[Preference[AnyName]]) – list of preferences

  • candidate_list (ipt.INames[AnyName] | None) – full list of allowed candidates

contenders()

List of contenders.

Return type:

list[AnyName]

empty()

Return True if there is no contender.

Return type:

bool

remove_candidate(cand)

Remove candidate from calculations.

Parameters:

cand (Candidate[AnyName])

Return type:

None

remove_name(name)

Remove candidate by name from calculations.

Parameters:

name (tuple[AnyName, AnyName])

Return type:

None

winners()

Get winners sorted by score.

Return type:

list[Candidate[tuple[AnyName, AnyName]]]