abcvoting.generate
Random generation of approval profiles.
This module is based on the paper on the package prefsampling.
- class abcvoting.generate.PointProbabilityDistribution(name, center_point=0.5, sigma=0.15, width=1.0)
Class for specifying a probability distribution generating points.
- Parameters:
- namestr
Name (identifier) of the probability distribution. See example below.
- center_pointtuple or float, optional
Center point of the distribution.
This can be either a point (tuple) or a float. If it is a float, it is assumed that the point has this value in all coordinates.
- sigmafloat, optional
Standard deviation (only required for Gaussian distributions).
- widthfloat
Width of the geometric shape that constrains the probability distribution.
This parameter is used for “1d_interval”, “2d_square”, “2d_disc”, and “2d_gaussian_disc”.
Examples
Here is a visual representation of the different probability distributions available.
# distributions to generate points in 1- and 2-dimensional space distributions = [ PointProbabilityDistribution("1d_interval", center_point=[0]), PointProbabilityDistribution("1d_gaussian", center_point=[4]), PointProbabilityDistribution("1d_gaussian_interval", center_point=[6], width=0.5), PointProbabilityDistribution("2d_square", center_point=[0, 2]), PointProbabilityDistribution("2d_disc", center_point=[2, 2]), PointProbabilityDistribution("2d_gaussian", center_point=[4, 2], sigma=0.25), PointProbabilityDistribution("2d_gaussian_disc", center_point=[6, 2], sigma=0.25), ]
Expand for references to
abcvoting.generate.PointProbabilityDistribution
- prefsampling_function()
- abcvoting.generate.prefsampling_euclidean_wrapper(num_voters, num_cand, voter_prob_distribution, candidate_prob_distribution, voter_points, candidate_points, return_points, sampler, sampler_params)
Wrapper for prefsampling functions.
Maps the outcome of the samplers to an abcvoting profile. This is specific to the Euclidean samplers.
- Parameters:
- num_votersint
The desired number of voters in the profile.
- num_candint
The desired number of candidates in the profile.
- voter_prob_distributionPointProbabilityDistribution or None
A probability distribution used to generate voter points.
- candidate_prob_distributionPointProbabilityDistribution or None
A probability distribution used to generate candidate points.
- voter_pointsiterable
A list of points.
The length of this list must be num_voters. The dimension of the points must be the same as the points in candiddate_points or as specified by candidate_prob_distribution. This parameter is only used if voter_prob_distribution is None.
- candidate_pointsiterable
A list of points.
The length of this list must be num_cand. The dimension of the points must be the same as the points in voter_points or as specified by voter_prob_distribution. This parameter is only used if candidate_prob_distribution is None.
- return_pointsbool, optional
If true, also return the list of voter points and a list of candidate points.
- samplerCallable
The prefsampling function.
- sampler_paramsdict
The arguments passed to the sampler, all arguments are passed as kwargs.
- Returns:
- abcvoting.preferences.Profile | tuple[abcvoting.preferences.Profile,np.ndarray,np.ndarray]
- abcvoting.generate.prefsampling_wrapper(sampler, sampler_params)
Wrapper for prefsampling functions to map the outcome of the samplers to an abcvoting profile.
- Parameters:
- samplerCallable
The prefsampling function.
- sampler_paramsdict
The arguments passed to the sampler, all are passed as kwargs.
- Returns:
- abcvoting.preferences.Profile
- abcvoting.generate.random_disjoint_resampling_profile(num_voters, num_cand, p, phi=None, num_groups=2)
Generate a random profile using the (p,phi,g)-Disjoint Resampling probability distribution.
- Parameters:
- num_votersint
The desired number of voters in the profile.
- num_candint
The desired number of candidates in the profile.
- pfloat in [0, 1]
Probability of approving a candidate in case that the model resamples.
- phifloat in [0, 1]
Probability to resample an approval.
For each generated vote, we go through all candidates. For each candidate, we copy the approval of the central ballot with probability 1 - phi. Otherwise, with probability phi, we resample the approval of the candidate (so that the generated vote approves that candidate with probability p).
- num_groupsint, optional
Corresponds to the parameter g in (p,phi,g)-Disjoint Resampling.
The model randomly partitions the candidates into num_groups groups. To generate a vote, the model first randomly selects a group. Then, it samples a vote from a (p,phi)-resampling model, where the central ballot approves exactly all candidates in the selected group. Thus, the parameter p is not used to obtain the central ballot, but is used in case of resampling.
- Returns:
- abcvoting.preferences.Profile
References
How to Sample Approval Elections? Stanisław Szufa, Piotr Faliszewski, Łukasz Janeczko, Martin Lackner, Arkadii Slinko, Krzysztof Sornat, Nimrod Talmon. https://arxiv.org/abs/2207.01140
- abcvoting.generate.random_euclidean_fixed_size_profile(num_voters, num_cand, voter_prob_distribution, candidate_prob_distribution, setsize, voter_points=None, candidate_points=None, return_points=False)
Generate a random profile using the Euclidean with fixed-size approval sets distribution.
- Parameters:
- num_votersint
The desired number of voters in the profile.
- num_candint
The desired number of candidates in the profile.
- voter_prob_distributionPointProbabilityDistribution or None
A probability distribution used to generate voter points.
- candidate_prob_distributionPointProbabilityDistribution or None
A probability distribution used to generate candidate points.
- setsizeint
Number of candidates that each voter approves.
- voter_pointsiterable
A list of points.
The length of this list must be num_voters. The dimension of the points must be the same as the points in candiddate_points or as specified by candidate_prob_distribution. This parameter is only used if voter_prob_distribution is None.
- candidate_pointsiterable
A list of points.
The length of this list must be num_cand. The dimension of the points must be the same as the points in voter_points or as specified by voter_prob_distribution. This parameter is only used if candidate_prob_distribution is None.
- return_pointsbool, optional
If true, also return the list of voter points and a list of candidate points.
- Returns:
- abcvoting.preferences.Profile
- abcvoting.generate.random_euclidean_threshold_profile(num_voters, num_cand, voter_prob_distribution, candidate_prob_distribution, threshold, voter_points=None, candidate_points=None, return_points=False)
Generate a random profile using the Euclidean Threshold probability distribution.
- Parameters:
- num_votersint
The desired number of voters in the profile.
- num_candint
The desired number of candidates in the profile.
- voter_prob_distributionPointProbabilityDistribution or None
A probability distribution used to generate voter points.
- candidate_prob_distributionPointProbabilityDistribution or None
A probability distribution used to generate candidate points.
- thresholdfloat
Voters’ tolerance for approving candidates. This is a float >= 1.
A voter approves all candidates that have at a distance of at most threshold * d, where d is the minimum distance between this voter and any candidate. Setting threshold to 1 means that only the closest candidate is approved (there might be more than one).
- voter_pointsiterable
A list of points.
The length of this list must be num_voters. The dimension of the points must be the same as the points in candidate_points or as specified by candidate_prob_distribution. This parameter is only used if voter_prob_distribution is None.
- candidate_pointsiterable
A list of points.
The length of this list must be num_cand. The dimension of the points must be the same as the points in voter_points or as specified by voter_prob_distribution. This parameter is only used if candidate_prob_distribution is None.
- return_pointsbool, optional
If true, also return the list of voter points and a list of candidate points.
- Returns:
- abcvoting.preferences.Profile
- abcvoting.generate.random_euclidean_vcr_profile(num_voters, num_cand, voter_prob_distribution, candidate_prob_distribution, voter_radius, candidate_radius, voter_points=None, candidate_points=None, return_points=False)
Generate a random profile using the Euclidean VCR (Voter Candidate Range) distribution.
- Parameters:
- num_votersint
The desired number of voters in the profile.
- num_candint
The desired number of candidates in the profile.
- voter_prob_distributionPointProbabilityDistribution or None
A probability distribution used to generate voter points.
- candidate_prob_distributionPointProbabilityDistribution or None
A probability distribution used to generate candidate points.
- voter_radius, candidate_radiusfloat or list of float
Radius of candidates and voters to determine approval ballots.
If a float is given, this radius applies to all voters/candidates. If a list of floats is given, this specifies the radius for each voter/candidate individually. In this case, the length of voter_radius/candidate_radius must be num_voters/num_cand.
A voter approves a candidate if their distance is <= the voter’s radius + the candidate’s radius.
- voter_pointsiterable
A list of points.
The length of this list must be num_voters. The dimension of the points must be the same as the points in candiddate_points or as specified by candidate_prob_distribution. This parameter is only used if voter_prob_distribution is None.
- candidate_pointsiterable
A list of points.
The length of this list must be num_cand. The dimension of the points must be the same as the points in voter_points or as specified by voter_prob_distribution. This parameter is only used if candidate_prob_distribution is None.
- return_pointsbool, optional
If true, also return the list of voter points and a list of candidate points.
- Returns:
- abcvoting.preferences.Profile
References
How to Sample Approval Elections? Stanisław Szufa, Piotr Faliszewski, Łukasz Janeczko, Martin Lackner, Arkadii Slinko, Krzysztof Sornat, Nimrod Talmon. https://arxiv.org/abs/2207.01140
- abcvoting.generate.random_ic_fixed_size_profile(num_voters, num_cand, setsize)
Generate a random profile using the IC with fixed-size approval sets distribution.
- Parameters:
- num_votersint
The desired number of voters in the profile.
- num_candint
The desired number of candidates in the profile.
- setsizeint
Number of candidates that each voter approves.
- Returns:
- abcvoting.preferences.Profile
- abcvoting.generate.random_ic_profile(num_voters, num_cand, p=0.5)
Generate a random profile using the Independent Culture (IC) probability distribution.
- Parameters:
- num_votersint
The desired number of voters in the profile.
- num_candint
The desired number of candidates in the profile.
- pfloat in [0, 1]
Probability of approving a candidate.
- Returns:
- abcvoting.preferences.Profile
References
Corresponds to p-IC in:
How to Sample Approval Elections? Stanisław Szufa, Piotr Faliszewski, Łukasz Janeczko, Martin Lackner, Arkadii Slinko, Krzysztof Sornat, Nimrod Talmon. https://arxiv.org/abs/2207.01140
- abcvoting.generate.random_mallows_profile(num_voters, num_cand, setsize, dispersion)
Generate a random profile using the Truncated Mallows probability distribution.
- Parameters:
- num_votersint
The desired number of voters in the profile.
- num_candint
The desired number of candidates in the profile.
- setsizeint
Number of candidates that each voter approves.
- dispersionfloat in [0, 1]
Dispersion parameter of the Mallows model.
- Returns:
- abcvoting.preferences.Profile
- abcvoting.generate.random_noise_model_profile(num_voters, num_cand, p, phi, distance='hamming')
Generate a random profile using the Random Noise probability distribution.
- Parameters:
- num_votersint
The desired number of voters in the profile.
- num_candint
The desired number of candidates in the profile.
- pfloat in [0, 1]
Fraction of candidates that will be approved by the central ballot.
Precisely, the central ballot will approve the first floor(p * num_cand) candidates.
- phifloat in [0, 1]
Probability to resample an approval.
For each generated vote, we go through all candidates. For each candidate, we copy the approval of the central ballot with probability 1 - phi. Otherwise, with probability phi, we resample the approval of the candidate (so that the generated vote approves that candidate with probability p).
- distancestr, optional
The used distance measure.
The default is Hamming distance (“hamming”). Other possibilities are “jaccard”, “zelinka”, and “bunke-shearer”.
- Returns:
- abcvoting.preferences.Profile
References
How to Sample Approval Elections? Stanisław Szufa, Piotr Faliszewski, Łukasz Janeczko, Martin Lackner, Arkadii Slinko, Krzysztof Sornat, Nimrod Talmon. https://arxiv.org/abs/2207.01140
- abcvoting.generate.random_point(prob_distribution)
Generate a point in space according to a given probability distribution.
- Parameters:
- prob_distributionPointProbabilityDistribution
A probability distribution (see
PointProbabilityDistribution
).
- Returns:
- np.ndarray
- abcvoting.generate.random_profile(num_voters, num_cand, prob_distribution)
Generate a random profile using the probability distribution prob_distribution.
The following probability distributions are supported:
>>> PROBABILITY_DISTRIBUTION_IDS ('IC fixed-size', 'IC', 'Truncated Mallows', 'Urn fixed-size', 'Urn', 'Truncated Urn', 'Euclidean VCR', 'Euclidean fixed-size', 'Euclidean Threshold', 'Resampling', 'Disjoint Resampling', 'Noise')
- Parameters:
- num_votersint
The desired number of voters in the profile.
- num_candint
The desired number of candidates in the profile.
- prob_distributiondict
Specification of the probability distribution.
- Returns:
- abcvoting.preferences.Profile
Examples
Generate a profile via the Independent Culture (IC) distribution with a probability of 0.5.
>>> prob_distribution = {"id": "IC", "p": 0.5} >>> profile = random_profile(num_voters=5, num_cand=5, prob_distribution=prob_distribution) >>> print(profile) profile with 5 voters and 5 candidates: voter 0: {0, 1, 2, 3}, voter 1: {0, 2, 4}, voter 2: {1, 3}, voter 3: {0, 3, 4}, voter 4: {0}
Expand for references to
abcvoting.generate.random_profile
- abcvoting.generate.random_resampling_profile(num_voters, num_cand, p, phi)
Generate a random profile using the Resampling probability distribution.
- Parameters:
- num_votersint
The desired number of voters in the profile.
- num_candint
The desired number of candidates in the profile.
- pfloat in [0, 1]
Fraction of candidates that will be approved by the central ballot.
Precisely, the central ballot will approve the first floor(p * num_cand) candidates.
- phifloat in [0, 1]
Probability to resample an approval.
For each generated vote, we go through all candidates. For each candidate, we copy the approval of the central ballot with probability 1 - phi. Otherwise, with probability phi, we resample the approval of the candidate (so that the generated vote approves that candidate with probability p).
- Returns:
- abcvoting.preferences.Profile
References
How to Sample Approval Elections? Stanisław Szufa, Piotr Faliszewski, Łukasz Janeczko, Martin Lackner, Arkadii Slinko, Krzysztof Sornat, Nimrod Talmon. https://arxiv.org/abs/2207.01140
- abcvoting.generate.random_truncated_urn_profile(num_voters, num_cand, setsize, replace)
Generate a random profile using the Truncated Polya Urn probability distribution.
- Parameters:
- num_votersint
The desired number of voters in the profile.
- num_candint
The desired number of candidates in the profile.
- setsizeint
Number of candidates that each voter approves (top entries from a ranking).
- replacefloat
New balls added to the urn in each iteration, relative to the original number.
The urn starts with num_cand factorial balls, each representing a ranking of candidates. This quantity is normalized to 1.0. The replace value is a float that indicates how many balls are added using this normalization. Specifically, replace * (num_cand factorial) are added in each iteration.
- Returns:
- abcvoting.preferences.Profile
References
How to Sample Approval Elections? Stanisław Szufa, Piotr Faliszewski, Łukasz Janeczko, Martin Lackner, Arkadii Slinko, Krzysztof Sornat, Nimrod Talmon. https://arxiv.org/abs/2207.01140
- abcvoting.generate.random_urn_fixed_size_profile(num_voters, num_cand, setsize, replace)
Generate a random profile using the Polya Urn with fixed-size approval sets distribution.
- Parameters:
- num_votersint
The desired number of voters in the profile.
- num_candint
The desired number of candidates in the profile.
- setsizeint
Number of candidates that each voter approves.
- replacefloat
New balls added to the urn in each iteration, relative to the original number.
The urn starts with (num_cand choose setsize) balls, each representing a set of candidates with size setsize. This quantity is normalized to 1.0. The replace value is a float that indicates how many balls are added using this normalization. Specifically, replace * (num_cand choose setsize) are added in each iteration.
- Returns:
- abcvoting.preferences.Profile
- abcvoting.generate.random_urn_profile(num_voters, num_cand, p, replace)
Generate a random profile using the Polya Urn probability distribution.
- Parameters:
- num_votersint
The desired number of voters in the profile.
- num_candint
The desired number of candidates in the profile.
- pfloat in [0, 1]
If a new vote is generated, each candidate is approved with likelihood p.
- replacefloat
New balls added to the urn in each iteration, relative to the original number.
A value of 1.0 means that in the second iteration, there is a chance of 0.5 that the ballot of the first iteration is chosen and a chance of 0.5 that a new ballot is drawn from p-IC.
- Returns:
- abcvoting.preferences.Profile