Grade Profiles

Profiles of voters that assign grades from a fixed set to each candidate. The ballots for a GradeProfile are in the ballots page.

GradeProfile Class

class pref_voting.grade_profiles.GradeProfile(grade_maps, grades, gcounts=None, candidates=None, cmap=None, gmap=None, grade_order=None)

An anonymous profile of (truncated) grades.

Parameters:

• grade_maps (list[dict[int or str: int or str]] or list[Grade]) – List of grades in the profile, where a grade is either a Grade object or a dictionary.

• grades – List of grades.

• gcounts (list[int], optional) – List of the number of voters associated with each grade. Should be the same length as grade_maps. If not provided, it is assumed that 1 voter submitted each element of grade_maps.

• candidates (list[int] or list[str], optional) – List of candidates in the profile. If not provided, it is the candidates that are assigned a grade by least on voter.

• cmap (dict[int or str: str], optional) – Dictionary mapping candidates to candidate names (strings). If not provided, each candidate name is mapped to itself.

• gmap (list[int or str], optional) – Dictionary mapping grades to grade names (strings). If not provided, each grade is mapped to itself.

• grade_order – A list of the grades representing the order of the grades. It is assumed the grades are listed from largest to smallest. If not provided, the grades are assumed to be numbers and compared using the greater-than relation.

Example:

The following code creates a profile in which 2 voters submitted the ranking 0 ranked first, 1 ranked second, and 2 ranked third; 3 voters submitted the ranking 1 and 2 are tied for first place and 0 is ranked second; and 1 voter submitted the ranking in which 2 is ranked first and 0 is ranked second:

gprof =  GradeProfile([{"x":1, "y":3, "z":1}, {"x":0, "y":-1, "z":3}, {"x":0, "y":-1}, {"x":0, "y":1, "z":2}], [-1, 0, 1, 2, 3], gcounts=[2, 3, 1, 1], candidates=["x", "y", "z"])

gprof.display()

approval_scores()

Return a dictionary representing the approval scores of the candidates in the profile.

avg(c)

Return the average of the grades of c. If c is not assigned a grade by any voter, return None.

avg_grade_function()

Return the average grade function of the profile.

candidates

The domain of the profile.

cmap

The candidate map is a dictionary associating an alternative with the name used when displaying a alternative.

display(show_totals=False, average_median_ties=False)

Display a grade profile as an ascii table (using tabulate). If show_totals is true then the sum, min, and max of the grades are displayed.

classmethod from_string(gprof_str)

Returns a profile of utilities described by gprof_str.

gprof_str must be in the format produced by the pref_voting.GradeProfile.write() function.

gmap

The candidate map is a dictionary associating an alternative with the name used when displaying a alternative.

property grade_functions

Return all of the grade functions in the profile.

grade_order

The order of the grades. If None, then order from largest to smallest

grades

The grades in the profile.

property grades_counts

Returns the grade and the counts of each grade.

has_grade(c)

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

margin(c1, c2, use_extended=False)

Return the margin of c1 over c2. If c1 is not assigned a grade by any voter, return None.

max(c)

Return the maximum of the grade of c. If c is not assigned a grade by any voter, return None.

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

Return the median of the grades of c. If c is not assigned a grade by any voter, return None.

min(c)

Return the minimum of the grades of c. If c is not assigned a grade by any voter, return None.

num_voters

The number of voters in the profile.

proportion(cand, grade)

Return the proportion of voters that assign cand the grade grade.

Note that grade could be None, in which case the proportion of voters that do not assign cand a grade is returned.

proportion_with_grade(cand, grade)

Return the proportion of voters that assign a grade to cand .

proportion_with_higher_grade(cand, grade)

Return the proportion of voters that assign a strictly higher grade to cand than grade.

proportion_with_lower_grade(cand, grade)

Return the proportion of voters that assign a strictly lower grade to cand than grade.

sum(c)

Return the sum of the grades of c. If c is not assigned a grade by any voter, return None.

sum_grade_function()

Return the sum grade function of the profile.

to_ranking_profile()

Return a ranking profile (a :class:ProfileWithTies) corresponding to the profile.

visualize()

Visualize a grade profile as a stacked bar plot.

write()

Write the profile to a string.