Vote generation API

Generate votes for voting system simulations.

The generators implemented here mostly produce score votes since those are the most general type. For other types, convert the result using converters:

Vote generators

class votelib.generate.IssueSpaceGenerator(candidates, sampler='gauss', vote_creation='minmax', random_state=None)

Generate random votes by sampling from a multidimensional issue space.

The most common paradigm for random vote generation is to spread some candidates as points into a multidimensional space (representing their opinions or characteristics), then sample voter points from a statistical distribution on that space and determine their votes based on their proximity to candidates. This class implements this paradigm, delegating the sampling to a contained instance of Sampler.

Parameters

  • candidates (Union[int, Dict[Union[str, CandidateObject], Tuple[float, …]]]) – Positions of candidates in the issue space. It is also possible to specify just an integer; in that case, the candidate positions will be sampled in the same way the voters are.

  • sampler (Union[str, Sampler]) – How to sample the voter points. Either an object with a sample() method that yields numerical tuples with the correct number of dimensions (such as instances of Sampler subclasses), or a string referencing a name of a statistical distribution; in that case, DistributionSampler will be invoked in two dimensions with default settings on the specified distribution. See the class documentation for more on supported distributions.

  • vote_creation (str) –

    How to transform voter-to-candidate proximities in the issue space to score votes:

    • minmax: The closest candidate is assigned a score of 1, the furthest is assigned a score of 0. Score votes are produced.

    • closest: The closest candidate is voted for. Simple votes are produced.

    • Other transformations are not implemented.

  • random_state (Optional[int]) – Seed for the sampler.

generate(n)

Generate n votes for the candidate setup.

Return type

Dict[Any, int]

samples_to_votes(sample, candidates)

Convert issue space samples to votes.

Return type

Dict[Any, int]

class votelib.generate.ScoreSpaceGenerator(candidates, sampler='uniform', round_scores=False, random_state=None)

Randomly sample independent candidate scorings.

This generator is simpler than IssueSpaceGenerator since it uses the underlying sampler to produce candidate scorings directly. The candidate scores are independent of each other.

Under default settings, this generator produces the Impartial Culture (IC). By providing different settings for different dimensions of the passed sampler, score probabilities for individual candidates can be set. An example for two candidates, in which A will, on average, get higher scores (mean 0.7) than B (mean 0.3):

ScoreSpaceGenerator(
    candidates=['A', 'B'],
    sampler=BoundedSampler(
        DistributionSampler('gauss', mu=(0.7, 0.3), sigma=(1, 1)),
        bbox=(0, 1)
    )
)
Parameters

  • candidates (Union[int, List[Union[str, CandidateObject]]]) – Candidate objects (most straightforwardly, a list of candidate names as strings). It is also possible to specify just an integer; in that case, the candidate names are autogenerated as uppercase ASCII letters (A, B, C…).

  • sampler (Union[str, Sampler]) – How to sample the scores. Either an object with a sample() method that yields numerical tuples with the correct number of dimensions (such as instances of Sampler subclasses), or a string referencing a name of a statistical distribution; in that case, DistributionSampler will be invoked with default settings on the specified distribution. See the class documentation for more on supported distributions.

  • round_scores (bool) – Whether to round the scores (using round half to even) to integers.

  • random_state (Optional[int]) – Seed for the sampler.

generate(n)

Generate n votes.

Return type

Dict[Any, int]

Random samplers

class votelib.generate.DistributionSampler(distribution='gauss', n_dims=None, **kwargs)

Sample points from the issue or score space by specifying a distribution.

Uses a statistical probability distribution to produce randomly located points within the issue space or score space of given dimensionality. The distributions are taken from Python’s random module by referencing the names of the generating functions.

The outputs from this sampler need to be fed into IssueSpaceGenerator to produce votes or specify candidate positions or into ScoreSpaceGenerator to be converted to candidate scorings directly.

Any superfluous keyword arguments are passed to the generating function from the random module. If no keyword arguments are given but are required (i.e. the distribution parameters need to be specified), for some distributions (uniform, gauss, triangular, beta), defaults are specified in this class and automatically used if necessary.

Parameters

  • distribution (str) – The name of the distribution to use. Must refer to a name of a function in Python stdlib random module that produces random floats.

  • n_dims (Optional[int]) – Dimensionality of the issue or score space to sample from.

sample(n, n_dims=None)

Sample n issue space samples from the distribution.

Return type

Iterable[Tuple[float, …]]

class votelib.generate.BoundedSampler(inner, bbox)

A sampler from a bounded issue space.

Wraps another sampler to only produce issue space samples that lie within a specified multidimensional bounding box. Useful e.g. for the generation of Yee diagrams.

The outputs from this sampler need to be fed into SamplingGenerator to produce votes or specify candidate positions.

Parameters

  • inner (Sampler) – A sampler (e.g. DistributionSampler) to wrap. Its samples are filtered by the specified bounding box.

  • bbox (Tuple[Number, …]) – The bounding box to restrict the samples to. First, all minima per dimension are specified, then all maxima; for two dimensions, this would be (minx, miny, maxx, maxy). If the inner sampler has a defined number of dimensions, it is also possible to specify only two numbers, which will be interpreted as the minimum and maximum in each dimension.

sample(n, *args, **kwargs)

A generator to sample n bbox-restricted issue space samples.

Return type

Iterable[Tuple[float, …]]