Spatial Profiles

Spatial Profile Class

class pref_voting.spatial_profiles.SpatialProfile(cand_pos, voter_pos, candidate_types=None)[source]

A spatial profile is a set of candidates and voters in a multi-dimensional space. Each voter and candidate is assigned vector of floats representing their position on each issue.

Parameters:

  • cand_pos (dict) – A dictionary mapping each candidate to their position in the space.

  • voter_pos (dict) – A dictionary mapping each voter to their position in the space.

candidates

A list of candidates.

Type:

list

voters

A list of voters.

Type:

list

cand_pos

A dictionary mapping each candidate to their position in the space.

Type:

dict

voter_pos

A dictionary mapping each voter to their position in the space.

Type:

dict

num_dims

The number of dimensions in the space.

Type:

int

cand_types

A dictionary mapping each candidate to their type (e.g., party affiliation).

Type:

dict

candidate_position(c)[source]

Given a candidate c, returns their position in the space.

candidate_type(c)[source]

Given a candidate c, returns their type.

display()[source]

Displays the positions of each candidate and voter in the profile.

classmethod from_string(sp_str)[source]

Returns a spatial profile described by sp_str.

sp_str must be in the format produced by the pref_voting.SpatialProfile.write() function.

set_candidate_types(cand_types)[source]

Sets the types of each candidate.

to_string()[source]

Returns a string representation of the spatial profile.

to_utility_profile(utility_function=None, uncertainty_function=None, batch=False, return_virtual_cand_positions=False)[source]

Returns a utility profile corresponding to the spatial profile.

Parameters:

  • utility_function (callable, optional) – A function that takes two vectors and returns a float. The default utility function is the quadratic utility function.

  • uncertainty_function (callable, optional) – A function that models uncertainty and returns covariance parameters.

  • batch (bool, optional) – If True, generate positions in batches. Default is False.

  • return_virtual_cand_positions (bool, optional) – If True, return virtual candidate positions. Default is False.

Returns:

A utility profile corresponding to the spatial profile. (optional) Tuple[UtilityProfile, dict]: The utility profile and virtual candidate positions if return_virtual_cand_positions is True.

Return type:

UtilityProfile

view(show_labels=False)[source]

Displays the spatial model in a 1D, 2D, or 3D plot.

Parameters:

show_labels (optional, bool) – If True, displays the labels of each candidate and voter. The default is False.

voter_position(v)[source]

Given a voter v, returns their position in the space.

Utility Functions

The utility functions that are used to generate the utility profile from a spatial profile.

pref_voting.utility_functions.linear_utility(v_pos: Array(float32, 1, 'A', False, aligned=True), c_pos: Array(float32, 1, 'A', False, aligned=True))[source]

The utility of the candidate for the voter is negative of the Euclidean distance between the positions.

Parameters:

  • v_pos (numpy array) – The position(s) of the voter.

  • c_pos (numpy array) – The position(s) of the candidate.

Returns:

The utility of the candidate to the voter.

Return type:

float

pref_voting.utility_functions.quadratic_utility(v_pos: Array(float32, 1, 'A', False, aligned=True), c_pos: Array(float32, 1, 'A', False, aligned=True))[source]

The utility of the candidate for the voter is negative of the squared Euclidean distance between the positions.

Parameters:

  • v_pos (numpy array) – The position(s) of the voter.

  • c_pos (numpy array) – The position(s) of the candidate.

Returns:

The utility of the candidate to the voter.

Return type:

float

pref_voting.utility_functions.city_block_utility(v_pos: Array(float32, 1, 'A', False, aligned=True), c_pos: Array(float32, 1, 'A', False, aligned=True))[source]

The utility of the candidate for the voter is the negative of the city-block distance between the positions (also known as the Manhattan distance).

Parameters:

  • v_pos (numpy array) – The position(s) of the voter.

  • c_pos (numpy array) – The position(s) of the candidate.

Returns:

The utility of the candidate to the voter.

Return type:

float

pref_voting.utility_functions.shepsle_utility(v_pos: Array(float32, 1, 'A', False, aligned=True), c_pos: Array(float32, 1, 'A', False, aligned=True))[source]

The Shepsle utility function from “The Strategy of Ambiguity: Uncertainty and Electoral Competition” by Kenneth A. Shepsle, American Political Science Review, 1972, vol. 66, issue 2, pp. 555-568. For a justification of this utility function, see Appendix B from Making Multicandidate Elections More Democratic (https://doi.org/10.1515/9781400859504.114) by S. Merrill III.

Parameters:

  • v_pos (numpy array) – The position(s) of the voter.

  • c_pos (numpy array) – The position(s) of the candidate.

Returns:

The utility of the candidate to the voter.

Return type:

float

pref_voting.utility_functions.matthews_utility(v_pos: Array(float32, 1, 'A', False, aligned=True), c_pos: Array(float32, 1, 'A', False, aligned=True))[source]

Based on the Matthews directional model. See “A Unified Theory of Voting” by S. Merrill III and B. Grofman, pg. 26.

Parameters:

  • v_pos (numpy array) – The position(s) of the voter.

  • c_pos (numpy array) – The position(s) of the candidate.

Returns:

The utility of the candidate to the voter.

Return type:

float

pref_voting.utility_functions.rm_utility(v_pos: Array(float32, 1, 'A', False, aligned=True), c_pos: Array(float32, 1, 'A', False, aligned=True))[source]

Based on the Rabinowitz and Macdonald (1989) pure directional model. See “A Unified Theory of Voting” by S. Merrill III and B. Grofman, pg. 31.

Parameters:

  • v_pos (numpy array) – The position(s) of the voter.

  • c_pos (numpy array) – The position(s) of the candidate.

Returns:

The utility of the candidate to the voter.

Return type:

float

pref_voting.utility_functions.mixed_rm_utility(v_pos: Array(float32, 1, 'A', False, aligned=True), c_pos: Array(float32, 1, 'A', False, aligned=True), beta=0.5)[source]

Based on the Rabinowitz and Macdonald (1989) mixed model described on pages 43-44 of “A Unified Theory of Voting” by S. Merrill III and B. Grofman.

beta = 1 is the proximity quadratic utility function beta = 0 is the RM directional utility function

Parameters:

  • v_pos (numpy array) – The position(s) of the voter.

  • c_pos (numpy array) – The position(s) of the candidate.

  • beta (float) – The beta parameter of the mixed model.

Returns:

The utility of the candidate to the voter.

Return type:

float