RuleSequentialElimination

class whalrus.RuleSequentialElimination(*args, rules: Union[list, whalrus.rules.rule.Rule] = None, eliminations: Union[list, whalrus.eliminations.elimination.Elimination] = None, propagate_tie_break=True, **kwargs)

A rule by sequential elimination (such as RuleTwoRound).

Parameters:

• args – Cf. parent class.
• rules (list of Rule) – A list of rules, one for each round. Unlike for RuleIteratedElimination, different rounds may use different voting rules.
• eliminations (list of Elimination) – A list of elimination algorithms, one for each round except the last one.
• propagate_tie_break (bool) – If True (default), then the tie-breaking rule of this object is also used for the base rules. Cf. RuleIteratedElimination for more explanation on this parameter.
• kwargs – Cf. parent class.

Examples

>>> rule = RuleSequentialElimination(
...     ['a > b > c > d > e', 'b > c > d > e > a'], weights=[2, 1],
...     rules=[RuleBorda(), RulePlurality(), RulePlurality()],
...     eliminations=[EliminationBelowAverage(), EliminationLast(k=1)])
>>> rule.elimination_rounds_[0].rule_.gross_scores_
{'a': 8, 'b': 10, 'c': 7, 'd': 4, 'e': 1}
>>> rule.elimination_rounds_[1].rule_.gross_scores_
{'a': 2, 'b': 1, 'c': 0}
>>> rule.final_round_.gross_scores_
{'a': 2, 'b': 1}

If rules is not a list, the number of rounds is inferred from eliminations. An application of this is to define the two-round system:

>>> rule = RuleSequentialElimination(
...     ['a > b > c > d > e', 'b > a > c > d > e', 'c > a > b > d > e'], weights=[2, 2, 1],
...     rules=RulePlurality(), eliminations=[EliminationLast(k=-2)])
>>> rule.elimination_rounds_[0].rule_.gross_scores_
{'a': 2, 'b': 2, 'c': 1, 'd': 0, 'e': 0}
>>> rule.final_round_.gross_scores_
{'a': 3, 'b': 2}

Note: there exists a shortcut for the above rule in particular, the class RuleTwoRound.

Similarly, if elimination is not a list, the number of rounds is deduced from rules:

>>> rule = RuleSequentialElimination(
...     ['a > b > c > d > e', 'b > a > c > d > e'], weights=[2, 1],
...     rules=[RuleBorda(), RuleBorda(), RulePlurality()], eliminations=EliminationLast(k=1))
>>> rule.elimination_rounds_[0].rule_.gross_scores_
{'a': 11, 'b': 10, 'c': 6, 'd': 3, 'e': 0}
>>> rule.elimination_rounds_[1].rule_.gross_scores_
{'a': 8, 'b': 7, 'c': 3, 'd': 0}
>>> rule.final_round_.gross_scores_
{'a': 2, 'b': 1, 'c': 0}

cotrailers_

“Cotrailers” of the election, i.e. the candidates that fare worst in the election. This is the last equivalence class in order_. For example, in RuleScoreNum, it is the candidates that are tied for the worst score.

Type:NiceSet

cowinners_

Cowinners of the election, i.e. the candidates that fare best in the election.. This is the first equivalence class in order_. For example, in RuleScoreNum, it is the candidates that are tied for the best score.

Type:NiceSet

elimination_rounds_

The elimination rounds. A list of Elimination objects. All rounds except the last one.

Type:list

final_round_

The final round, which decides the winner of the election.

Type:Rule

n_candidates_

Number of candidates.

Type:int

rounds_

The rounds. All rounds but the last one are Elimination objects. The last one is a Rule object.

Examples

Note that in some cases, there may be fewer actual rounds than declared in the definition of the rule:

>>> rule = RuleSequentialElimination(
...     ['a > b > c > d', 'a > c > d > b', 'a > d > b > c'],
...     rules=[RuleBorda(), RulePlurality(), RulePlurality()],
...     eliminations=[EliminationBelowAverage(), EliminationLast(k=1)])
>>> len(rule.rounds_)
2
>>> rule.elimination_rounds_[0].rule_.gross_scores_
{'a': 9, 'b': 3, 'c': 3, 'd': 3}
>>> rule.final_round_.gross_scores_
{'a': 3}

Type:list

strict_order_

Result of the election as a strict order over the candidates. The first element is the winner, etc. This may use the tie-breaking rule.

Type:list

trailer_

The “trailer” of the election. This is the last candidate in strict_order_ and also the unfavorable choice of the tie-breaking rule in cotrailers_.

Type:object

winner_

The winner of the election. This is the first candidate in strict_order_ and also the choice of the tie-breaking rule in cowinners_.

Type:object