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

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

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

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

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

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[KT, VT_co][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[KT][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[VT_co][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]