Util Grade Profiles

Profiles of voters that each submit both a utility function over candidates and an assignment of grades from a fixed set to each candidate. The ballots for a UtilGradeProfile are Utilities and Grades.

UtilGradeProfile Class

class pref_voting.util_grade_profile.UtilGradeProfile(utilities, grade_maps, grades, ucounts=None, candidates=None, cmap=None, gmap=None, grade_order=None)

An anonymous profile of utilities and grades.

Each voter submits both a utility function over candidates and a grade assignment (e.g., approval/disapproval). This class packages both into a single object, combining the functionality of UtilityProfile and GradeProfile.

Parameters:

• utilities (list[dict] or list[Utility]) – List of utility dicts or Utility objects.

• grade_maps (list[dict] or list[Grade]) – List of grade dicts or Grade objects.

• grades (list) – List of possible grades.

• ucounts (list[int], optional) – List of the number of voters associated with each utility/grade pair. If not provided, 1 per entry.

• candidates (list, optional) – List of candidates. If not provided, discovered from the utilities and grade maps.

• cmap (dict, optional) – Dictionary mapping candidates to display names.

• gmap (dict, optional) – Dictionary mapping grades to display names.

• grade_order (list, optional) – Grades listed from largest to smallest. If not provided, grades are sorted in descending numeric order.

Example:

ugprof = UtilGradeProfile(
    [{"x": 5, "y": 3, "z": 1}, {"x": 2, "y": 4, "z": 4}],
    [{"x": 1, "y": 0, "z": 0}, {"x": 0, "y": 1, "z": 1}],
    [0, 1],
    candidates=["x", "y", "z"],
    gmap={0: "Not Approved", 1: "Approved"},
)

approval_scores()

Return approval scores (requires grades [0, 1]).

as_dict()

Return a dictionary representation of the profile.

avg(c)

Return the average grade for c, or None if ungraded.

avg_grade_function()

Return the average grade function.

avg_utility_function()

Return the average utility function.

candidates

Sorted list of candidates.

cmap

Candidate display-name mapping.

description()

Return Python code that recreates this profile.

display(cmap=None, show_totals=False)

Display the profile as an ASCII table showing utilities and grades.

gmap

Grade display-name mapping.

property grade_functions

Return the expanded list of grade functions (one per voter).

grade_margin(c1, c2, use_extended=False)

Return the grade-based margin of c1 over c2.

grade_order

Grade ordering (largest to smallest).

grades

List of possible grades.

property grades_counts

Return (grades_list, ucounts).

has_grade(c)

Return True if c is assigned a grade by at least one voter.

has_utility(x)

Return True if x is assigned a utility by at least one voter.

max(c)

Return the maximum grade for c, or None if ungraded.

median(c, use_lower=True, use_average=False)

Return the median grade for c, or None if ungraded.

min(c)

Return the minimum grade for c, or None if ungraded.

normalize_by_range()

Return a new profile with each utility normalized by range.

normalize_by_standard_score()

Return a new profile with each utility normalized by standard score.

num_cands

Number of candidates.

num_voters

Total number of voters.

proportion(cand, grade)

Return the proportion of voters assigning grade to cand.

proportion_with_grade(cand, grade)

Proportion of voters assigning exactly grade to cand.

proportion_with_higher_grade(cand, grade)

Proportion of voters assigning strictly higher grade to cand.

proportion_with_lower_grade(cand, grade)

Proportion of voters assigning strictly lower grade to cand.

remove_candidates(cands_to_ignore)

Return a new profile with the specified candidates removed.

sum(c)

Return the sum of grades for c, or None if ungraded.

sum_grade_function()

Return the sum grade function.

sum_utility_function()

Return the sum utility function.

to_grade_profile()

Return a GradeProfile with just the grade data.

to_pref_grade_profile()

Return a PrefGradeProfile with rankings derived from utilities.

to_ranking_profile()

Return a ProfileWithTies with rankings derived from utilities.

to_utility_profile()

Return a UtilityProfile with just the utility data.

util_avg(x)

Return the average utility of x, or None if unrated.

util_max(x)

Return the maximum utility of x, or None if unrated.

util_min(x)

Return the minimum utility of x, or None if unrated.

util_sum(x)

Return the sum of utilities of x, or None if unrated.

property utilities

Return the expanded list of utility functions (one per voter).

property utilities_counts

Return (utilities_list, ucounts).

visualize_grades()

Visualize grade distributions as a stacked bar plot.