RuleRangeVoting¶

class whalrus.RuleRangeVoting(*args, converter: whalrus.converters_ballot.converter_ballot.ConverterBallot = None, scorer: whalrus.scorers.scorer.Scorer = None, **kwargs)[source]¶

Range voting.

Parameters

args – Cf. parent class.
converter (ConverterBallot) – Default: ConverterBallotToGrades.
scorer (Scorer) – Default: ScorerLevels.
kwargs – Cf. parent class.

Examples

Typical usage:

>>> RuleRangeVoting([{'a': 1, 'b': .8, 'c': .2}, {'a': 0, 'b': .6, 'c': 1}]).scores_
{'a': Fraction(1, 2), 'b': Fraction(7, 10), 'c': Fraction(3, 5)}
>>> RuleRangeVoting([{'a': 10, 'b': 8, 'c': 2}, {'a': 0, 'b': 6, 'c': 10}]).scores_
{'a': 5, 'b': 7, 'c': 6}

The following examples use the ballot converter:

>>> RuleRangeVoting(['a > b > c']).profile_converted_[0].as_dict
{'a': 1, 'b': Fraction(1, 2), 'c': 0}
>>> RuleRangeVoting(
...     ['a > b > c'], converter=ConverterBallotToGrades(scale=ScaleRange(0, 10))
... ).profile_converted_[0].as_dict
{'a': 10, 'b': 5, 'c': 0}

To examine the effect of the options, let us examine:

>>> b1 = BallotLevels({'a': 8, 'b': 10}, candidates={'a', 'b'})
>>> b2 = BallotLevels({'a': 6, 'c': 10}, candidates={'a', 'b', 'c'})

In ballot b1, candidate c is absent, which means that the candidate was not even available when the voter cast her ballot. In ballot b2, candidate b is ungraded: it was available, but the voter decided not to give it a grade. By the way, we will also introduce a candidate d who receives no evaluation at all. Here are several possible settings for the voting rule, along with their consequences:

>>> RuleRangeVoting([b1, b2], candidates={'a', 'b', 'c', 'd'}).scores_
{'a': 7, 'b': 10, 'c': 10, 'd': 0}
>>> RuleRangeVoting([b1, b2], candidates={'a', 'b', 'c', 'd'}, default_average=5).scores_
{'a': 7, 'b': 10, 'c': 10, 'd': 5}
>>> RuleRangeVoting([b1, b2], candidates={'a', 'b', 'c', 'd'},
...     scorer=ScorerLevels(level_ungraded=0)).scores_
{'a': 7, 'b': 5, 'c': 10, 'd': 0}
>>> RuleRangeVoting([b1, b2], candidates={'a', 'b', 'c', 'd'},
...     scorer=ScorerLevels(level_ungraded=0, level_absent=0)).scores_
{'a': 7, 'b': 5, 'c': 5, 'd': 0}

For more information, cf. ScorerLevels.

property average_score_¶

The average score.

Type: Number

property average_score_as_float_¶

The average score as a float. It is the same as average_score_, but converted to a float.

Type: float

property best_score_as_float_¶

The best score as a float. It is the same as RuleScore.best_score_, but converted to a float.

Type: float

compare_scores(one: numbers.Number, another: numbers.Number) → int¶

Compare two scores.

Parameters

one (object) – A score.
another (object) – A score.

Returns

0 if they are equal, a positive number if one is greater than another, a negative number otherwise.

Return type

int

property cotrailers_¶

“Cotrailers”. The set of candidates with the worst score.

Type: NiceSet

property cowinners_¶

Cowinners. The set of candidates with the best score.

Type: NiceSet

property gross_scores_¶

The gross scores of the candidates. For each candidate, this dictionary gives the sum of its scores, multiplied by the weights of the corresponding voters. This is the numerator in the candidate’s average score.

Type: NiceDict

property gross_scores_as_floats_¶

Gross scores as floats. It is the same as gross_scores_, but converted to floats.

Type: NiceDict

property n_candidates_¶

Number of candidates.

Type: int

property scores_as_floats_¶

Scores as floats. It is the same as scores_, but converted to floats.

Type: NiceDict

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 weights_¶

The weights used for the candidates. For each candidate, this dictionary gives the total weight for this candidate, i.e. the total weight of all voters who assign a score to this candidate. This is the denominator in the candidate’s average score.

Type: NiceDict

property weights_as_floats_¶

Weights as floats. It is the same as weights_, but converted to floats.

Type: NiceDict

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

property worst_score_as_float_¶

The worst score as a float. It is the same as RuleScore.worst_score_, but converted to a float.

Type: float