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),
]

(Source code, png, hires.png, pdf)

Expand for references to abcvoting.generate.PointProbabilityDistribution

abcvoting.generate

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(len(profile))
5

Expand for references to abcvoting.generate.random_profile

abcvoting.generate

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