Profile

class whalrus.Profile(ballots: Union[list, Profile], weights: list = None, voters: list = None)

A profile of ballots.

Parameters

• ballots (iterable) – Typically, it is a list, but it can also be a Profile. Its elements must be Ballot objects or, more generally, inputs that can be interpreted by ConverterBallotGeneral.

• weights (list) – A list of numbers representing the weights of the ballots. Default: if ballots is a Profile, then use the weights of this profile; otherwise, all weights are 1.

• voters (list) – A list representing the voters corresponding to the ballots. Default: if ballots is a Profile, then use the voters of this profile; otherwise, all voters are None.

Examples

Most general syntax:

>>> profile = Profile(
...     ballots=[BallotOrder('a > b ~ c'), BallotOrder('a ~ b > c')],
...     weights=[2, 1],
...     voters=['Alice', 'Bob']
... )
>>> print(profile)
Alice (2): a > b ~ c
Bob (1): a ~ b > c

In the following example, each ballot illustrates a different syntax:

>>> profile = Profile([
...     ['a', 'b', 'c'],
...     ('b', 'c', 'a'),
...     'c > a > b',
... ])
>>> print(profile)
a > b > c
b > c > a
c > a > b

Profiles have a list-like behavior in the sense that they implement __len__, __getitem__, __setitem__ and __delitem__:

>>> profile = Profile(['a > b', 'b > a', 'a ~ b'])
>>> len(profile)
3
>>> profile[0]
BallotOrder(['a', 'b'], candidates={'a', 'b'})
>>> profile[0] = 'a ~ b'
>>> print(profile)
a ~ b
b > a
a ~ b
>>> del profile[0]
>>> print(profile)
b > a
a ~ b

Profiles can be concatenated:

>>> profile = Profile(['a > b', 'b > a']) + ['a ~ b']
>>> print(profile)
a > b
b > a
a ~ b

Profiles can be multiplied by a scalar, which multiplies the weights:

>>> profile = Profile(['a > b', 'b > a']) * 3
>>> print(profile)
(3): a > b
(3): b > a

append(ballot: object, weight: numbers.Number = 1, voter: object = None) → None

Append a ballot to the profile.

Parameters

• ballot (object) – A ballot or, more generally, an input that can be interpreted by ConverterBallotGeneral.

• weight (Number) – The weight of the ballot.

• voter (object) – The voter.

Examples

>>> profile = Profile(['a > b'])
>>> profile.append('b > a')
>>> print(profile)
a > b
b > a

property ballots

The ballots.

Examples

>>> profile = Profile(['a > b', 'b > a'])
>>> profile.ballots
[BallotOrder(['a', 'b'], candidates={'a', 'b'}), BallotOrder(['b', 'a'], candidates={'a', 'b'})]

Type

list of Ballot

property has_voters

Presence of explicit voters. True iff at least one voter is not None.

Examples

>>> profile = Profile(['a > b', 'b > a'])
>>> profile.has_voters
False

Type

bool

property has_weights

Presence of non-trivial weights. True iff at least one weight is not 1.

Examples

>>> profile = Profile(['a > b', 'b > a'])
>>> profile.has_weights
False

Type

bool

items() → Iterator

Items of the profile.

Returns

A zip of triples (ballot, weight, voter).

Return type

Iterator

Examples

>>> profile = Profile(['a > b', 'b > a'])
>>> for ballot, weight, voter in profile.items():
...     print('Ballot %s, weight %s, voter %s.' % (ballot, weight, voter))
Ballot a > b, weight 1, voter None.
Ballot b > a, weight 1, voter None.

remove(ballot: object = None, voter: object = None) → None

Remove a ballot from the profile.

If only the ballot is specified, remove the first matching ballot in the profile. If only the voter is specified, remove the first ballot whose voter matches the given voter. If both are specified, remove the first ballot matching both descriptions.

Parameters

• ballot (object) – The ballot or, more generally, an input that can be interpreted by ConverterBallotGeneral.

• voter (object) – The voter.

Examples

>>> profile = Profile(['a > b', 'b > a'])
>>> profile.remove('b > a')
>>> print(profile)
a > b

property voters

The voters.

Examples

>>> profile = Profile(['a > b', 'b > a'], voters=['Alice', 'Bob'])
>>> profile.voters
['Alice', 'Bob']

Type

list

property weights

The weights.

Examples

>>> profile = Profile(['a > b', 'b > a'])
>>> profile.weights
[1, 1]

Type

list of Number