app_total_cost += project.cost
for category in project.categories:
app_cost_per_category[category] += project.cost
+ if app_total_cost == 0:
+ raise ValueError(
+ "Category proportionality can only be computed for instances with at least one non-empty ballot."
+ )
for category in categories:
proportional_app_cost_per_category[category] += (
app_cost_per_category[category]
diff --git a/docs/_modules/pabutools/analysis/profileproperties.html b/docs/_modules/pabutools/analysis/profileproperties.html
index ed65058d..7626fe73 100644
--- a/docs/_modules/pabutools/analysis/profileproperties.html
+++ b/docs/_modules/pabutools/analysis/profileproperties.html
@@ -308,6 +308,8 @@ Source code for pabutools.analysis.profileproperties
The median length of the ballots in the profile.
"""
+ if profile.num_ballots() == 0:
+ return 0
ballot_lengths = np.zeros(profile.num_ballots())
index = 0
for ballot in profile:
@@ -356,6 +358,8 @@ Source code for pabutools.analysis.profileproperties
The median cost of the ballots in the profile.
"""
+ if profile.num_ballots() == 0:
+ return 0
ballot_costs = np.zeros(profile.num_ballots())
index = 0
for ballot in profile:
@@ -404,6 +408,8 @@ Source code for pabutools.analysis.profileproperties
The median approval score of projects.
"""
+ if len(instance) == 0:
+ return 0
return float(
np.median([frac(profile.approval_score(project)) for project in instance])
)
@@ -446,6 +452,8 @@ Source code for pabutools.analysis.profileproperties
The median score assigned to a project.
"""
+ if len(instance) == 0:
+ return 0
return float(
np.median([frac(profile.total_score(project)) for project in instance])
)
diff --git a/docs/_modules/pabutools/election/profile/approvalprofile.html b/docs/_modules/pabutools/election/profile/approvalprofile.html
index 55620aab..6aaa388e 100644
--- a/docs/_modules/pabutools/election/profile/approvalprofile.html
+++ b/docs/_modules/pabutools/election/profile/approvalprofile.html
@@ -572,7 +572,7 @@ Source code for pabutools.election.profile.approvalprofile
[docs]def get_all_approval_profiles(
instance: Instance, num_agents: int
-) -> Generator[Iterable[Project]]:
+) -> Generator[ApprovalProfile]:
"""
Returns a generator over all the possible profile for a given instance of a given length.
@@ -588,7 +588,8 @@ Source code for pabutools.election.profile.approvalprofile
Generator[Iterable[:py:class:`~pabutools.election.instance.Project`]]
Generator over subsets of projects.
"""
- return product(powerset(instance), repeat=num_agents)
+ for p in product(powerset(instance), repeat=num_agents):
+ yield ApprovalProfile([ApprovalBallot(b) for b in p], instance=instance)
[docs]class ApprovalMultiProfile(MultiProfile, AbstractApprovalProfile):
diff --git a/docs/_modules/pabutools/election/satisfaction/satisfactionmeasure.html b/docs/_modules/pabutools/election/satisfaction/satisfactionmeasure.html
index 09d272f2..e4090646 100644
--- a/docs/_modules/pabutools/election/satisfaction/satisfactionmeasure.html
+++ b/docs/_modules/pabutools/election/satisfaction/satisfactionmeasure.html
@@ -395,7 +395,30 @@ Source code for pabutools.election.satisfaction.satisfactionmeasure
res = 0
for sat in self:
res += sat.sat(projects) * self.multiplicity(sat)
- return res
+ return res
+
+[docs] @abstractmethod
+ def remove_satisfied(
+ self, sat_bound: dict[AbstractBallot, Number], projects: Iterable[Project]
+ ) -> GroupSatisfactionMeasure:
+ """
+ Returns a new satisfaction profile excluding the satisfaction measurs corresponding to satisfied voters, i.e.,
+ who have met or exceeded their satisfaction bound for a given collection of projects.
+
+ Parameters
+ ----------
+ sat_bound : dict[str, Number]
+ A dictionary of ballot names to numbers, specifying for each ballot the satisfaction bound above which
+ the voter is considered satisfied. Note that the keys are ballot names, and that nothing ensures ballot
+ names to be unique, so be careful here.
+ projects : Iterable[:py:class:`~pabutools.election.instance.Project`]
+ The collection of projects.
+
+ Returns
+ -------
+ :py:class:`~pabutools.election.satisfaction.satisfactionmeasure.GroupSatisfactionMeasure`
+ The new satisfaction profile.
+ """
else:
if sat_profile is None:
sat_profile = profile.as_sat_profile(sat_class=sat_class)
-
return max_additive_utilitarian_welfare_scheme(
instance, sat_profile, budget_allocation, resoluteness=resoluteness
)
"""
The method of equal shares.
"""
+from itertools import chain
from copy import copy, deepcopy
from collections.abc import Iterable
from numbers import Number
@@ -488,8 +489,10 @@ Source code for pabutools.rules.mes
initial_projects.remove(proj)
scores = {proj: sat_profile.total_satisfaction([proj]) for proj in initial_projects}
for proj, score in scores.items():
- if score <= 0 or proj.cost == 0:
+ if proj.cost == 0:
initial_projects.remove(proj)
+ if score > 0:
+ initial_budget_allocation.append(proj)
voters_details = [
MESVoter(sat.ballot, sat, initial_budget, sat_profile.multiplicity(sat))
diff --git a/docs/_sources/usage.rst b/docs/_sources/usage.rst
index a2b6f207..11a8978b 100644
--- a/docs/_sources/usage.rst
+++ b/docs/_sources/usage.rst
@@ -433,14 +433,16 @@ We also offer additive satisfaction functions, where the satisfaction for a set
of projects is equal to the sum of the satisfaction of each individual project. The class
:py:class:`~pabutools.election.satisfaction.additivesatisfaction.AdditiveSatisfaction`
implements such functions. Its constructor takes a function as a parameter that maps
-instance, profile, ballot, and project to a score. As an example, we demonstrate
+instance, profile, ballot, project, and pre-computed values to a score. The pre-computed
+argument is used to pass fixed parameters to the function that can be used
+for expensive computations not to be done more than once. As an example, we demonstrate
how to define the cardinality satisfaction function.
.. code-block:: python
from pabutools.election import AdditiveSatisfaction
- def cardinality_sat_func(instance, profile, ballot, project):
+ def cardinality_sat_func(instance, profile, ballot, project, precomputed_values):
return int(project in ballot)
class Cardinality_Sat(AdditiveSatisfaction):
diff --git a/docs/genindex.html b/docs/genindex.html
index d79514d7..6351b237 100644
--- a/docs/genindex.html
+++ b/docs/genindex.html
@@ -1492,6 +1492,14 @@ R
+ - remove_satisfied() (GroupSatisfactionMeasure method)
+
+
- reverse() (ApprovalProfile method)
diff --git a/docs/objects.inv b/docs/objects.inv
index 851c1f72..0668761a 100644
Binary files a/docs/objects.inv and b/docs/objects.inv differ
diff --git a/docs/reference/election/profile.html b/docs/reference/election/profile.html
index 35373ac9..d2f61fa8 100644
--- a/docs/reference/election/profile.html
+++ b/docs/reference/election/profile.html
@@ -1929,7 +1929,7 @@ Contents
-
-get_all_approval_profiles(instance: Instance, num_agents: int) Generator[Iterable[Project]][source]#
+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:
diff --git a/docs/reference/election/satisfaction.html b/docs/reference/election/satisfaction.html
index 7565ee67..f311a489 100644
--- a/docs/reference/election/satisfaction.html
+++ b/docs/reference/election/satisfaction.html
@@ -311,6 +311,7 @@ Contents
GroupSatisfactionMeasure
Contents
SatisfactionMultiProfile.multiplicity()SatisfactionMultiProfile.pop()SatisfactionMultiProfile.popitem()SatisfactionMultiProfile.remove_satisfied()SatisfactionMultiProfile.setdefault()SatisfactionMultiProfile.subtract()SatisfactionMultiProfile.total() Contents
SatisfactionProfile.multiplicity()SatisfactionProfile.pop()SatisfactionProfile.remove()SatisfactionProfile.remove_satisfied()SatisfactionProfile.reverse()SatisfactionProfile.sort()SatisfactionProfile.total_satisfaction() Contents
+
+-
+abstract remove_satisfied(sat_bound: dict[AbstractBallot, numbers.Number], projects: Iterable[Project]) GroupSatisfactionMeasure[source]#
+Returns a new satisfaction profile excluding the satisfaction measurs corresponding to satisfied voters, i.e.,
+who have met or exceeded their satisfaction bound for a given collection of projects.
+
+- Parameters:
+
+sat_bound (dict[str, Number]) – A dictionary of ballot names to numbers, specifying for each ballot the satisfaction bound above which
+the voter is considered satisfied. Note that the keys are ballot names, and that nothing ensures ballot
+names to be unique, so be careful here.
projects (Iterable[Project]) – The collection of projects.
+- Returns:
+The new satisfaction profile.
+- Return type:
+-
+
+
+
+
-
total_satisfaction(projects: Iterable[Project]) Number[source]#
@@ -848,6 +874,29 @@ Contents
Raises KeyError if the dict is empty.
+
+-
+remove_satisfied(sat_bound: dict[AbstractBallot, numbers.Number], projects: Iterable[Project]) SatisfactionMultiProfile[source]#
+Returns a new satisfaction profile excluding the satisfaction measurs corresponding to satisfied voters, i.e.,
+who have met or exceeded their satisfaction bound for a given collection of projects.
+
+- Parameters:
+
+sat_bound (dict[str, Number]) – A dictionary of ballot names to numbers, specifying for each ballot the satisfaction bound above which
+the voter is considered satisfied. Note that the keys are ballot names, and that nothing ensures ballot
+names to be unique, so be careful here.
projects (Iterable[Project]) – The collection of projects.
+- Returns:
+The new satisfaction profile.
+- Return type:
+-
+
+
+
+
-
setdefault(key, default=None, /)#
@@ -1052,6 +1101,29 @@ Contents
Raises ValueError if the value is not present.
+
+-
+remove_satisfied(sat_bound: dict[str, numbers.Number], projects: Iterable[Project]) SatisfactionProfile[source]#
+Returns a new satisfaction profile excluding the satisfaction measurs corresponding to satisfied voters, i.e.,
+who have met or exceeded their satisfaction bound for a given collection of projects.
+
+- Parameters:
+
+sat_bound (dict[str, Number]) – A dictionary of ballot names to numbers, specifying for each ballot the satisfaction bound above which
+the voter is considered satisfied. Note that the keys are ballot names, and that nothing ensures ballot
+names to be unique, so be careful here.
projects (Iterable[Project]) – The collection of projects.
+- Returns:
+The new satisfaction profile.
+- Return type:
+-
+
+
+
+
-
reverse(*args)#
@@ -2130,6 +2202,7 @@ Contents
GroupSatisfactionMeasure
Contents
SatisfactionMultiProfile.multiplicity()SatisfactionMultiProfile.pop()SatisfactionMultiProfile.popitem()SatisfactionMultiProfile.remove_satisfied()SatisfactionMultiProfile.setdefault()SatisfactionMultiProfile.subtract()SatisfactionMultiProfile.total() Contents
SatisfactionProfile.multiplicity()SatisfactionProfile.pop()SatisfactionProfile.remove()SatisfactionProfile.remove_satisfied()SatisfactionProfile.reverse()SatisfactionProfile.sort()SatisfactionProfile.total_satisfaction()Additive Satisfaction FunctionsAdditiveSatisfaction
implements such functions. Its constructor takes a function as a parameter that maps
-instance, profile, ballot, and project to a score. As an example, we demonstrate
+instance, profile, ballot, project, and pre-computed values to a score. The pre-computed
+argument is used to pass fixed parameters to the function that can be used
+for expensive computations not to be done more than once. As an example, we demonstrate
how to define the cardinality satisfaction function.
from pabutools.election import AdditiveSatisfaction
-def cardinality_sat_func(instance, profile, ballot, project):
+def cardinality_sat_func(instance, profile, ballot, project, precomputed_values):
return int(project in ballot)
class Cardinality_Sat(AdditiveSatisfaction):
diff --git a/pabutools/election/satisfaction/satisfactionprofile.py b/pabutools/election/satisfaction/satisfactionprofile.py
index 6b17c4c2..6bfeb0ae 100644
--- a/pabutools/election/satisfaction/satisfactionprofile.py
+++ b/pabutools/election/satisfaction/satisfactionprofile.py
@@ -118,9 +118,13 @@ def multiplicity(self, sat: SatisfactionMeasure) -> int:
"""
return 1
- def remove_satisfied(self, sat_bound: dict[str, Number],
- projects: Iterable[Project]) -> SatisfactionProfile:
- res = SatisfactionProfile((s for s in self if s.sat(projects) < sat_bound[s.ballot.name]), instance=self.instance)
+ def remove_satisfied(
+ self, sat_bound: dict[str, Number], projects: Iterable[Project]
+ ) -> SatisfactionProfile:
+ res = SatisfactionProfile(
+ (s for s in self if s.sat(projects) < sat_bound[s.ballot.name]),
+ instance=self.instance,
+ )
res.sat_class = self.sat_class
return res
@@ -304,9 +308,17 @@ def extend_from_multiprofile(
def multiplicity(self, sat: SatisfactionMeasure) -> int:
return self[sat]
- def remove_satisfied(self, sat_bound: dict[AbstractBallot, Number],
- projects: Iterable[Project]) -> SatisfactionMultiProfile:
- res = SatisfactionMultiProfile({s: m for s, m in self.items() if s.sat(projects) < sat_bound[s.ballot.name]}, instance=self.instance)
+ def remove_satisfied(
+ self, sat_bound: dict[AbstractBallot, Number], projects: Iterable[Project]
+ ) -> SatisfactionMultiProfile:
+ res = SatisfactionMultiProfile(
+ {
+ s: m
+ for s, m in self.items()
+ if s.sat(projects) < sat_bound[s.ballot.name]
+ },
+ instance=self.instance,
+ )
res.sat_class = self.sat_class
return res