Profile module

Contents

Profile module#

Module describing different profile formats. A profile simply correspond to a list of ballots (see the ballot module), one for each voter of the election. The structure of this module is very similar to that of the ballot module.

All profiles are derived from the AbstractProfile class. Then, two general categories of profiles are introduced. First, the usual profiles that contain one ballot per voter. These are implemented by the following classes, all inheriting from the class Profile:

The second category of profiles this module introduce are the so-called multiprofile. In those profiles, only unique ballots are stored, together with their multiplicity. Frozen ballots are used here as the ballots need to be non-mutable. The corresponding classes all inherit from MultiProfile, and are:

For each type of profile, we also define a corresponding abstract class. This can be used for typing purposes, but also for attributes and methods that apply both to the profile and the multiprofile. These classes are:

class AbstractProfile(instance: Instance | None = None, ballot_validation: bool | None = None, ballot_type: type[AbstractBallot] | None = None)[source]#

Bases: ABC, Iterable[AbstractBallot]

Abstract class representing a profile, that is, a collection of ballots. This class is only meant to be inherited.

Parameters:

  • instance (Instance, optional) – The instance related to the profile. Defaults to Instance().

  • ballot_validation (bool, optional) – Boolean indicating whether ballots should be validated before being added to the profile. Defaults to True.

  • ballot_type (type[AbstractBallot], optional) – The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised. Defaults to AbstractBallot.

instance#

The instance related to the profile.

Type:

Instance

ballot_validation#

Boolean indicating whether ballots should be validated before being added to the profile.

Type:

bool

ballot_type#

The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised.

Type:

type[AbstractBallot]

abstract as_sat_profile(sat_class: type[SatisfactionMeasure]) → GroupSatisfactionMeasure[source]#

Converts the profile into a satisfaction profile. See the satisfaction for more details.

Parameters:

sat_class (type[SatisfactionMeasure]) – The class for the representing the satisfaction measure to use.

Returns:

A satisfaction profile, that is, a collection of satisfaction measures for all the voters.

Return type:

py:class:~pabutools.election.satisfaction.satisfactionmeasure.GroupSatisfactionMeasure

abstract multiplicity(ballot: AbstractBallot) → int[source]#

Method returning the multiplicity of a ballot. Used to ensure that Profile and MultiProfile can be used interchangeably.

Parameters:

ballot (AbstractBallot) – The ballot whose multiplicity is inquired.

Returns:

The multiplicity of the ballots.

Return type:

int

abstract num_ballots() → int[source]#

Returns the number of ballots appearing in the profile. Used to ensure that Profile and MultiProfile can be used interchangeably.

Returns:

The number of voters.

Return type:

int

validate_ballot(ballot: AbstractBallot) → None[source]#

Method validating a ballot before adding it to the profile. Checks if the type of the ballot is a subclass of the attribute ballot_type. Throws a TypeError if not, and returns None otherwise.

Parameters:

ballot (AbstractBallot) – The ballot to be checked.

class Profile(init: Iterable[Ballot] = (), instance: Instance | None = None, ballot_validation: bool | None = None, ballot_type: type[Ballot] | None = None)[source]#

Bases: list, AbstractProfile

A profile, that is, a list of ballots per voters. This class inherits from the Python list class and can thus be used as one. All other profile classes inherit form this one.

Parameters:

  • init (Iterable[Ballot], optional) – An iterable of Ballot that is used as initializer for the list. If activated, the types of the ballots are validated. In case an AbstractProfile object is passed, the additional attributes are also copied (except if the corresponding keyword arguments have been given).

  • instance (Instance, optional) – The instance related to the profile. Defaults to Instance().

  • ballot_validation (bool, optional) – Boolean indicating whether ballots should be validated before being added to the profile. Defaults to True.

  • ballot_type (type[AbstractBallot], optional) – The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised. Defaults to Ballot.

instance#

The instance related to the profile.

Type:

Instance

ballot_validation#

Boolean indicating whether ballots should be validated before being added to the profile.

Type:

bool

ballot_type#

The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised.

Type:

type[AbstractBallot]

append(item: Ballot) → None[source]#

Append object to the end of the list.

abstract as_multiprofile() → MultiProfile[source]#

Converts the profile into a MultiProfile.

Returns:

The multiprofile corresponding to the profile.

Return type:

MultiProfile

as_sat_profile(sat_class: type[SatisfactionMeasure])[source]#

Converts the profile into a satisfaction profile. See the satisfaction for more details.

Parameters:

sat_class (type[SatisfactionMeasure]) – The class for the representing the satisfaction measure to use.

Returns:

A satisfaction profile, that is, a collection of satisfaction measures for all the voters.

Return type:

py:class:~pabutools.election.satisfaction.satisfactionmeasure.GroupSatisfactionMeasure

extend(other) → None[source]#

Extend list by appending elements from the iterable.

insert(index: int, item: Ballot) → None[source]#

Insert object before index.

multiplicity(ballot: Ballot) → int[source]#

Returns 1 regardless of the input (even if the ballot does not appear in the profile, to save up computation).

Parameters:

ballot (AbstractBallot) – The ballot whose multiplicity is inquired.

Returns:

1

Return type:

int

num_ballots() → int[source]#

Returns the number of ballots appearing in the profile. Used to ensure that Profile and MultiProfile can be used interchangeably.

Returns:

The number of voters.

Return type:

int

class MultiProfile(init: Iterable[FrozenBallot] = (), instance: Instance | None = None, ballot_validation: bool | None = None, ballot_type: type[FrozenBallot] | None = None)[source]#

Bases: Counter, AbstractProfile

A multiprofile, that is, a profile that stores the ballots together with their multiplicity. This class inherits from the Python Counter class (a special type of dict meant to represent multisets) and can be used as one. All other multiprofile classes inherit form this one.

Parameters:

  • init (Iterable[Ballot], optional) – An iterable of Ballot that is used as initializer for the list. If activated, the types of the ballots are validated. In case an AbstractProfile object is passed, the additional attributes are also copied (except if the corresponding keyword arguments have been given).

  • instance (Instance, optional) – The instance related to the profile. Defaults to Instance().

  • ballot_validation (bool, optional) – Boolean indicating whether ballots should be validated before being added to the profile. Defaults to True.

  • ballot_type (type[AbstractBallot], optional) – The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised. Defaults to FrozenBallot.

instance#

The instance related to the profile.

Type:

Instance

ballot_validation#

Boolean indicating whether ballots should be validated before being added to the profile.

Type:

bool

ballot_type#

The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised.

Type:

type[AbstractBallot]

append(ballot: AbstractBallot)[source]#

Appends a ballot to the profile and update the multiplicity if necessary.

Parameters:

ballot (AbstractBallot) – The ballot to append to the profile.

as_sat_profile(sat_class: type[SatisfactionMeasure])[source]#

Converts the profile into a satisfaction profile. See the satisfaction for more details.

Parameters:

sat_class (type[SatisfactionMeasure]) – The class for the representing the satisfaction measure to use.

Returns:

A satisfaction profile, that is, a collection of satisfaction measures for all the voters.

Return type:

py:class:~pabutools.election.satisfaction.satisfactionmeasure.GroupSatisfactionMeasure

extend(iterable: Iterable[AbstractBallot], force_freeze=True)[source]#

Extends the profile by appending all the ballots in the iterable.

Parameters:

  • iterable (Iterable[AbstractBallot]) – An iterable of ballots to add to the profile.

  • force_freeze (bool, optional) – Boolean indicating whether subclasses of Ballot should be frozen beforehand. Defaults to True.

multiplicity(ballot: FrozenBallot) → int[source]#

Method returning the multiplicity of a ballot. Used to ensure that Profile and MultiProfile can be used interchangeably.

Parameters:

ballot (AbstractBallot) – The ballot whose multiplicity is inquired.

Returns:

The multiplicity of the ballots.

Return type:

int

num_ballots() → int[source]#

Returns the number of ballots appearing in the profile. Used to ensure that Profile and MultiProfile can be used interchangeably.

Returns:

The number of voters.

Return type:

int

total()[source]#

Sum of the counts

class AbstractApprovalProfile(legal_min_length: int | None = None, legal_max_length: int | None = None, legal_min_cost: int | float | mpq | None = None, legal_max_cost: int | float | mpq | None = None)[source]#

Bases: AbstractProfile, ABC, Iterable[AbstractApprovalBallot]

Abstract class for approval profiles. Stores the metadata and the methods specific to approval profiles.

Parameters:

  • legal_min_length (int, optional) – The minimum length of an approval ballot per the rules of the election. Defaults to None.

  • legal_max_length (int, optional) – The maximum length of an approval ballot per the rules of the election. Defaults to None.

  • legal_min_cost (Numeric, optional) – The minimum total cost of an approval ballot per the rules of the election. Defaults to None.

  • legal_max_cost (Numeric, optional) – The maximum total cost of an approval ballot per the rules of the election. Defaults to None.

legal_min_length#

The minimum length of an approval ballot per the rules of the election.

Type:

int

legal_max_length#

The maximum length of an approval ballot per the rules of the election.

Type:

int

legal_min_cost#

The minimum total cost of an approval ballot per the rules of the election.

Type:

Numeric

legal_max_cost#

The maximum total cost of an approval ballot per the rules of the election.

Type:

Numeric

approval_score(project: Project) → int[source]#

Returns the approval score of a project, that is, the number of voters who approved of it.

Parameters:

project (Project) – The project.

Returns:

The approval score.

Return type:

int

approved_projects() → set[Project][source]#

Returns the set of all the projects approved by at least one voter.

Returns:

The set of projects with at least one supporter.

Return type:

set[Project]

is_party_list() → bool[source]#

Checks whether the profile is a party-list profile. In a party-list profile all approval sets are either disjoint or equal.

Returns:

True if the profile is party-list and False otherwise.

Return type:

bool

is_trivial() → bool[source]#

Tests if the profile is trivial, meaning that all projects that are approved by at least one voter have a cost that exceeds the budget limit.

Returns:

True if the profile is trivial, and False otherwise.

Return type:

bool

class ApprovalProfile(init: Iterable[ApprovalBallot] = (), instance: Instance | None = None, ballot_validation: bool | None = None, ballot_type: type[AbstractBallot] | None = None, legal_min_length: int | None = None, legal_max_length: int | None = None, legal_min_cost: int | float | mpq | None = None, legal_max_cost: int | float | mpq | None = None)[source]#

Bases: Profile, AbstractApprovalProfile

A profile of approval ballots, that is, a list of approval ballots per voters. See the class ApprovalBallot for more details on approval ballots. This class inherits from the Python list class and can thus be used as one.

Parameters:

  • init (Iterable[ApprovalBallot], optional) – An iterable of ApprovalBallot that is used an initializer for the list. If activated, the types of the ballots are validated. In case an AbstractProfile object is passed, the additional attributes are also copied (except if the corresponding keyword arguments have been given).

  • instance (Instance, optional) – The instance related to the profile. Defaults to Instance().

  • ballot_validation (bool, optional) – Boolean indicating whether ballots should be validated before being added to the profile. Defaults to True.

  • ballot_type (type[AbstractBallot], optional) – The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised. Defaults to ApprovalBallot.

  • legal_min_length (int, optional) – The minimum length of an approval ballot per the rules of the election. Defaults to None.

  • legal_max_length (int, optional) – The maximum length of an approval ballot per the rules of the election. Defaults to None.

  • legal_min_cost (Numeric, optional) – The minimum total cost of an approval ballot per the rules of the election. Defaults to None.

  • legal_max_cost (Numeric, optional) – The maximum total cost of an approval ballot per the rules of the election. Defaults to None.

instance#

The instance related to the profile.

Type:

Instance

ballot_validation#

Boolean indicating whether ballots should be validated before being added to the profile.

Type:

bool

ballot_type#

The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised.

Type:

type[AbstractBallot]

legal_min_length#

The minimum length of an approval ballot per the rules of the election.

Type:

int

legal_max_length#

The maximum length of an approval ballot per the rules of the election.

Type:

int

legal_min_cost#

The minimum total cost of an approval ballot per the rules of the election.

Type:

Numeric

legal_max_cost#

The maximum total cost of an approval ballot per the rules of the election.

Type:

Numeric

append(item: Ballot) → None#

Append object to the end of the list.

approval_score(project: Project) → int#

Returns the approval score of a project, that is, the number of voters who approved of it.

Parameters:

project (Project) – The project.

Returns:

The approval score.

Return type:

int

approved_projects() → set[Project]#

Returns the set of all the projects approved by at least one voter.

Returns:

The set of projects with at least one supporter.

Return type:

set[Project]

as_multiprofile()[source]#

Converts the profile into a ApprovalMultiProfile.

Returns:

The multiprofile corresponding to the profile.

Return type:

ApprovalMultiProfile

as_sat_profile(sat_class: type[SatisfactionMeasure])#

Converts the profile into a satisfaction profile. See the satisfaction for more details.

Parameters:

sat_class (type[SatisfactionMeasure]) – The class for the representing the satisfaction measure to use.

Returns:

A satisfaction profile, that is, a collection of satisfaction measures for all the voters.

Return type:

py:class:~pabutools.election.satisfaction.satisfactionmeasure.GroupSatisfactionMeasure

clear()#

Remove all items from list.

copy(*args)#

Return a shallow copy of the list.

count(value, /)#

Return number of occurrences of value.

extend(other) → None#

Extend list by appending elements from the iterable.

index(value, start=0, stop=9223372036854775807, /)#

Return first index of value.

Raises ValueError if the value is not present.

insert(index: int, item: Ballot) → None#

Insert object before index.

is_party_list() → bool#

Checks whether the profile is a party-list profile. In a party-list profile all approval sets are either disjoint or equal.

Returns:

True if the profile is party-list and False otherwise.

Return type:

bool

is_trivial() → bool#

Tests if the profile is trivial, meaning that all projects that are approved by at least one voter have a cost that exceeds the budget limit.

Returns:

True if the profile is trivial, and False otherwise.

Return type:

bool

multiplicity(ballot: Ballot) → int#

Returns 1 regardless of the input (even if the ballot does not appear in the profile, to save up computation).

Parameters:

ballot (AbstractBallot) – The ballot whose multiplicity is inquired.

Returns:

1

Return type:

int

num_ballots() → int#

Returns the number of ballots appearing in the profile. Used to ensure that Profile and MultiProfile can be used interchangeably.

Returns:

The number of voters.

Return type:

int

pop(index=-1, /)#

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)#

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse(*args)#

Reverse IN PLACE.

sort(*, key=None, reverse=False)#

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

validate_ballot(ballot: AbstractBallot) → None#

Method validating a ballot before adding it to the profile. Checks if the type of the ballot is a subclass of the attribute ballot_type. Throws a TypeError if not, and returns None otherwise.

Parameters:

ballot (AbstractBallot) – The ballot to be checked.

class ApprovalMultiProfile(init: Iterable[FrozenApprovalBallot] = (), instance: Instance | None = None, ballot_validation: bool | None = None, ballot_type: type[FrozenBallot] | None = None, profile: ApprovalProfile | None = None, legal_min_length: int | None = None, legal_max_length: int | None = None, legal_min_cost: int | float | mpq | None = None, legal_max_cost: int | float | mpq | None = None)[source]#

Bases: MultiProfile, AbstractApprovalProfile

A multiprofile of approval ballots, that is, a multiset of approval ballots together with their multiplicity. Ballots needs to be hashable, so the class FrozenApprovalBallot should be used by default here. This class inherits from the Python Counter class and can thus be used as one.

Parameters:

  • init (Iterable[FrozenApprovalBallot], optional) – An iterable of FrozenApprovalBallot that is used an initializer for the counter. If activated, the types of the ballots are validated. In case an AbstractProfile object is passed, the additional attributes are also copied (except if the corresponding keyword arguments have been given).

  • instance (Instance, optional) – The instance related to the profile. Defaults to Instance().

  • ballot_validation (bool, optional) – Boolean indicating whether ballots should be validated before being added to the profile. Defaults to True.

  • ballot_type (type[AbstractBallot], optional) – The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised. Defaults to FrozenApprovalBallot.

  • profile (ApprovalProfile, optional) – A profile used to initialise the multiprofile. Some metadata are taken from the profile if they are not specified in the constructor.

  • legal_min_length (int, optional) – The minimum length of an approval ballot per the rules of the election. Defaults to None.

  • legal_max_length (int, optional) – The maximum length of an approval ballot per the rules of the election. Defaults to None.

  • legal_min_cost (Numeric, optional) – The minimum total cost of an approval ballot per the rules of the election. Defaults to None.

  • legal_max_cost (Numeric, optional) – The maximum total cost of an approval ballot per the rules of the election. Defaults to None.

instance#

The instance related to the profile.

Type:

Instance

ballot_validation#

Boolean indicating whether ballots should be validated before being added to the profile.

Type:

bool

ballot_type#

The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised.

Type:

type[AbstractBallot]

legal_min_length#

The minimum length of an approval ballot per the rules of the election.

Type:

int

legal_max_length#

The maximum length of an approval ballot per the rules of the election.

Type:

int

legal_min_cost#

The minimum total cost of an approval ballot per the rules of the election.

Type:

Numeric

legal_max_cost#

The maximum total cost of an approval ballot per the rules of the election.

Type:

Numeric

append(ballot: AbstractBallot)#

Appends a ballot to the profile and update the multiplicity if necessary.

Parameters:

ballot (AbstractBallot) – The ballot to append to the profile.

approval_score(project: Project) → int#

Returns the approval score of a project, that is, the number of voters who approved of it.

Parameters:

project (Project) – The project.

Returns:

The approval score.

Return type:

int

approved_projects() → set[Project]#

Returns the set of all the projects approved by at least one voter.

Returns:

The set of projects with at least one supporter.

Return type:

set[Project]

as_sat_profile(sat_class: type[SatisfactionMeasure])#

Converts the profile into a satisfaction profile. See the satisfaction for more details.

Parameters:

sat_class (type[SatisfactionMeasure]) – The class for the representing the satisfaction measure to use.

Returns:

A satisfaction profile, that is, a collection of satisfaction measures for all the voters.

Return type:

py:class:~pabutools.election.satisfaction.satisfactionmeasure.GroupSatisfactionMeasure

clear() → None.  Remove all items from D.#
copy(*args)#

Return a shallow copy.

elements()#

Iterator over elements repeating each as many times as its count.

>>> c = Counter('ABCABC')
>>> sorted(c.elements())
['A', 'A', 'B', 'B', 'C', 'C']

Knuth’s example for prime factors of 1836: 2**2 * 3**3 * 17**1

>>> import math
>>> prime_factors = Counter({2: 2, 3: 3, 17: 1})
>>> math.prod(prime_factors.elements())
1836

Note, if an element’s count has been set to zero or is a negative number, elements() will ignore it.

extend(iterable: Iterable[AbstractBallot], force_freeze=True)#

Extends the profile by appending all the ballots in the iterable.

Parameters:

  • iterable (Iterable[AbstractBallot]) – An iterable of ballots to add to the profile.

  • force_freeze (bool, optional) – Boolean indicating whether subclasses of Ballot should be frozen beforehand. Defaults to True.

classmethod fromkeys(iterable, v=None)#

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)#

Return the value for key if key is in the dictionary, else default.

is_party_list() → bool#

Checks whether the profile is a party-list profile. In a party-list profile all approval sets are either disjoint or equal.

Returns:

True if the profile is party-list and False otherwise.

Return type:

bool

is_trivial() → bool#

Tests if the profile is trivial, meaning that all projects that are approved by at least one voter have a cost that exceeds the budget limit.

Returns:

True if the profile is trivial, and False otherwise.

Return type:

bool

items() → a set-like object providing a view on D's items#
keys() → a set-like object providing a view on D's keys#
most_common(n=None)#

List the n most common elements and their counts from the most common to the least. If n is None, then list all element counts.

>>> Counter('abracadabra').most_common(3)
[('a', 5), ('b', 2), ('r', 2)]
multiplicity(ballot: FrozenBallot) → int#

Method returning the multiplicity of a ballot. Used to ensure that Profile and MultiProfile can be used interchangeably.

Parameters:

ballot (AbstractBallot) – The ballot whose multiplicity is inquired.

Returns:

The multiplicity of the ballots.

Return type:

int

num_ballots() → int#

Returns the number of ballots appearing in the profile. Used to ensure that Profile and MultiProfile can be used interchangeably.

Returns:

The number of voters.

Return type:

int

pop(k[, d]) → v, remove specified key and return the corresponding value.#

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()#

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)#

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

subtract(iterable=None, /, **kwds)#

Like dict.update() but subtracts counts instead of replacing them. Counts can be reduced below zero. Both the inputs and outputs are allowed to contain zero and negative counts.

Source can be an iterable, a dictionary, or another Counter instance.

>>> c = Counter('which')
>>> c.subtract('witch')             # subtract elements from another iterable
>>> c.subtract(Counter('watch'))    # subtract elements from another counter
>>> c['h']                          # 2 in which, minus 1 in witch, minus 1 in watch
0
>>> c['w']                          # 1 in which, minus 1 in witch, minus 1 in watch
-1
total()#

Sum of the counts

update(iterable=None, /, **kwds)#

Like dict.update() but add counts instead of replacing them.

Source can be an iterable, a dictionary, or another Counter instance.

>>> c = Counter('which')
>>> c.update('witch')           # add elements from another iterable
>>> d = Counter('watch')
>>> c.update(d)                 # add elements from another counter
>>> c['h']                      # four 'h' in which, witch, and watch
4
validate_ballot(ballot: AbstractBallot) → None#

Method validating a ballot before adding it to the profile. Checks if the type of the ballot is a subclass of the attribute ballot_type. Throws a TypeError if not, and returns None otherwise.

Parameters:

ballot (AbstractBallot) – The ballot to be checked.

values() → an object providing a view on D's values#
get_random_approval_profile(instance: Instance, num_agents: int) → ApprovalProfile[source]#

Generates a random approval profile in which approval ballots are such that each project is approved with probability 0.5.

Parameters:

  • instance (Instance) – The instance the profile is defined with respect to.

  • num_agents (int) – The length of the profile, i.e., the number of agents.

Returns:

The randomly generated profile.

Return type:

ApprovalProfile

get_all_approval_profiles(instance: Instance, num_agents: int) → Generator[ApprovalProfile][source]#

Returns a generator over all the possible profile for a given instance of a given length.

Parameters:

  • instance (Instance) – The instance the profile is defined with respect to.

  • num_agents (int) – The length of the profile, i.e., the number of agents..

Returns:

Generator over subsets of projects.

Return type:

Generator[Iterable[Project]]

class AbstractCardinalProfile(legal_min_length: int | None = None, legal_max_length: int | None = None, legal_min_score: int | float | mpq | None = None, legal_max_score: int | float | mpq | None = None)[source]#

Bases: AbstractProfile, ABC, Iterable[AbstractCardinalBallot]

Abstract class for cardinal profiles. Stores the metadata and the methods specific to cardinal profiles.

Parameters:

  • legal_min_length (int, optional) – The minimum number of projects a voter needs to assign a score to per the rules of the election. Defaults to None.

  • legal_max_length (int, optional) – The maximum number of projects a voter needs to assign a score to per the rules of the election. Defaults to None.

  • legal_min_score (Numeric, optional) – The minimum score a project can be assigned by a voter per the rules of the election. Defaults to None.

  • legal_max_score (Numeric, optional) – The maximum score a project can be assigned by a voter per the rules of the election. Defaults to None.

legal_min_length#

The minimum number of projects a voter needs to assign a score to per the rules of the election.

Type:

int

legal_max_length#

The maximum number of projects a voter needs to assign a score to per the rules of the election.

Type:

int

legal_min_score#

The minimum score a project can be assigned by a voter per the rules of the election.

Type:

Numeric

legal_max_score#

The maximum score a project can be assigned by a voter per the rules of the election.

Type:

Numeric

total_score(project: Project) → int | float | mpq[source]#

Returns the total score of a project, that is, the sum of scores received from all voters.

Parameters:

project (Project) – The project.

Returns:

The total score assigned to the project.

Return type:

Numeric

class CardinalProfile(init: Iterable[CardinalBallot] = (), instance: Instance | None = None, ballot_validation: bool | None = None, ballot_type: type[Ballot] | None = None, legal_min_length: int | None = None, legal_max_length: int | None = None, legal_min_score: int | float | mpq | None = None, legal_max_score: int | float | mpq | None = None)[source]#

Bases: Profile, AbstractCardinalProfile

A profile of cardinal ballots, that is, a list of cardinal ballots per voters. See the class CardinalBallot for more details on cardinal ballots. This class inherits from the Python list class and can thus be used as one.

Parameters:

  • init (Iterable[CardinalBallot], optional) – An iterable of CardinalBallot that is used an initializer for the list. If activated, the types of the ballots are validated. In case an AbstractProfile object is passed, the additional attributes are also copied (except if the corresponding keyword arguments have been given).

  • instance (Instance, optional) – The instance related to the profile. Defaults to Instance().

  • ballot_validation (bool, optional) – Boolean indicating whether ballots should be validated before being added to the profile. Defaults to True.

  • ballot_type (type[AbstractBallot], optional) – The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised. Defaults to CardinalBallot.

  • legal_min_length (int, optional) – The minimum number of projects a voter needs to assign a score to per the rules of the election. Defaults to None.

  • legal_max_length (int, optional) – The maximum number of projects a voter needs to assign a score to per the rules of the election. Defaults to None.

  • legal_min_score (Numeric, optional) – The minimum score a project can be assigned by a voter per the rules of the election. Defaults to None.

  • legal_max_score (Numeric, optional) – The maximum score a project can be assigned by a voter per the rules of the election. Defaults to None.

instance#

The instance related to the profile.

Type:

Instance

ballot_validation#

Boolean indicating whether ballots should be validated before being added to the profile.

Type:

bool

ballot_type#

The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised.

Type:

type[AbstractBallot]

legal_min_length#

The minimum number of projects a voter needs to assign a score to per the rules of the election.

Type:

int

legal_max_length#

The maximum number of projects a voter needs to assign a score to per the rules of the election.

Type:

int

legal_min_score#

The minimum score a project can be assigned by a voter per the rules of the election.

Type:

Numeric

legal_max_score#

The maximum score a project can be assigned by a voter per the rules of the election.

Type:

Numeric

append(item: Ballot) → None#

Append object to the end of the list.

as_multiprofile()[source]#

Converts the profile into a CardinalMultiProfile.

Returns:

The multiprofile corresponding to the profile.

Return type:

CardinalMultiProfile

as_sat_profile(sat_class: type[SatisfactionMeasure])#

Converts the profile into a satisfaction profile. See the satisfaction for more details.

Parameters:

sat_class (type[SatisfactionMeasure]) – The class for the representing the satisfaction measure to use.

Returns:

A satisfaction profile, that is, a collection of satisfaction measures for all the voters.

Return type:

py:class:~pabutools.election.satisfaction.satisfactionmeasure.GroupSatisfactionMeasure

clear()#

Remove all items from list.

complete(projects: Collection[Project], default_score: int | float | mpq) → None[source]#

Completes all the ballots such that for all ballots, if a project from projects has not been assigned a score, then it is assigned default_score.

Parameters:

  • projects (Iterable[Project]) – The set of all the projects to consider. This is typically the instance.

  • default_score (Numeric) – The default score that will be assigned.

copy(*args)#

Return a shallow copy of the list.

count(value, /)#

Return number of occurrences of value.

extend(other) → None#

Extend list by appending elements from the iterable.

index(value, start=0, stop=9223372036854775807, /)#

Return first index of value.

Raises ValueError if the value is not present.

insert(index: int, item: Ballot) → None#

Insert object before index.

multiplicity(ballot: Ballot) → int#

Returns 1 regardless of the input (even if the ballot does not appear in the profile, to save up computation).

Parameters:

ballot (AbstractBallot) – The ballot whose multiplicity is inquired.

Returns:

1

Return type:

int

num_ballots() → int#

Returns the number of ballots appearing in the profile. Used to ensure that Profile and MultiProfile can be used interchangeably.

Returns:

The number of voters.

Return type:

int

pop(index=-1, /)#

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)#

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse(*args)#

Reverse IN PLACE.

sort(*, key=None, reverse=None)[source]#

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

total_score(project: Project) → int | float | mpq#

Returns the total score of a project, that is, the sum of scores received from all voters.

Parameters:

project (Project) – The project.

Returns:

The total score assigned to the project.

Return type:

Numeric

validate_ballot(ballot: AbstractBallot) → None#

Method validating a ballot before adding it to the profile. Checks if the type of the ballot is a subclass of the attribute ballot_type. Throws a TypeError if not, and returns None otherwise.

Parameters:

ballot (AbstractBallot) – The ballot to be checked.

class CardinalMultiProfile(init: Iterable[FrozenCardinalBallot] = (), instance: Instance | None = None, ballot_validation: bool | None = None, ballot_type: type[FrozenBallot] | None = None, profile: CardinalProfile | None = None, legal_min_length: int | None = None, legal_max_length: int | None = None, legal_min_score: int | float | mpq | None = None, legal_max_score: int | float | mpq | None = None)[source]#

Bases: MultiProfile, AbstractCardinalProfile

A multiprofile of cardinal ballots, that is, a multiset of cardinal ballots together with their multiplicity. Ballots needs to be hashable, so the class FrozenCardinalBallot should be used by default here. This class inherits from the Python Counter class and can thus be used as one.

Parameters:

  • init (Iterable[FrozenCardinalBallot], optional) – An iterable of FrozenCardinalBallot that is used an initializer for the list. If activated, the types of the ballots are validated. In case an AbstractProfile object is passed, the additional attributes are also copied (except if the corresponding keyword arguments have been given).

  • instance (Instance, optional) – The instance related to the profile. Defaults to Instance().

  • ballot_validation (bool, optional) – Boolean indicating whether ballots should be validated before being added to the profile. Defaults to True.

  • ballot_type (type[AbstractBallot], optional) – The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised. Defaults to CardinalBallot.

  • profile (CardinalProfile, optional) – A profile used to initialise the multiprofile. Some metadata are taken from the profile if they are not specified in the constructor.

  • legal_min_length (int, optional) – The minimum number of projects a voter needs to assign a score to per the rules of the election. Defaults to None.

  • legal_max_length (int, optional) – The maximum number of projects a voter needs to assign a score to per the rules of the election. Defaults to None.

  • legal_min_score (Numeric, optional) – The minimum score a project can be assigned by a voter per the rules of the election. Defaults to None.

  • legal_max_score (Numeric, optional) – The maximum score a project can be assigned by a voter per the rules of the election. Defaults to None.

instance#

The instance related to the profile.

Type:

Instance

ballot_validation#

Boolean indicating whether ballots should be validated before being added to the profile.

Type:

bool

ballot_type#

The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised.

Type:

type[AbstractBallot]

legal_min_length#

The minimum number of projects a voter needs to assign a score to per the rules of the election.&

Type:

int

legal_max_length#

The maximum number of projects a voter needs to assign a score to per the rules of the election.

Type:

int

legal_min_score#

The minimum score a project can be assigned by a voter per the rules of the election.

Type:

Numeric

legal_max_score#

The maximum score a project can be assigned by a voter per the rules of the election.

Type:

Numeric

append(ballot: AbstractBallot)#

Appends a ballot to the profile and update the multiplicity if necessary.

Parameters:

ballot (AbstractBallot) – The ballot to append to the profile.

as_sat_profile(sat_class: type[SatisfactionMeasure])#

Converts the profile into a satisfaction profile. See the satisfaction for more details.

Parameters:

sat_class (type[SatisfactionMeasure]) – The class for the representing the satisfaction measure to use.

Returns:

A satisfaction profile, that is, a collection of satisfaction measures for all the voters.

Return type:

py:class:~pabutools.election.satisfaction.satisfactionmeasure.GroupSatisfactionMeasure

clear() → None.  Remove all items from D.#
copy(*args)#

Return a shallow copy.

elements()#

Iterator over elements repeating each as many times as its count.

>>> c = Counter('ABCABC')
>>> sorted(c.elements())
['A', 'A', 'B', 'B', 'C', 'C']

Knuth’s example for prime factors of 1836: 2**2 * 3**3 * 17**1

>>> import math
>>> prime_factors = Counter({2: 2, 3: 3, 17: 1})
>>> math.prod(prime_factors.elements())
1836

Note, if an element’s count has been set to zero or is a negative number, elements() will ignore it.

extend(iterable: Iterable[AbstractBallot], force_freeze=True)#

Extends the profile by appending all the ballots in the iterable.

Parameters:

  • iterable (Iterable[AbstractBallot]) – An iterable of ballots to add to the profile.

  • force_freeze (bool, optional) – Boolean indicating whether subclasses of Ballot should be frozen beforehand. Defaults to True.

classmethod fromkeys(iterable, v=None)#

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)#

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items#
keys() → a set-like object providing a view on D's keys#
most_common(n=None)#

List the n most common elements and their counts from the most common to the least. If n is None, then list all element counts.

>>> Counter('abracadabra').most_common(3)
[('a', 5), ('b', 2), ('r', 2)]
multiplicity(ballot: FrozenBallot) → int#

Method returning the multiplicity of a ballot. Used to ensure that Profile and MultiProfile can be used interchangeably.

Parameters:

ballot (AbstractBallot) – The ballot whose multiplicity is inquired.

Returns:

The multiplicity of the ballots.

Return type:

int

num_ballots() → int#

Returns the number of ballots appearing in the profile. Used to ensure that Profile and MultiProfile can be used interchangeably.

Returns:

The number of voters.

Return type:

int

pop(k[, d]) → v, remove specified key and return the corresponding value.#

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()#

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

score(project: Project) → int | float | mpq[source]#

Returns the score of a project, that is, the sum of scores received from all voters. :param project: The project. :type project: pabutools.election.instance.Project

Return type:

Fraction

setdefault(key, default=None, /)#

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

subtract(iterable=None, /, **kwds)#

Like dict.update() but subtracts counts instead of replacing them. Counts can be reduced below zero. Both the inputs and outputs are allowed to contain zero and negative counts.

Source can be an iterable, a dictionary, or another Counter instance.

>>> c = Counter('which')
>>> c.subtract('witch')             # subtract elements from another iterable
>>> c.subtract(Counter('watch'))    # subtract elements from another counter
>>> c['h']                          # 2 in which, minus 1 in witch, minus 1 in watch
0
>>> c['w']                          # 1 in which, minus 1 in witch, minus 1 in watch
-1
total()#

Sum of the counts

total_score(project: Project) → int | float | mpq#

Returns the total score of a project, that is, the sum of scores received from all voters.

Parameters:

project (Project) – The project.

Returns:

The total score assigned to the project.

Return type:

Numeric

update(iterable=None, /, **kwds)#

Like dict.update() but add counts instead of replacing them.

Source can be an iterable, a dictionary, or another Counter instance.

>>> c = Counter('which')
>>> c.update('witch')           # add elements from another iterable
>>> d = Counter('watch')
>>> c.update(d)                 # add elements from another counter
>>> c['h']                      # four 'h' in which, witch, and watch
4
validate_ballot(ballot: AbstractBallot) → None#

Method validating a ballot before adding it to the profile. Checks if the type of the ballot is a subclass of the attribute ballot_type. Throws a TypeError if not, and returns None otherwise.

Parameters:

ballot (AbstractBallot) – The ballot to be checked.

values() → an object providing a view on D's values#
class AbstractCumulativeProfile(legal_min_length: int | None = None, legal_max_length: int | None = None, legal_min_score: int | float | mpq | None = None, legal_max_score: int | float | mpq | None = None, legal_min_total_score: int | float | mpq | None = None, legal_max_total_score: int | float | mpq | None = None)[source]#

Bases: AbstractCardinalProfile, ABC

Abstract class for cumulative profiles. Stores the metadata and the methods specific to cumulative profiles.

Parameters:

  • legal_min_length (int, optional) – The minimum number of projects a voter needs to assign a score to per the rules of the election. Defaults to None.

  • legal_max_length (int, optional) – The maximum number of projects a voter needs to assign a score to per the rules of the election. Defaults to None.

  • legal_min_score (Numeric, optional) – The minimum score a project can be assigned by a voter per the rules of the election. Defaults to None.

  • legal_max_score (Numeric, optional) – The maximum score a project can be assigned by a voter per the rules of the election. Defaults to None.

  • legal_min_total_score (Numeric, optional) – Minimum total score that can be assigned across all projects per the rules of the election. Defaults to None.

  • legal_max_total_score (Numeric, optional) – Maximum total score that can be assigned across all projects per the rules of the election. Defaults to None.

legal_min_length#

The minimum number of projects a voter needs to assign a score to per the rules of the election.

Type:

int

legal_max_length#

The maximum number of projects a voter needs to assign a score to per the rules of the election.

Type:

int

legal_min_score#

The minimum score a project can be assigned by a voter per the rules of the election.

Type:

Numeric

legal_max_score#

The maximum score a project can be assigned by a voter per the rules of the election.

Type:

Numeric

legal_min_total_score#

Minimum total score that can be assigned across all projects per the rules of the election.

Type:

Numeric

legal_max_total_score#

Maximum total score that can be assigned across all projects per the rules of the election.

Type:

Numeric

class CumulativeProfile(init: Iterable[CumulativeBallot] = (), instance: Instance | None = None, ballot_validation: bool | None = None, ballot_type: type[Ballot] | None = None, legal_min_length: int | None = None, legal_max_length: int | None = None, legal_min_score: int | float | mpq | None = None, legal_max_score: int | float | mpq | None = None, legal_min_total_score: int | float | mpq | None = None, legal_max_total_score: int | float | mpq | None = None)[source]#

Bases: CardinalProfile, AbstractCumulativeProfile

A profile of cumulative ballots, that is, a list of cumulative ballots per voters. See the class CumulativeBallot for more details on cumulative ballots. This class inherits from the Python list class and can thus be used as one.

Parameters:

  • init (Iterable[CumulativeBallot], optional) – An iterable of CumulativeBallot that is used an initializer for the list. If activated, the types of the ballots are validated. In case an AbstractProfile object is passed, the additional attributes are also copied (except if the corresponding keyword arguments have been given).

  • instance (Instance, optional) – The instance related to the profile. Defaults to Instance().

  • ballot_validation (bool, optional) – Boolean indicating whether ballots should be validated before being added to the profile. Defaults to True.

  • ballot_type (type[AbstractBallot], optional) – The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised. Defaults to CumulativeBallot.

  • legal_min_length (int, optional) – The minimum number of projects a voter needs to assign a score to per the rules of the election. Defaults to None.

  • legal_max_length (int, optional) – The maximum number of projects a voter needs to assign a score to per the rules of the election. Defaults to None.

  • legal_min_score (Numeric, optional) – The minimum score a project can be assigned by a voter per the rules of the election. Defaults to None.

  • legal_max_score (Numeric, optional) – The maximum score a project can be assigned by a voter per the rules of the election. Defaults to None.

  • legal_min_total_score (Numeric, optional) – Minimum total score that can be assigned across all projects per the rules of the election. Defaults to None.

  • legal_max_total_score (Numeric, optional) – Maximum total score that can be assigned across all projects per the rules of the election. Defaults to None.

instance#

The instance related to the profile.

Type:

Instance

ballot_validation#

Boolean indicating whether ballots should be validated before being added to the profile.

Type:

bool

ballot_type#

The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised.

Type:

type[AbstractBallot]

legal_min_length#

The minimum number of projects a voter needs to assign a score to per the rules of the election.

Type:

int

legal_max_length#

The maximum number of projects a voter needs to assign a score to per the rules of the election.

Type:

int

legal_min_score#

The minimum score a project can be assigned by a voter per the rules of the election.

Type:

Numeric

legal_max_score#

The maximum score a project can be assigned by a voter per the rules of the election.

Type:

Numeric

legal_min_total_score#

Minimum total score that can be assigned across all projects per the rules of the election.

Type:

Numeric

legal_max_total_score#

Maximum total score that can be assigned across all projects per the rules of the election.

Type:

Numeric

append(item: Ballot) → None#

Append object to the end of the list.

as_multiprofile()[source]#

Converts the profile into a CumulativeMultiProfile.

Returns:

The multiprofile corresponding to the profile.

Return type:

CumulativeMultiProfile

as_sat_profile(sat_class: type[SatisfactionMeasure])#

Converts the profile into a satisfaction profile. See the satisfaction for more details.

Parameters:

sat_class (type[SatisfactionMeasure]) – The class for the representing the satisfaction measure to use.

Returns:

A satisfaction profile, that is, a collection of satisfaction measures for all the voters.

Return type:

py:class:~pabutools.election.satisfaction.satisfactionmeasure.GroupSatisfactionMeasure

clear()#

Remove all items from list.

complete(projects: Collection[Project], default_score: int | float | mpq) → None#

Completes all the ballots such that for all ballots, if a project from projects has not been assigned a score, then it is assigned default_score.

Parameters:

  • projects (Iterable[Project]) – The set of all the projects to consider. This is typically the instance.

  • default_score (Numeric) – The default score that will be assigned.

copy(*args)#

Return a shallow copy of the list.

count(value, /)#

Return number of occurrences of value.

extend(other) → None#

Extend list by appending elements from the iterable.

index(value, start=0, stop=9223372036854775807, /)#

Return first index of value.

Raises ValueError if the value is not present.

insert(index: int, item: Ballot) → None#

Insert object before index.

multiplicity(ballot: Ballot) → int#

Returns 1 regardless of the input (even if the ballot does not appear in the profile, to save up computation).

Parameters:

ballot (AbstractBallot) – The ballot whose multiplicity is inquired.

Returns:

1

Return type:

int

num_ballots() → int#

Returns the number of ballots appearing in the profile. Used to ensure that Profile and MultiProfile can be used interchangeably.

Returns:

The number of voters.

Return type:

int

pop(index=-1, /)#

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)#

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse(*args)#

Reverse IN PLACE.

sort(*, key=None, reverse=None)[source]#

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

total_score(project: Project) → int | float | mpq#

Returns the total score of a project, that is, the sum of scores received from all voters.

Parameters:

project (Project) – The project.

Returns:

The total score assigned to the project.

Return type:

Numeric

validate_ballot(ballot: AbstractBallot) → None#

Method validating a ballot before adding it to the profile. Checks if the type of the ballot is a subclass of the attribute ballot_type. Throws a TypeError if not, and returns None otherwise.

Parameters:

ballot (AbstractBallot) – The ballot to be checked.

class CumulativeMultiProfile(init: Iterable[FrozenCumulativeBallot] = (), instance: Instance | None = None, ballot_validation: bool | None = None, ballot_type: type[FrozenBallot] | None = None, profile: CumulativeProfile | None = None, legal_min_length: int | None = None, legal_max_length: int | None = None, legal_min_score: int | float | mpq | None = None, legal_max_score: int | float | mpq | None = None, legal_min_total_score: int | float | mpq | None = None, legal_max_total_score: int | float | mpq | None = None)[source]#

Bases: CardinalMultiProfile, AbstractCumulativeProfile

A multiprofile of cardinal ballots, that is, a multiset of cumulative ballots together with their multiplicity. Ballots needs to be hashable, so the class FrozenCumulativeBallot should be used by default here. This class inherits from the Python Counter class and can thus be used as one.

Parameters:

  • init (Iterable[FrozenCumulativeBallot], optional) – An iterable of FrozenCumulativeBallot that is used as initializer for the list. If activated, the types of the ballots are validated. In case an AbstractProfile object is passed, the additional attributes are also copied (except if the corresponding keyword arguments have been given).

  • instance (Instance, optional) – The instance related to the profile. Defaults to Instance().

  • ballot_validation (bool, optional) – Boolean indicating whether ballots should be validated before being added to the profile. Defaults to True.

  • ballot_type (type[AbstractBallot], optional) – The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised. Defaults to FrozenCumulativeBallot.

  • profile (CumulativeProfile, optional) – A profile used to initialise the multiprofile. Some metadata are taken from the profile if they are not specified in the constructor.

  • legal_min_length (int, optional) – The minimum number of projects a voter needs to assign a score to per the rules of the election. Defaults to None.

  • legal_max_length (int, optional) – The maximum number of projects a voter needs to assign a score to per the rules of the election. Defaults to None.

  • legal_min_score (Numeric, optional) – The minimum score a project can be assigned by a voter per the rules of the election. Defaults to None.

  • legal_max_score (Numeric, optional) – The maximum score a project can be assigned by a voter per the rules of the election. Defaults to None.

  • legal_min_total_score (Numeric, optional) – Minimum total score that can be assigned across all projects per the rules of the election. Defaults to None.

  • legal_max_total_score (Numeric, optional) – Maximum total score that can be assigned across all projects per the rules of the election. Defaults to None.

instance#

The instance related to the profile.

Type:

Instance

ballot_validation#

Boolean indicating whether ballots should be validated before being added to the profile.

Type:

bool

ballot_type#

The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised.

Type:

type[AbstractBallot]

legal_min_length#

The minimum number of projects a voter needs to assign a score to per the rules of the election.

Type:

int

legal_max_length#

The maximum number of projects a voter needs to assign a score to per the rules of the election.

Type:

int

legal_min_score#

The minimum score a project can be assigned by a voter per the rules of the election.

Type:

Numeric

legal_max_score#

The maximum score a project can be assigned by a voter per the rules of the election.

Type:

Numeric

legal_min_total_score#

Minimum total score that can be assigned across all projects per the rules of the election.

Type:

Numeric

legal_max_total_score#

Maximum total score that can be assigned across all projects per the rules of the election.

Type:

Numeric

append(ballot: AbstractBallot)#

Appends a ballot to the profile and update the multiplicity if necessary.

Parameters:

ballot (AbstractBallot) – The ballot to append to the profile.

as_sat_profile(sat_class: type[SatisfactionMeasure])#

Converts the profile into a satisfaction profile. See the satisfaction for more details.

Parameters:

sat_class (type[SatisfactionMeasure]) – The class for the representing the satisfaction measure to use.

Returns:

A satisfaction profile, that is, a collection of satisfaction measures for all the voters.

Return type:

py:class:~pabutools.election.satisfaction.satisfactionmeasure.GroupSatisfactionMeasure

clear() → None.  Remove all items from D.#
copy(*args)#

Return a shallow copy.

elements()#

Iterator over elements repeating each as many times as its count.

>>> c = Counter('ABCABC')
>>> sorted(c.elements())
['A', 'A', 'B', 'B', 'C', 'C']

Knuth’s example for prime factors of 1836: 2**2 * 3**3 * 17**1

>>> import math
>>> prime_factors = Counter({2: 2, 3: 3, 17: 1})
>>> math.prod(prime_factors.elements())
1836

Note, if an element’s count has been set to zero or is a negative number, elements() will ignore it.

extend(iterable: Iterable[AbstractBallot], force_freeze=True)#

Extends the profile by appending all the ballots in the iterable.

Parameters:

  • iterable (Iterable[AbstractBallot]) – An iterable of ballots to add to the profile.

  • force_freeze (bool, optional) – Boolean indicating whether subclasses of Ballot should be frozen beforehand. Defaults to True.

classmethod fromkeys(iterable, v=None)#

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)#

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items#
keys() → a set-like object providing a view on D's keys#
most_common(n=None)#

List the n most common elements and their counts from the most common to the least. If n is None, then list all element counts.

>>> Counter('abracadabra').most_common(3)
[('a', 5), ('b', 2), ('r', 2)]
multiplicity(ballot: FrozenBallot) → int#

Method returning the multiplicity of a ballot. Used to ensure that Profile and MultiProfile can be used interchangeably.

Parameters:

ballot (AbstractBallot) – The ballot whose multiplicity is inquired.

Returns:

The multiplicity of the ballots.

Return type:

int

num_ballots() → int#

Returns the number of ballots appearing in the profile. Used to ensure that Profile and MultiProfile can be used interchangeably.

Returns:

The number of voters.

Return type:

int

pop(k[, d]) → v, remove specified key and return the corresponding value.#

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()#

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

score(project: Project) → int | float | mpq#

Returns the score of a project, that is, the sum of scores received from all voters. :param project: The project. :type project: pabutools.election.instance.Project

Return type:

Fraction

setdefault(key, default=None, /)#

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

subtract(iterable=None, /, **kwds)#

Like dict.update() but subtracts counts instead of replacing them. Counts can be reduced below zero. Both the inputs and outputs are allowed to contain zero and negative counts.

Source can be an iterable, a dictionary, or another Counter instance.

>>> c = Counter('which')
>>> c.subtract('witch')             # subtract elements from another iterable
>>> c.subtract(Counter('watch'))    # subtract elements from another counter
>>> c['h']                          # 2 in which, minus 1 in witch, minus 1 in watch
0
>>> c['w']                          # 1 in which, minus 1 in witch, minus 1 in watch
-1
total()#

Sum of the counts

total_score(project: Project) → int | float | mpq#

Returns the total score of a project, that is, the sum of scores received from all voters.

Parameters:

project (Project) – The project.

Returns:

The total score assigned to the project.

Return type:

Numeric

update(iterable=None, /, **kwds)#

Like dict.update() but add counts instead of replacing them.

Source can be an iterable, a dictionary, or another Counter instance.

>>> c = Counter('which')
>>> c.update('witch')           # add elements from another iterable
>>> d = Counter('watch')
>>> c.update(d)                 # add elements from another counter
>>> c['h']                      # four 'h' in which, witch, and watch
4
validate_ballot(ballot: AbstractBallot) → None#

Method validating a ballot before adding it to the profile. Checks if the type of the ballot is a subclass of the attribute ballot_type. Throws a TypeError if not, and returns None otherwise.

Parameters:

ballot (AbstractBallot) – The ballot to be checked.

values() → an object providing a view on D's values#
class AbstractOrdinalProfile(legal_min_length: int | None = None, legal_max_length: int | None = None)[source]#

Bases: AbstractProfile, ABC

Abstract class for ordinal profiles. Stores the metadata and the methods specific to ordinal profiles.

Parameters:

  • legal_min_length (int, optional) – The minimum length of an ordinal ballot per the rules of the election. Defaults to None.

  • legal_max_length (int, optional) – The maximum length of an ordinal ballot per the rules of the election. Defaults to None.

legal_min_length#

The minimum length of an ordinal ballot per the rules of the election.

Type:

int

legal_max_length#

The maximum length of an ordinal ballot per the rules of the election.

Type:

int

class OrdinalProfile(init: Iterable[OrdinalBallot] = (), instance: Instance | None = None, ballot_validation: bool | None = None, ballot_type: type[Ballot] | None = None, legal_min_length: int | None = None, legal_max_length: int | None = None)[source]#

Bases: Profile, AbstractOrdinalProfile

A profile of ordinal ballots, that is, a list of ordinal ballots per voters. See the class OrdinalBallot for more details on ordinal ballots. This class inherits from the Python list class and can thus be used as one.

Parameters:

  • init (Iterable[OrdinalBallot], optional) – An iterable of OrdinalBallot that is used an initializer for the list. If activated, the types of the ballots are validated. In case an AbstractProfile object is passed, the additional attributes are also copied (except if the corresponding keyword arguments have been given).

  • instance (Instance, optional) – The instance related to the profile. Defaults to Instance().

  • ballot_validation (bool, optional) – Boolean indicating whether ballots should be validated before being added to the profile. Defaults to True.

  • ballot_type (type[AbstractBallot], optional) – The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised. Defaults to OrdinalBallot.

  • legal_min_length (int, optional) – The minimum length of an ordinal ballot per the rules of the election. Defaults to None.

  • legal_max_length (int, optional) – The maximum length of an ordinal ballot per the rules of the election. Defaults to None.

instance#

The instance related to the profile.

Type:

Instance

ballot_validation#

Boolean indicating whether ballots should be validated before being added to the profile.

Type:

bool

ballot_type#

The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised.

Type:

type[AbstractBallot]

legal_min_length#

The minimum length of an ordinal ballot per the rules of the election.

Type:

int

legal_max_length#

The maximum length of an ordinal ballot per the rules of the election.

Type:

int

append(item: Ballot) → None#

Append object to the end of the list.

as_multiprofile()[source]#

Converts the profile into a OrdinalMultiProfile.

Returns:

The multiprofile corresponding to the profile.

Return type:

OrdinalMultiProfile

as_sat_profile(sat_class: type[SatisfactionMeasure])#

Converts the profile into a satisfaction profile. See the satisfaction for more details.

Parameters:

sat_class (type[SatisfactionMeasure]) – The class for the representing the satisfaction measure to use.

Returns:

A satisfaction profile, that is, a collection of satisfaction measures for all the voters.

Return type:

py:class:~pabutools.election.satisfaction.satisfactionmeasure.GroupSatisfactionMeasure

clear()#

Remove all items from list.

copy(*args)#

Return a shallow copy of the list.

count(value, /)#

Return number of occurrences of value.

extend(other) → None#

Extend list by appending elements from the iterable.

index(value, start=0, stop=9223372036854775807, /)#

Return first index of value.

Raises ValueError if the value is not present.

insert(index: int, item: Ballot) → None#

Insert object before index.

multiplicity(ballot: Ballot) → int#

Returns 1 regardless of the input (even if the ballot does not appear in the profile, to save up computation).

Parameters:

ballot (AbstractBallot) – The ballot whose multiplicity is inquired.

Returns:

1

Return type:

int

num_ballots() → int#

Returns the number of ballots appearing in the profile. Used to ensure that Profile and MultiProfile can be used interchangeably.

Returns:

The number of voters.

Return type:

int

pop(index=-1, /)#

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)#

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse(*args)#

Reverse IN PLACE.

sort(*, key=None, reverse=False)#

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

validate_ballot(ballot: AbstractBallot) → None#

Method validating a ballot before adding it to the profile. Checks if the type of the ballot is a subclass of the attribute ballot_type. Throws a TypeError if not, and returns None otherwise.

Parameters:

ballot (AbstractBallot) – The ballot to be checked.

class OrdinalMultiProfile(init: Iterable[FrozenOrdinalBallot] = (), instance: Instance | None = None, ballot_validation: bool | None = None, ballot_type: type[FrozenBallot] | None = None, profile: OrdinalProfile | None = None, legal_min_length: int | None = None, legal_max_length: int | None = None)[source]#

Bases: MultiProfile, AbstractOrdinalProfile

A multiprofile of ordinal ballots, that is, a multiset of ordinal ballots together with their multiplicity. Ballots needs to be hashable, so the class FrozenOrdinalBallot should be used by default here. This class inherits from the Python Counter class and can thus be used as one.

Parameters:

  • init (Iterable[FrozenOrdinalBallot], optional) – An iterable of FrozenOrdinalBallot that is used an initializer for the list. If activated, the types of the ballots are validated. In case an AbstractProfile object is passed, the additional attributes are also copied (except if the corresponding keyword arguments have been given).

  • instance (Instance, optional) – The instance related to the profile. Defaults to Instance().

  • ballot_validation (bool, optional) – Boolean indicating whether ballots should be validated before being added to the profile. Defaults to True.

  • ballot_type (type[AbstractBallot], optional) – The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised. Defaults to ForzenOrdinalBallot.

  • profile (OrdinalProfile, optional) – A profile used to initialise the multiprofile. Some metadata are taken from the profile if they are not specified in the constructor.

  • legal_min_length (int, optional) – The minimum length of an ordinal ballot per the rules of the election. Defaults to None.

  • legal_max_length (int, optional) – The maximum length of an ordinal ballot per the rules of the election. Defaults to None.

instance#

The instance related to the profile.

Type:

Instance

ballot_validation#

Boolean indicating whether ballots should be validated before being added to the profile.

Type:

bool

ballot_type#

The type that the ballots are validated against. If ballot_validation is True and a ballot of a type that is not a subclass of ballot_type is added, an exception will be raised.

Type:

type[AbstractBallot]

legal_min_length#

The minimum length of an ordinal ballot per the rules of the election.

Type:

int

legal_max_length#

The maximum length of an ordinal ballot per the rules of the election.

Type:

int

append(ballot: AbstractBallot)#

Appends a ballot to the profile and update the multiplicity if necessary.

Parameters:

ballot (AbstractBallot) – The ballot to append to the profile.

as_sat_profile(sat_class: type[SatisfactionMeasure])#

Converts the profile into a satisfaction profile. See the satisfaction for more details.

Parameters:

sat_class (type[SatisfactionMeasure]) – The class for the representing the satisfaction measure to use.

Returns:

A satisfaction profile, that is, a collection of satisfaction measures for all the voters.

Return type:

py:class:~pabutools.election.satisfaction.satisfactionmeasure.GroupSatisfactionMeasure

clear() → None.  Remove all items from D.#
copy(*args)#

Return a shallow copy.

elements()#

Iterator over elements repeating each as many times as its count.

>>> c = Counter('ABCABC')
>>> sorted(c.elements())
['A', 'A', 'B', 'B', 'C', 'C']

Knuth’s example for prime factors of 1836: 2**2 * 3**3 * 17**1

>>> import math
>>> prime_factors = Counter({2: 2, 3: 3, 17: 1})
>>> math.prod(prime_factors.elements())
1836

Note, if an element’s count has been set to zero or is a negative number, elements() will ignore it.

extend(iterable: Iterable[AbstractBallot], force_freeze=True)#

Extends the profile by appending all the ballots in the iterable.

Parameters:

  • iterable (Iterable[AbstractBallot]) – An iterable of ballots to add to the profile.

  • force_freeze (bool, optional) – Boolean indicating whether subclasses of Ballot should be frozen beforehand. Defaults to True.

classmethod fromkeys(iterable, v=None)#

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)#

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items#
keys() → a set-like object providing a view on D's keys#
most_common(n=None)#

List the n most common elements and their counts from the most common to the least. If n is None, then list all element counts.

>>> Counter('abracadabra').most_common(3)
[('a', 5), ('b', 2), ('r', 2)]
multiplicity(ballot: FrozenBallot) → int#

Method returning the multiplicity of a ballot. Used to ensure that Profile and MultiProfile can be used interchangeably.

Parameters:

ballot (AbstractBallot) – The ballot whose multiplicity is inquired.

Returns:

The multiplicity of the ballots.

Return type:

int

num_ballots() → int#

Returns the number of ballots appearing in the profile. Used to ensure that Profile and MultiProfile can be used interchangeably.

Returns:

The number of voters.

Return type:

int

pop(k[, d]) → v, remove specified key and return the corresponding value.#

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()#

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)#

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

subtract(iterable=None, /, **kwds)#

Like dict.update() but subtracts counts instead of replacing them. Counts can be reduced below zero. Both the inputs and outputs are allowed to contain zero and negative counts.

Source can be an iterable, a dictionary, or another Counter instance.

>>> c = Counter('which')
>>> c.subtract('witch')             # subtract elements from another iterable
>>> c.subtract(Counter('watch'))    # subtract elements from another counter
>>> c['h']                          # 2 in which, minus 1 in witch, minus 1 in watch
0
>>> c['w']                          # 1 in which, minus 1 in witch, minus 1 in watch
-1
total()#

Sum of the counts

update(iterable=None, /, **kwds)#

Like dict.update() but add counts instead of replacing them.

Source can be an iterable, a dictionary, or another Counter instance.

>>> c = Counter('which')
>>> c.update('witch')           # add elements from another iterable
>>> d = Counter('watch')
>>> c.update(d)                 # add elements from another counter
>>> c['h']                      # four 'h' in which, witch, and watch
4
validate_ballot(ballot: AbstractBallot) → None#

Method validating a ballot before adding it to the profile. Checks if the type of the ballot is a subclass of the attribute ballot_type. Throws a TypeError if not, and returns None otherwise.

Parameters:

ballot (AbstractBallot) – The ballot to be checked.

values() → an object providing a view on D's values#
Contents