Utility Profiles

Profiles of voters that assign utilities to a set of candidates. The ballots for a UtilityProfile are in the ballots page.

UtilityProfile Class

class pref_voting.utility_profiles.UtilityProfile(utilities, ucounts=None, domain=None, cmap=None)

An anonymous profile of (truncated) utilities.

Parameters:

• utilities (list[dict[int or str: float]] or list[Utility]) – List of utilities in the profile, where a utility is either a Utility object or a dictionary.

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

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

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

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:

uprof =  UtilityProfile([{"x":1, "y":3, "z":1}, {"x":0, "y":-1, "z":4}, {"x":0.5, "y":-1}, {"x":0, "y":1, "z":2}], ucounts=[2, 3, 1, 1], domain=["x", "y", "z"])

as_dict()

Return a the profile as a dictionary.

avg_utility_function()

Return the average utility function of the profile.

property candidates

Return the candidates in the profile.

cmap

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

display(vmap=None, show_totals=False)

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

domain

The domain of the profile.

classmethod from_json(uprof_json)

Returns a profile of utilities described by uprof_json.

uprof_json must be in the format produced by the pref_voting.UtilityProfile.as_dict() function.

classmethod from_string(uprof_str)

Returns a profile of utilities described by uprof_str.

uprof_str must be in the format produced by the pref_voting.UtilityProfile.write() function.

has_utility(x)

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

normalize_by_range()

Return a profile in which each utility is normalized by range.

normalize_by_standard_score()

Return a profile in which each utility is normalized by standard scores.

num_voters

The number of voters in the profile.

sum_utility_function()

Return the sum utility function of the profile.

to_approval_profile(prob_to_cont_approving=1.0, decay_rate=0.0)

Return a GradeProfile with each utility transformed to an approval ballot.

See pref_voting.Utility.to_approval_ballot() for more details.

to_k_approval_profile(k, prob_to_cont_approving=1.0, decay_rate=0.0)

Return a GradeProfile with each utility transformed to a k-approval ballot.

See pref_voting.Utility.to_approval_ballot() for more details.

to_ranking_profile()

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

util_avg(x)

Return the sum of the utilities of x. If x is not assigned a utility by any voter, return None.

util_max(x)

Return the maximum of the utilities of x. If x is not assigned a utility by any voter, return None.

util_min(x)

Return the minimum of the utilities of x. If x is not assigned a utility by any voter, return None.

util_sum(x)

Return the sum of the utilities of x. If x is not assigned a utility by any voter, return None.

property utilities

Return all of the utilities in the profile.

property utilities_counts

Returns the utilities and the counts of each utility.

write()

Write the profile to a string.

Helper Functions

pref_voting.utility_profiles.write_utility_profiles_to_json(uprofs, filename)

Write a list of utility profiles to a json file.

pref_voting.utility_profiles.read_utility_profiles_from_json(filename)

Read a list of utility profiles to a json file.