RuleIteratedElimination

class whalrus.RuleIteratedElimination(*args, base_rule: whalrus.rules.rule.Rule = None, elimination: whalrus.eliminations.elimination.Elimination = None, propagate_tie_break=True, **kwargs)

A rule by iterated elimination (such as RuleIRV, RuleCoombs, RuleNanson, etc.)

Parameters:

• args – Cf. parent class.
• base_rule (Rule) – The rule used at each round to determine the eliminated candidate(s). Unlike for RuleSequentialElimination, all the rounds use the same voting rule.
• elimination (Elimination) – The elimination algorithm. Default: EliminationLast(k=1).
• propagate_tie_break (bool) – If True (default), then the tie-breaking rule of this object is also used for the base rule (cf. below).
• kwargs – Cf. parent class.

Examples

>>> irv = RuleIteratedElimination(['a > b > c', 'b > a > c', 'c > a > b'], weights=[2, 3, 4],
...                                 base_rule=RulePlurality())
>>> irv.eliminations_[0].rule_.gross_scores_
{'a': 2, 'b': 3, 'c': 4}
>>> irv.eliminations_[1].rule_.gross_scores_
{'b': 5, 'c': 4}
>>> irv.eliminations_[2].rule_.gross_scores_
{'b': 9}
>>> irv.winner_
'b'

Remark: there exists a shortcut for the above rule in particular, the class RuleIRV.

By default, propagate_tie_break is True. So if you want to specify a tie-breaking rule, just do it in the parameters of this object, and it will also be used in the base rule. This is probably what you want to do:

>>> irv = RuleIteratedElimination(['a > c > b', 'b > a > c', 'c > a > b'], weights=[1, 2, 1],
...                                 base_rule=RulePlurality(), tie_break=Priority.ASCENDING)
>>> irv.eliminations_[0].rule_.gross_scores_
{'a': 1, 'b': 2, 'c': 1}
>>> irv.eliminations_[1].rule_.gross_scores_
{'a': 2, 'b': 2}
>>> irv.eliminations_[2].rule_.gross_scores_
{'a': 4}
>>> irv.winner_
'a'

If propagate_tie_break is False, then there is a subtlety between the tie-breaking rule of this object, and the tie-breaking rule of the base rule. The following (somewhat contrived) example illustrates the respective roles of the two tie-breaking rules.

>>> rule = RuleIteratedElimination(
...     ['a', 'b', 'c', 'd', 'e'], weights=[3, 2, 2, 2, 1],
...     tie_break=Priority.DESCENDING, propagate_tie_break=False,
...     base_rule=RulePlurality(tie_break=Priority.ASCENDING), elimination=EliminationLast(k=2))
>>> rule.eliminations_[0].rule_.gross_scores_
{'a': 3, 'b': 2, 'c': 2, 'd': 2, 'e': 1}

With the worst score, e is eliminated anyway, but we need to eliminate a second candidate because k = 2. In Plurality, b, c and d are tied, but since Plurality’s tie-breaking rule is ASCENDING, candidates b or c get an advantage over d. Hence d is eliminated:

>>> rule.eliminations_[0].eliminated_
{'d', 'e'}

Note that the tie-breaking rule of the base rule (here Plurality) is always sufficient to compute the weak order over the candidates. This order may be finer than the elimination order, because being eliminated at the same time does not mean being tied, as d and e illustrate here:

>>> rule.order_
[{'a'}, {'b', 'c'}, {'d'}, {'e'}]

So, where does the tie-breaking rule of this object come in? It is simply used to get the strict order over the candidates, as usual in a Rule. In our example, since it is DESCENDING, candidate c gets an advantage over b:

>>> rule.strict_order_
['a', 'c', 'b', 'd', 'e']

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

eliminations_

The elimination rounds. A list of Elimination objects. The first one corresponds to the first round, etc.

Type:list

n_candidates_

Number of candidates.

Type:int

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