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 by inheriting UtilityProfile (the utility side) and composing a GradeProfile (the grade side). See the module docstring for the design.

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"},
)

as_dict()

Return a dictionary representation of the profile.

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.

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.

remove_candidates(cands_to_ignore)

Return a new profile with the specified candidates removed.

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.

visualize_grades()

Visualize grade distributions as a stacked bar plot.