pref_voting 1.16.31__py3-none-any.whl

pref_voting/generate_spatial_profiles.py

@@ -0,0 +1,198 @@
+import numpy as np
+from pref_voting.spatial_profiles import SpatialProfile
+
+
+def generate_covariance(n_dimensions, std, rho):
+    """
+    Generates a covariance matrix for a multivariate normal distribution with the given standard deviation and correlation coefficient.
+
+    Parameters
+    ----------
+    n_dimensions : int
+        The number of dimensions.
+    std : float
+        The standard deviation.
+    rho : float
+        The correlation coefficient.
+
+    Returns
+    -------
+    cov : numpy.ndarray
+        The covariance matrix for a multivariate normal distribution.
+    """
+    assert std > 0, "Standard deviation must be positive"
+    assert rho >= 0 and rho <= 1, "Correlation coefficient must be between 0 and 1"
+    assert n_dimensions > 0, "Number of dimensions must be positive"
+
+    cov = (std**2) * (np.eye(n_dimensions) + rho * (np.ones((n_dimensions, n_dimensions)) - np.eye(n_dimensions)))
+    
+    return cov
+
+def generate_spatial_profile(num_cands, num_voters, num_dims, cand_cov = None, voter_cov = None, num_profiles = 1): 
+
+    """ 
+    Generates a spatial profile with the candidate and voter positions generated by a multivariate normal distribution with num_dims dimensions and cand_cov the covariance matrix for candidates and voter_cov the covariance matrix for voters.
+
+    Parameters
+    ----------
+    num_cands : int
+        The number of candidates.
+    num_voters : int
+        The number of voters.
+    num_dims : int  
+        The number of dimensions.
+    cand_cov : numpy.ndarray, optional
+        The covariance matrix for the multivariate normal distribution for candidates. The default is None.
+    voter_cov : numpy.ndarray, optional
+        The covariance matrix for the multivariate normal distribution for voters. The default is the identity matrix.
+    
+    Returns
+    -------
+    SpatialProfile  
+        A spatial profile with the candidate and voter positions generated by a multivariate normal distribution with num_dims dimensions and cand_cov the covariance matrix for candidates and voter_cov the covariance matrix for voters.
+
+    """
+    cand_cov = np.eye(num_dims) if cand_cov is None else cand_cov
+    voter_cov = np.eye(num_dims) if voter_cov is None else voter_cov
+
+    assert num_dims == cand_cov.shape[0] == cand_cov.shape[1], "Candidate covariance matrix must be square and have the same number of dimensions as the number of dimensions specified"
+    assert num_dims == voter_cov.shape[0] == voter_cov.shape[1], "Voter covariance matrix must be square and have the same number of dimensions as the number of dimensions specified"
+
+    cand_mean = np.zeros(num_dims)
+    voter_mean = np.zeros(num_dims)
+
+    cand_samples = np.random.multivariate_normal(cand_mean, cand_cov, size=(num_profiles,num_cands))
+    voter_samples = np.random.multivariate_normal(voter_mean, voter_cov, size=(num_profiles,num_voters))
+
+    profs = [SpatialProfile({c: cand_samples[pidx][c] for c in range(num_cands)},
+                            {v: voter_samples[pidx][v] for v in range(num_voters)})
+                          for pidx in range(num_profiles)]
+
+    return profs[0] if num_profiles == 1 else profs
+
+def generate_spatial_profile_polarized(
+    cand_clusters, 
+    voter_clusters, 
+    cluster_types = None, 
+    num_profiles = 1):
+    """
+    Generates a spatial profile with polarized clusters of candidates and voters.   
+    
+    Parameters
+    ----------
+    cand_clusters : list
+        A list of tuples of the form (mean, covariance, number of candidates) for each cluster of candidates.
+    voter_clusters : list
+        A list of tuples of the form (mean, covariance, number of voters) for each cluster of voters.
+    cluster_types : dict, optional
+        A list of the same length as cand_cluster that associates each cluster to the type of candidate. The default is None.
+
+    num_profiles : int, optional
+        The number of profiles to generate. The default is 1.
+
+    Returns
+    -------
+    SpatialProfile
+        A spatial profile with polarized clusters of candidates and voters.
+    """
+
+    cluster_types = cluster_types if cluster_types is not None else list(range(len(cand_clusters)))
+    cand_samples = list()
+    candidate_types = {}
+    total_num_cands = 0
+    for cluster_idx, cand_cluster in enumerate(cand_clusters):
+        cand_mean, cand_cov, num_cands = cand_cluster
+        candidate_types.update({cidx: cluster_types[cluster_idx] for cidx in range(total_num_cands, total_num_cands+num_cands)})
+        total_num_cands += num_cands
+        cluster_samples = np.random.multivariate_normal(cand_mean, cand_cov, 
+                                                        size=(num_profiles,num_cands))
+        if len(cand_samples) == 0:
+            cand_samples = cluster_samples
+        else:
+            cand_samples = np.concatenate([cand_samples, cluster_samples], axis=1)
+
+    voter_samples = list()
+    total_num_voters = 0
+    for voter_cluster in voter_clusters:
+        voter_mean, voter_cov, num_voters = voter_cluster
+        total_num_voters += num_voters
+        cluster_samples = np.random.multivariate_normal(voter_mean, voter_cov, 
+                                                        size=(num_profiles,num_voters))
+        if len(voter_samples) == 0:
+            voter_samples = cluster_samples
+        else:
+            voter_samples = np.concatenate([voter_samples, cluster_samples], axis=1) 
+
+    
+    profs = [SpatialProfile({cidx: cand_samples[pidx][cidx]
+                           for cidx in range(total_num_cands)},
+                           {vidx: voter_samples[pidx][vidx]
+                            for vidx in range(total_num_voters)}, 
+                            candidate_types=candidate_types) 
+                            for pidx in range(num_profiles)]
+    
+    return profs[0] if num_profiles == 1 else profs
+
+
+def generate_spatial_profile_polarized_cands_randomly_polarized_voters(
+        cand_clusters, 
+        num_voters,
+        voter_distributions,
+        cluster_types = None, 
+        num_profiles = 1):
+    """
+    Generates a spatial profile with polarized clusters of candidates and voters.   
+    
+    Parameters
+    ----------
+    cand_clusters : list
+        A list of tuples of the form (mean, covariance, number of candidates) for each cluster of candidates.
+    num_voters : int
+        The number of voters.
+    voter_distributions : list
+        A list of tuples of the form (mean, covariance, prob) for each distribution of voters, where prob is the probability that a voter is assigned to this cluster.
+    cluster_types : dict, optional
+        A list of the same length as cand_cluster that associates each cluster to the type of candidate. The default is None.
+    num_profiles : int, optional
+        The number of profiles to generate. The default is 1.
+
+    Returns
+    -------
+    SpatialProfile
+        A spatial profile with polarized clusters of candidates and voters.
+    """
+
+    cluster_types = cluster_types if cluster_types is not None else list(range(len(cand_clusters)))
+    cand_samples = list()
+    candidate_types = {}
+    total_num_cands = 0
+    for cluster_idx, cand_cluster in enumerate(cand_clusters):
+        cand_mean, cand_cov, num_cands = cand_cluster
+        candidate_types.update({cidx: cluster_types[cluster_idx] for cidx in range(total_num_cands, total_num_cands+num_cands)})
+        total_num_cands += num_cands
+        cluster_samples = np.random.multivariate_normal(cand_mean, cand_cov, size=(num_profiles,num_cands))
+        if len(cand_samples) == 0:
+            cand_samples = cluster_samples
+        else:
+            cand_samples = np.concatenate([cand_samples, cluster_samples], axis=1)
+
+    all_potential_voters = list()
+    voter_cluster_probs = list()
+    for voter_distribution in voter_distributions:
+        voter_mean, voter_cov, prob = voter_distribution
+        all_potential_voters.append(np.random.multivariate_normal(voter_mean, voter_cov, size=(num_profiles, num_voters)))
+        voter_cluster_probs.append(prob)
+
+    # for each profile, randomly assign voters to clusters
+
+    #voters = range(num_voters)
+
+    voters_clusters_assignment = np.random.choice(len(all_potential_voters), size=(num_profiles, num_voters), p = voter_cluster_probs)
+    profs = [SpatialProfile({cidx: cand_samples[pidx][cidx]
+                           for cidx in range(total_num_cands)},
+                           {vidx: all_potential_voters[voters_clusters_assignment[pidx][vidx]][pidx][vidx]
+                            for vidx in range(num_voters)}, 
+                            candidate_types=candidate_types) 
+                            for pidx in range(num_profiles)]
+    
+    return profs[0] if num_profiles == 1 else profs

pref_voting/generate_utility_profiles.py

@@ -0,0 +1,160 @@
+
+'''
+    File: generate_utility_profiles.py
+    Author: Wes Holliday (wesholliday@berkeley.edu) and Eric Pacuit (epacuit@umd.edu)
+    Date: May 26, 2023
+    
+    Functions to generate utility profiles.
+'''
+
+
+from math import ceil
+import numpy as np
+from scipy.spatial import distance
+from functools import partial
+
+from pref_voting.utility_profiles import UtilityProfile
+from pref_voting.utility_functions import *
+
+# turn off future warnings.
+# getting the following warning when calling tabulate to display a profile: 
+# /Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8/site-packages/tabulate.py:1027: FutureWarning: elementwise comparison failed; returning scalar instead, but in the future will perform elementwise comparison
+#  if headers == "keys" and not rows:
+# see https://stackoverflow.com/questions/40659212/futurewarning-elementwise-comparison-failed-returning-scalar-but-in-the-futur
+#
+import warnings
+warnings.simplefilter(action='ignore', category=FutureWarning)
+
+
+def generate_utility_profile_uniform(num_candidates, num_voters, num_profiles = 1):
+    """
+    Generate a utility profile where each voter assigns a random number between 0 and 1 to each candidate.
+
+    Args:   
+        num_candidates (int): The number of candidates.
+        num_voters (int): The number of voters.
+    
+    Returns:
+        UtilityProfile: A utility profile.
+
+    """
+
+    cand_utils = np.random.uniform(size=(num_profiles, num_voters, num_candidates))
+
+    uprofs = [UtilityProfile([{c: cand_utils[pidx][v][c] 
+                               for c in range(num_candidates)} 
+                               for v in range(num_voters)]) 
+                               for pidx in range(num_profiles)]
+    
+    return uprofs if num_profiles > 1 else uprofs[0]
+
+def generate_utility_profile_normal(num_candidates, num_voters, std = 0.1, normalize = None, num_profiles = 1):
+    """
+    Generate a utility profile where each voter assigns a random number drawn from a normal distribution with a randomly chosen mean (between 0 and 1) with standard deviation ``std`` to each candidate.   
+    
+    Args:
+        num_candidates (int): The number of candidates.
+        num_voters (int): The number of voters. 
+        std (float): The standard deviation of the normal distribution. The default is 0.1.
+        normalize (str): The normalization method to use. The default is None.
+    
+    Returns:
+        UtilityProfile: A utility profile.
+    """
+    
+    mean_utilities = {c: np.random.uniform(0, 1) for c in range(num_candidates)}
+    cand_utils = {c: np.random.normal(mean_utilities[c], std, size=(num_profiles, num_voters)) for c in range(num_candidates)}
+    
+    if normalize == "range": 
+        uprofs = [UtilityProfile([{c: cand_utils[c][pidx][vidx] 
+                                   for c in range(num_candidates)} 
+                                   for vidx in range(num_voters)]).normalize_by_range() 
+                                   for pidx in range(num_profiles)]
+    elif normalize == "score":
+        uprofs = [UtilityProfile([{c: cand_utils[c][pidx][vidx] 
+                                   for c in range(num_candidates)} 
+                                   for vidx in range(num_voters)]).normalize_by_standard_score() 
+                                   for pidx in range(num_profiles)]
+    else: # do not normalize
+        uprofs = [UtilityProfile([{c: cand_utils[c][pidx][vidx] 
+                                   for c in range(num_candidates)} 
+                                   for vidx in range(num_voters)]) 
+                                   for pidx in range(num_profiles)]
+
+
+    return uprofs if num_profiles > 1 else uprofs[0]
+utility_functions = {
+    "RM": {
+        "func": mixed_rm_utility,
+        "param": 1
+    },
+    "Linear": {
+        "func": linear_utility,
+        "param": None
+    },
+    "Quadratic": 
+    {   
+        "func": quadratic_utility,
+        "param": None
+    },
+    "Shepsle": {
+        "func": shepsle_utility,
+        "param": None
+    },
+    "City Block": { 
+        "func": city_block_utility,
+        "param": None
+    },
+    "Matthews": { 
+        "func": matthews_utility,
+        "param": None
+    }
+
+}
+def generate_spatial_utility_profile(num_cands, 
+                                     num_voters, 
+                                     num_dims = 2, 
+                                     utility_function = "Quadratic", 
+                                     utility_function_param = None):
+    
+    """
+    Create a spatial utility profile using specified utility functions. 
+
+
+    Args:
+        num_cands (int): The number of candidates.
+        num_voters (int): The number of voters.
+        num_dims (int): The number of dimensions. The default is 2.
+        utility_function (str): The utility function to use. The default is "Linear".
+        utility_function_param (float): The parameter of the utility function. The default is None.
+        
+    Returns:
+        UtilityProfile: A spatial utility profile.
+    """
+
+    # the first component of the parameter is the number of dimensions, 
+    # the second component is used to define the mixed model: 
+    # beta = 1 is proximity model (i.e., squared Euclidean distance)
+
+    mean = [0] * num_dims  # mean is 0 for each dimension
+    cov = np.diag([1] * num_dims)  # diagonal covariance
+
+    _utility_fnc = utility_functions[utility_function]["func"]
+
+    if utility_functions[utility_function]["param"] is not None or utility_function_param is not None: 
+        util_parm = utility_function_param  if utility_function_param is not None else utility_functions[utility_function]["param"]
+        utility_fnc = partial(_utility_fnc, util_parm)
+
+    else: 
+        utility_fnc = _utility_fnc
+
+    # sample candidate/voter positions using a multivariate normal distribution
+    cand_positions = np.random.multivariate_normal(np.array(mean), cov, num_cands)
+    voter_positions = np.random.multivariate_normal(np.array(mean), cov, num_voters)
+
+    utilities = [{c: utility_fnc(v_pos, c_pos)  for c, c_pos in enumerate(cand_positions)} 
+                 for _, v_pos in enumerate(voter_positions)]
+
+    return UtilityProfile(utilities)
+
+