Rule¶

class whalrus.Rule(*args, tie_break: whalrus.priorities.priority.Priority = Priority.UNAMBIGUOUS, converter: whalrus.converters_ballot.converter_ballot.ConverterBallot = None, **kwargs)[source]¶

A voting rule.

A Rule object is a callable whose inputs are ballots and optionally weights, voters and candidates. When the rule is called, it loads the profile. The output of the call is the rule itself. But after the call, you can access to the computed variables (ending with an underscore), such as cowinners_.

At the initialization of a Rule object, some options can be given, such as a tie-break rule or a converter. In some subclasses, there can also be an option about the way to count abstentions, etc.

Parameters

args – If present, these parameters will be passed to __call__ immediately after initialization.
tie_break (Priority) – A tie-break rule.
converter (ConverterBallot) – The converter that is used to convert input ballots in order to compute profile_converted_. Default: ConverterBallotGeneral.
kwargs – If present, these parameters will be passed to __call__ immediately after initialization.

profile_original_¶

The profile as it is entered by the user. Since it uses the constructor of Profile, it indirectly uses ConverterBallotGeneral to ensure, for example, that strings like 'a > b > c' are converted to Ballot objects.

Type: Profile

profile_converted_¶

The profile, with ballots that are adapted to the voting rule. For example, in RulePlurality, it will be BallotPlurality objects, even if the original ballots are BallotOrder objects. This uses the parameter converter of the rule.

Type: Profile

candidates_¶

The candidates of the election, as entered in the __call__.

Type: NiceSet

Examples

Cf. RulePlurality for some examples.

property 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

property 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

property n_candidates_¶

Number of candidates.

Type: int

property order_¶

Result of the election as a (weak) order over the candidates. This is a list of NiceSet. The first set contains the candidates that are tied for victory, etc.

Type: list

property 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

property 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

property 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