class whalrus.ScorerLevels(*args, level_ungraded: object = None, level_absent: object = None, **kwargs)[source]

A standard scorer for :class:BallotLevel.

  • args – Cf. parent class.
  • level_ungraded (object) – The level of the scale used for ungraded candidates, or None.
  • level_absent (object) – The level of the scale used for absent candidates, or None.
  • kwargs – Cf. parent class.


In the most general syntax, firstly, you define the scorer:

>>> scorer = ScorerLevels(level_absent=0)

Secondly, you use it as a callable to load some particular arguments:

>>> scorer(ballot=BallotLevels({'a': 10, 'b': 7, 'c': 3}), voter='Alice',
...        candidates={'a', 'b', 'c', 'd'})  # doctest:+ELLIPSIS
<... object at ...>

Finally, you can access the computed variables:

>>> scorer.scores_
{'a': 10, 'b': 7, 'c': 3, 'd': 0}

Later, if you wish, you can load other arguments (ballot, etc) with the same scorer, and so on.

Optionally, you can specify arguments as soon as the Scorer object is initialized. This allows for “one-liners” such as:

>>> ScorerLevels(ballot=BallotLevels({'a': 10, 'b': 7, 'c': 3}), voter='Alice',
...              candidates={'a', 'b', 'c', 'd'}, level_absent=0).scores_
{'a': 10, 'b': 7, 'c': 3, 'd': 0}

In the example below, candidates a, b and c are “ordered”, d is “unordered”, and e is “absent” in the ballot, meaning that e were not even available when the voter cast her ballot. The options of the scorer provide different ways to take these special cases into account:

>>> ballot=BallotLevels({'a': 10, 'b': 7, 'c': 3}, candidates={'a', 'b', 'c', 'd'})
>>> candidates_election = {'a', 'b', 'c', 'd', 'e'}
>>> ScorerLevels(ballot, candidates=candidates_election).scores_
{'a': 10, 'b': 7, 'c': 3}
>>> ScorerLevels(ballot, candidates=candidates_election,
...              level_ungraded=-5).scores_
{'a': 10, 'b': 7, 'c': 3, 'd': -5}
>>> ScorerLevels(ballot, candidates=candidates_election,
...              level_ungraded=-5, level_absent=-10).scores_
{'a': 10, 'b': 7, 'c': 3, 'd': -5, 'e': -10}

The scores, given as floats. It is the same as scores_, but converted to floats.

Like all conversions to floats, it is advised to use this attribute for display purposes only. For computation, you should always use scores_, which usually manipulates fractions and therefore allows for exact computation.

Raises:ValueError – If the scores cannot be converted to floats.