BallotLevels¶

class whalrus.BallotLevels(b: dict, candidates: set = None, scale: whalrus.scales.scale.Scale = None)[source]¶

Ballot with an evaluation of the candidates.

Parameters

b (dict) – Keys: candidates. Values represent some form of evaluation. The keys and the values must be hashable.
candidates (set) – The candidates that were available at the moment when the voter cast her ballot. Default: candidates that are explicitly mentioned in the ballot b.
scale (Scale) – The authorized scale of evaluations at the moment when the voter cast her ballot. Default: Scale() (meaning in this case “unknown”).

Examples

Most general syntax:

>>> ballot = BallotLevels({'a': 10, 'b': 7, 'c': 3},
...                       candidates={'a', 'b', 'c', 'd', 'e'},
...                       scale=ScaleRange(low=0, high=10))

Other examples of syntax:

>>> ballot = BallotLevels({'a': 10, 'b': 7, 'c': 3})
>>> ballot = BallotLevels({'a': 'Good', 'b': 'Bad', 'c': 'Bad'},
...                       scale=ScaleFromList(['Bad', 'Medium', 'Good']))

In addition to the set-like and list-like behaviors defined in parent class BallotOrder, it also has a dictionary-like behavior in the sense that it implements __getitem__:

>>> ballot = BallotLevels({'a': 10, 'b': 7, 'c': 3})
>>> ballot['a']
10

property as_dict¶

keys are candidates and values are levels of evaluation.

Examples

>>> BallotLevels({'a': 10, 'b': 7, 'c': 3}).as_dict
{'a': 10, 'b': 7, 'c': 3}

Type: NiceDict

property as_strict_order¶

Strict order format.

It is a list of candidates. For example, ['a', 'b', 'c'] means that a is preferred to b, who is preferred to c.

Raises: ValueError – If the ballot is not a strict order.

Examples

>>> BallotOrder('a > b > c').as_strict_order
['a', 'b', 'c']

Type: list

property candidates¶

the candidates.

If the set was not explicitly given, the candidates are inferred from the ballot.

Examples

>>> BallotOrder('a ~ b > c', candidates={'a', 'b', 'c', 'd', 'e'}).candidates
{'a', 'b', 'c', 'd', 'e'}
>>> BallotOrder('a ~ b > c').candidates
{'a', 'b', 'c'}

Type: NiceSet

property candidates_not_in_b¶

the candidates that were available at the moment of the vote, but are not explicitly mentioned in the ballot.

Examples

>>> BallotOrder('a ~ b > c', candidates={'a', 'b', 'c', 'd', 'e'}).candidates_not_in_b
{'d', 'e'}

Type: NiceSet

first(candidates: set = None, **kwargs) → object¶

The first (= most liked) candidate.

Parameters

candidates (set of candidates) – It can be any set of candidates, not necessarily a subset of self.candidates. Default: self.candidates.
kwargs –
- priority: a Priority. Default: Priority.UNAMBIGUOUS.
- include_unordered: a boolean. If True (default), then unordered candidates are considered present but below the others.

Returns

The first (= most liked) candidate, chosen in the intersection of self.candidates and the argument candidates. Can return None for an “abstention”.

Return type

candidate

Examples

>>> print(BallotOrder('a ~ b').first(priority=Priority.ASCENDING))
a
>>> print(BallotOrder('a > b', candidates={'a', 'b', 'c'}).first(candidates={'c'}))
c
>>> print(BallotOrder('a > b', candidates={'a', 'b', 'c'}).first(candidates={'c'},
...                                                              include_unordered=False))
None

property is_strict¶

Whether the ballot is a strict order or not.

True if the order is strict, i.e. if each indifference class contains one element. There can be some unordered candidates.

Examples

>>> BallotOrder('a > b > c').is_strict
True
>>> BallotOrder('a > b > c', candidates={'a', 'b', 'c', 'd', 'e'}).is_strict
True
>>> BallotOrder('a ~ b > c').is_strict
False

Type: bool

items() → ItemsView[source]¶

Items of the ballot.

Returns: This is a shortcut for self.as_dict.items().
Return type: ItemsView

Examples

>>> ballot = BallotLevels({'a': 10, 'b': 7, 'c': 3}, candidates={'a', 'b', 'c', 'd', 'e'})
>>> sorted(ballot.items())
[('a', 10), ('b', 7), ('c', 3)]

keys() → KeysView[source]¶

Keys of the ballot.

Returns: This is a shortcut for self.as_dict.keys().
Return type: KeysView

Examples

>>> ballot = BallotLevels({'a': 10, 'b': 7, 'c': 3}, candidates={'a', 'b', 'c', 'd', 'e'})
>>> sorted(ballot.keys())
['a', 'b', 'c']

last(candidates: set = None, **kwargs) → object¶

The last (= most disliked) candidate.

Parameters

candidates (set of candidates) – It can be any set of candidates, not necessarily a subset of self.candidates. Default is self.candidates.
kwargs –
- priority: a Priority object. Default: Priority.UNAMBIGUOUS.
- include_unordered: a boolean. If True (default), then unordered candidates are considered present but below the others.

Returns

The last (= most disliked) candidate, chosen in the intersection of self.candidates and the argument candidates. Can return None for an “abstention”.

Return type

candidate

Examples

>>> print(BallotOrder('a ~ b').last(priority=Priority.ASCENDING))
b
>>> print(BallotOrder('a > b', candidates={'a', 'b', 'c'}).last())
c
>>> print(BallotOrder('a > b', candidates={'a', 'b', 'c'}).last(include_unordered=False))
b
>>> ballot = BallotOrder('a > b', candidates={'a', 'b', 'c', 'd'})
>>> print(ballot.last(candidates={'c', 'd'}, include_unordered=False))
None

restrict(candidates: set = None, **kwargs) → whalrus.ballots.ballot_levels.BallotLevels[source]¶

Restrict the ballot to less candidates.

Parameters

candidates (set of candidates) – It can be any set of candidates, not necessarily a subset of self.candidates). Default: self.candidates.
kwargs – Some options (depending on the subclass).

Returns

The same ballot, “restricted” to the candidates given.

Return type

BallotOrder

Examples

Typical usage:

>>> ballot = BallotOrder('a ~ b > c')
>>> ballot
BallotOrder([{'a', 'b'}, 'c'], candidates={'a', 'b', 'c'})
>>> ballot.restrict(candidates={'b', 'c'})
BallotOrder(['b', 'c'], candidates={'b', 'c'})

More general usage:

>>> ballot.restrict(candidates={'b', 'c', 'd'})
BallotOrder(['b', 'c'], candidates={'b', 'c'})

In the last example above, note that d is not in the candidates of the restricted ballot, as she was not available at the moment when the voter cast her ballot.

values() → ValuesView[source]¶

Values of the ballot.

Returns: This is a shortcut for self.as_dict.values().
Return type: ValuesView

Examples

>>> ballot = BallotLevels({'a': 10, 'b': 7, 'c': 3}, candidates={'a', 'b', 'c', 'd', 'e'})
>>> sorted(ballot.values())
[3, 7, 10]