Pref Grade Profiles

Profiles of voters that each submit both a (truncated) strict weak order and an assignment of grades from a fixed set to each candidate. The ballots for a PrefGradeProfile are Rankings and Grades.

PrefGradeProfile Class

class pref_voting.pref_grade_profile.PrefGradeProfile(rankings, grade_maps, grades, rcounts=None, candidates=None, cmap=None, gmap=None, grade_order=None)

An anonymous profile in which each voter submits both a (truncated) strict weak order and an assignment of grades.

Parameters:

• rankings (list[dict[int or str: int]] or list[Ranking]) – List of rankings in the profile, where a ranking is either a Ranking object or a dictionary.

• 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[int or str]) – List of grades.

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

• candidates (list[int] or list[str], optional) – List of candidates in the profile. If not provided, this is the union of candidates appearing in the rankings and grade maps.

• 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 (dict[int or str: str], optional) – Dictionary mapping grades to grade names (strings). If not provided, each grade is mapped to itself.

• grade_order (list[int or str], optional) – 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 submit the ranking 0 first, 1 second, 2 third along with grades {0: 5, 1: 3, 2: 1}; and 3 voters submit the ranking with 1 and 2 tied for first and 0 second along with grades {0: 2, 1: 4, 2: 4}:

pgprof = PrefGradeProfile(
    [{0: 1, 1: 2, 2: 3}, {1: 1, 2: 1, 0: 2}],
    [{0: 5, 1: 3, 2: 1}, {0: 2, 1: 4, 2: 4}],
    [1, 2, 3, 4, 5],
    rcounts=[2, 3],
)

pgprof.display()

anonymize()

Return a profile which is the anonymized version of this profile.

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.

cindex_to_cand

Maps candidates to their index in the list of candidates and vice versa.

cmap

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

condorcet_loser(curr_cands=None)

Returns the Condorcet loser in the profile restricted to curr_cands if one exists, otherwise return None.

A candidate \(c\) is a Condorcet loser if every other candidate is majority preferred to \(c\).

condorcet_winner(curr_cands=None)

Returns the Condorcet winner in the profile restricted to curr_cands if one exists, otherwise return None.

The Condorcet winner is the candidate that is majority preferred to every other candidate.

copeland_scores(curr_cands=None, scores=(1, 0, -1))

The Copeland scores in the profile restricted to the candidates in curr_cands.

The Copeland score for candidate \(c\) is calculated as follows: \(c\) receives scores[0] points for every candidate that \(c\) is majority preferred to, scores[1] points for every candidate that is tied with \(c\), and scores[2] points for every candidate that is majority preferred to \(c\). The default scores is (1, 0, -1).

Parameters:

• curr_cands (list[int], optional) – restrict attention to candidates in this list. Defaults to all candidates in the profile if not provided.

• scores (tuple[int], optional) – the scores used to calculate the Copeland score of a candidate \(c\): scores[0] is for the candidates that \(c\) is majority preferred to; scores[1] is the number of candidates tied with \(c\); and scores[2] is the number of candidate majority preferred to \(c\). The default value is scores = (1, 0, -1)

Returns:

a dictionary associating each candidate in curr_cands with its Copeland score.

cycles()

Return a list of the cycles in the profile.

description()

Return the Python code needed to create the profile.

display(cmap=None, style='pretty', curr_cands=None, show_grades=True, show_totals=False)

Display the profile as an ascii table (using tabulate).

The rankings are displayed as in ProfileWithTies. If show_grades is True, the grade assignment for each voter type is also displayed below the ranking table.

Parameters:

• cmap (dict[int,str], optional) – the candidate map (overrides the cmap associated with this profile)

• style (str, optional) – the table style for tabulate (default "pretty")

• curr_cands (list[int], optional) – list of candidates to display

• show_grades (bool, optional) – whether to also display the grade assignments (default True)

• show_totals (bool, optional) – whether to display grade totals (sum, median) when showing grades (default False)

Return type:

None

display_margin_graph(cmap=None, curr_cands=None)

Display the margin graph of the profile (restricted to curr_cands) using the cmap. See MarginGraph.

display_rankings()

Display a list of the rankings in the profile.

display_support_graph(cmap=None, curr_cands=None)

Display the support graph of the profile (restricted to curr_cands) using the cmap. See SupportGraph.

dominates(cand, curr_cands=None)

Returns the list of candidates that cand is majority preferred to in the majority graph restricted to curr_cands.

dominators(cand, curr_cands=None)

Returns the list of candidates that are majority preferred to cand in the profile restricted to the candidates in curr_cands.

gmap

The grade map is a dictionary associating a grade with the name used when displaying a grade.

property grade_functions

Return all of the grade functions in the profile.

grade_margin(c1, c2, use_extended=False)

Return the grade-based margin of c1 over c2.

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 grades and the counts of each grade.

has_grade(c)

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

is_tied(c1, c2)

Returns True if c1 and c2 are tied (i.e., the margin of c1 over c2 is 0).

property is_truncated_linear

Return True if the profile only contains (truncated) linear orders.

is_uniquely_weighted()

Returns True if the profile is uniquely weighted.

A profile is uniquely weighted when there are no 0 margins and all the margins between any two candidates are unique.

majority_graph()

Returns the majority graph of the profile. See MajorityGraph.

majority_prefers(c1, c2)

Returns True if c1 is majority preferred to c2.

margin(c1, c2)

Returns the margin of candidate c1 over candidate c2, where the margin is the number of voters that rank c1 strictly above c2 minus the number of voters that rank c2 strictly above c1.

margin_graph()

Returns the margin graph of the profile. See MarginGraph.

property margin_matrix

Returns the margin matrix of the profile, where the entry at row i and column j is the margin of candidate i over candidate j.

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_bullet_votes()

Return the number of bullet votes in the profile.

num_cands

The number of candidates in the profile.

num_empty_rankings()

Return the number of empty rankings in the profile.

num_linear_orders()

Return the number of linear orders in the profile.

num_ranked_all_candidates()

Return the number of rankings that rank all candidates in the profile.

num_ranking_each_candidate()

Return a dictionary mapping each candidate to the number of voters that rank the candidate.

num_rankings_with_ties()

Return the number of rankings with ties in the profile.

num_truncated_linear_orders()

Return the number of truncated linear orders in the profile.

num_voters

The number of voters in the profile.

plurality_scores(curr_cands=None)

Return the Plurality Scores of the candidates, assuming that each voter ranks a single candidate in first place.

plurality_scores_ignoring_overvotes(curr_cands=None)

Return the Plurality scores ignoring empty rankings and overvotes.

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.

property ranking_types

Return a list of the types of rankings in the profile.

property rankings

Return a list of all individual rankings in the profile.

property rankings_as_dicts_counts

Returns the rankings represented as dictionaries and the counts of each ranking.

property rankings_as_indifference_list

Return a list of all individual rankings as indifference lists in the profile.

property rankings_counts

Returns the rankings and the counts of each ranking.

ranks

The ranks that are possible in the profile.

ratio(c1, c2)

Returns the ratio of the support of c1 over c2 to the support c2 over c1.

remove_candidates(cands_to_ignore)

Remove all candidates from cands_to_ignore from the profile.

Parameters:

cands_to_ignore (list[int]) – list of candidates to remove from the profile

Returns:

a profile with candidates from cands_to_ignore removed.

remove_empty_rankings()

Remove the empty rankings from the profile.

report()

Display a report of the types of rankings in the profile.

strength_matrix(curr_cands=None, strength_function=None)

Return the strength matrix of the profile. The strength matrix is a matrix where the entry in row \(i\) and column \(j\) is the number of voters that rank the candidate with index \(i\) over the candidate with index \(j\). If curr_cands is provided, then the strength matrix is restricted to the candidates in curr_cands. If strength_function is provided, then the strength matrix is computed using the strength function.

strict_maj_size()

Returns the strict majority of the number of voters.

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.

support(c1, c2)

Returns the support of candidate c1 over candidate c2, where the support is the number of voters that rank c1 strictly above c2.

support_graph()

Returns the support graph of the profile. See SupportGraph.

to_grade_profile()

Return a GradeProfile corresponding to the grade data in this profile.

to_ranking_profile()

Return a ProfileWithTies corresponding to the ranking data in this profile.

tops_scores(curr_cands=None, score_type='approval')

Return the tops scores of the candidates.

use_extended_strict_preference()

Redefine the supports so that extended strict preferences are used. Using extended strict preference may change the margins between candidates.

use_strict_preference()

Redefine the supports so that strict preferences are used. Using strict preference may change the margins between candidates.

using_extended_strict_preference

A flag indicating whether the profile is using extended strict preferences when calculating supports, margins, etc.

visualize_grades()

Visualize the grade assignments as a stacked bar plot.

weak_condorcet_winner(curr_cands=None)

Returns a list of the weak Condorcet winners in the profile restricted to curr_cands (which may be empty).

A candidate \(c\) is a weak Condorcet winner if there is no other candidate that is majority preferred to \(c\).

Note

While the Condorcet winner is unique if it exists, there may be multiple weak Condorcet winners.