Overview

We have three types of collective decision procedures:

1. Voting Method: given edata, outputs a sorted list of candidates, representing tied winners;

2. Probabilistic Voting Method: given edata, outputs a dictionary whose keys are candidates and whose values are probabilities;

3. Social Welfare Function: given edata, outputs a Ranking of the candidates.

We further categorize collective decision procedures based on the input from the voters:

1. Ordinal procedures take as input one or more of the following types of edata: Profile, ProfilesWithTies, MajorityGraph, MarginGraph, and SupportGraph. These procedures are discussed in the following:

   • Positional Scoring Rules

   • Iterative Methods

   • C1 Methods

   • Margin Methods

   • Combined Methods

   • Other Methods

   • Probabilistic Methods

2. Cardinal procedures take as input a UtilityProfile and/or a GradeProfile. These procedures are discussed in the following:

   • Utility Methods

   • Grade Methods

VotingMethod Class and Decorator

class pref_voting.voting_method.VotingMethod(vm, name=None, input_types=None, skip_registration=False, properties_file=None)

A class to add functionality to voting methods.

Parameters:

• vm (function) – An implementation of a voting method. The function should accept a Profile, ProfileWithTies, MajorityGraph, and/or MarginGraph, and a keyword parameter curr_cands to find the winner after restricting to curr_cands.

• name (string) – The Human-readable name of the voting method.

• properties (VotingMethodProperties) – The properties of the voting method.

• input_types (list) – The types of input that the voting method can accept.

add_property(prop, value)

Add a property to the voting method.

check_property(prop, include_counterexample=True)

Check if the voting method satisfies a property.

choose(edata, curr_cands=None)

Return a randomly chosen element from the winning set.

display(edata, curr_cands=None, cmap=None, **kwargs)

Display the winning set of candidates.

get_properties()

Return the properties of the voting method.

get_violation_witness(prop, minimal_resolute=False, minimal=False)

Return the election that witnesses a violation of prop.

has_property(prop)

Check if the voting method has a property.

load_properties(filename=None)

Load the properties of the voting method from a JSON file.

prob(edata, curr_cands=None)

Return a dictionary representing the even-chance tiebreaking for the voting method.

remove_property(prop)

Remove a property from the voting method.

save_properties(filename=None, timeout=10)

Save the properties of the voting method to a JSON file.

set_algorithm(algorithm)

Set the algorithm for the voting method if ‘algorithm’ is an accepted keyword parameter.

Parameters:

algorithm – The algorithm to set for the voting method.

set_name(new_name)

Set the name of the voting method.

pref_voting.voting_method.vm(name=None, input_types=None, skip_registration=False)

A decorator used when creating a voting method.

ProbVotingMethod Function Class and Decorator

class pref_voting.prob_voting_method.ProbVotingMethod(pvm, name=None)

A class to add functionality to probabilistic voting methods

Parameters:

• pvm (function) – An implementation of a probabilistic voting method. The function should accept any type of profile, and a keyword parameter curr_cands to find the winner after restricting to curr_cands.

• name (string) – The human-readable name of the social welfare function.

Returns:

A dictionary that represents the probability on the set of candidates.

choose(edata, curr_cands=None, **kwargs)

Return a randomly chosen element according to the probability.

display(edata, curr_cands=None, cmap=None, **kwargs)

Display the winning set of candidates.

set_name(new_name)

Set the name of the social welfare function.

support(edata, curr_cands=None, **kwargs)

Return the sorted list of the set of candidates that have non-zero probability.

pref_voting.prob_voting_method.pvm(name=None)

A decorator used when creating a social welfare function.

SocialWelfareFunction Class and Decorator

class pref_voting.social_welfare_function.SocialWelfareFunction(swf, name=None)

A class to add functionality to social welfare functions

Parameters:

• swf (function) – An implementation of a voting method. The function should accept any type of profile, and a keyword parameter curr_cands to find the winner after restricting to curr_cands.

• name (string) – The Human-readable name of the social welfare function.

Returns:

A ranking (Ranking) of the candidates.

display(edata, curr_cands=None, **kwargs)

Display the result of the social welfare function.

set_name(new_name)

Set the name of the social welfare function.

winners(edata, curr_cands=None, **kwargs)

Return a sorted list of the first place candidates.

pref_voting.social_welfare_function.swf(name=None)

A decorator used when creating a social welfare function.

Helper Functions: Converting between Voting Methods and Social Welfare Functions

pref_voting.helper.swf_from_vm(vm, tie_breaker=None)

Given a voting method, returns a social welfare function that uses the voting method to rank the candidates (winners are ranked first; then they are excluded from curr_cands and the new winners are ranked second; etc.).

Parameters:

• vm (function) – A voting method.

• tie_breaker (str) – The tie-breaking method to use. Options are “alphabetic”, “random”, and None. Default is None.

Returns:

A social welfare function that uses the voting method to rank the candidates.

Return type:

function

pref_voting.helper.vm_from_swf(swf)

Given a social welfare function, returns a voting method that selects all the candidates ranked first according to the swf.

Parameters:

swf (function) – A social welfare function.

Returns:

A voting method that uses the swf to find the winning set.

Return type:

function