Quick Start#

Organisation of the package#

The samplers are organised in the package based on the format of sample they produce. The module prefsampling.ordinal contains the ordinal samplers that generate rankings of the candidates. The module prefsampling.approval contains the samplers for approval preferences, the ones that generate sets of candidates.

Sample Types#

To make it easy to embed the package in all kinds of tools, we use basic Python types:

A collection of votes represented as a list, each element representing a voters;
Ordinal samplers return lists of list where the most preferred candidate is at position 0, the next one at position 1 and so forth;
Weak ordinal samplers return lists of list of list, that is, indifference classes are represented as (sorted) lists, the rest follows the representation of strit ordinal votes;
Approval samplers return lists of set, where each set contains the approved candidates.

In all cases, the candidates are named 0, 1, 2, ….

General Syntax#

All the sampler we provide have the same signature:

sampler(num_voters, num_candidates, **args, seed=None, **kwargs)

The parameter num_voters represents the number of samples that will be generated and the parameter num_candidates the number of candidates to consider. The seed parameter can be used to pass the seed used to defined the numpy random number generator to give you more control if needed (for replication for instance). Other parameters are specific to the samplers.

In the code reference of each sampler we provide examples of how to use the samplers in your code. We refer the reader to these examples and do not provide a general “how to” section here.

Ordinal Samplers#

Reference: prefsampling.ordinal

Sampler	**args	**kwargs
`identity()`	—	—
`impartial()`	—	—
`impartial_anonymous()`	—	—
`mallows()`	`phi`	`central_vote` (defaults to 0, 1, 2, …) `normalise_phi` (defaults to `False`) `impartial_central_vote` (defaults to `False`)
`norm_mallows()`	`norm_phi`	`central_vote` (defaults to 0, 1, 2, …)
`euclidean()`	`num_dimensions` `voters_positions` `candidates_positions`	`voters_positions_args` (defaults to `dict()`) `candidates_positions_args` (defaults to `dict()`) `tie_radius` (defaults to `None`)
`plackett_luce()`	`alphas`	—
`didi()`	`alphas`	—
`urn()`	`alpha`	—
`stratification()`	`weight`	—
`single_peaked_conitzer()`	—	—
`single_peaked_walsh()`	—	—
`single_peaked_circle()`	—	—
`k_axes_single_peaked()`	`k` `axes_weights`	`inner_sp_sampler`
`single_crossing()`	—	—
`group_separable()`	—	`tree_sampler` (defaults to `SCHROEDER`)

Approval Samplers#

Reference: prefsampling.approval

Sampler	**args	**kwargs
`identity()`	`rel_num_approvals`	—
`empty()`	—	—
`full()`	—	—
`impartial()`	`p`	—
`impartial_constant_size()`	`rel_num_approvals`	—
`urn()`	`p` `alpha`	—
`urn_constant_size()`	`rel_num_approvals` `alpha`	—
`urn_partylist()`	`alpha`	`parties` (required if `party_votes is None`) `party_votes` (required if `parties is None`)
`resampling()`	`phi` `rel_size_central_vote`	`central_vote` (defaults to {0, 1, 2, …}) `impartial_central_vote` (defaults to `False`)
`disjoint_resampling()`	`phi` `rel_size_central_vote`	`num_central_votes` (defaults to `None`) `central_votes` (see docs for the defaults) `impartial_central_votes` (defaults to `False`)
`moving_resampling()`	`phi` `rel_size_central_vote` `num_legs`	`central_votes` (see docs for the defaults) `impartial_central_votes` (defaults to `False`)
`euclidean_threshold()`	`threshold` `num_dimensions` `voters_positions` `candidates_positions`	`voters_positions_args` (defaults to `dict()`) `candidates_positions_args` (defaults to `dict()`)
`euclidean_vcr()`	`voters_radius` `candidates_radius` `num_dimensions` `voters_positions` `candidates_positions`	`voters_positions_args` (defaults to `dict()`) `candidates_positions_args` (defaults to `dict()`)
`euclidean_constant_size()`	`rel_num_approvals` `num_dimensions` `voters_positions` `candidates_positions`	`voters_positions_args` (defaults to `dict()`) `candidates_positions_args` (defaults to `dict()`)
`noise()`	`phi` `rel_size_central_vote`	`distance` (defaults to `HAMMING`) `central_votes` (see docs for the defaults) `impartial_central_votes` (defaults to `False`)
`truncated_ordinal()`	`rel_num_approvals` `ordinal_sampler` `ordinal_sampler_parameters`

Composition of Samplers#

It is often useful to be able to compose samplers, to define mixture for instance. The functions mixture() and concatenation() can do that.

The mixture uses different samplers, each being use with a given probability.

from prefsampling.core import mixture
from prefsampling.ordinal import single_peaked_conitzer, single_peaked_walsh, norm_mallows

# We create a mixture for 100 voters and 10 candidates of the single-peaked samplers using the
# Conitzer one with probability 0.6 and the Walsh one with probability 0.4
mixture(
    100,  # num_voters
    10,  # num_candidates
    [single_peaked_conitzer, single_peaked_walsh],  # list of samplers
    [0.6, 0.4],  # weights of the samplers
    [{}, {}]  # parameters of the samplers
)

# We create a mixture for 100 voters and 10 candidates of different Mallows' models
mixture(
    100,  # num_voters
    10,  # num_candidates
    [norm_mallows, norm_mallows, norm_mallows],  # list of samplers
    [4, 10, 3],  # weights of the samplers
    [{"norm_phi": 0.4}, {"norm_phi": 0.9}, {"norm_phi": 0.23}]  # parameters of the samplers
)

The concatenation simply concatenates the votes returned by different samplers.

from prefsampling.core import concatenation
from prefsampling.ordinal import single_peaked_conitzer, single_peaked_walsh

# We create a concatenation for 100 voters and 10 candidates. 60 votes are sampled from the
# single_peaked_conitzer sampler and 40 votes from the single_peaked_walsh sampler.
concatenation(
    [60, 40],  # num_voters per sampler
    10,  # num_candidates
    [single_peaked_conitzer, single_peaked_walsh],  # list of samplers
    [{}, {}]  # parameters of the samplers
)

Filters#

Filters are functions that operate on collections of votes and apply some random operation to them. These are the filters we have implemented:

Filter	Effect
`permute_voters()`	Randomly permutes the voters
`rename_candidates()`	Randomly rename the candidates
`resample_as_central_vote()`	Resamples the votes using them as central votes of sampler whose definition include a central vote (e.g., `mallows()` or `resampling()`)
`coin_flip_ties()`	Introduce random ties in a strict ordinal ballot

Below is an example of how to use the resample_as_central_vote() filter.

from prefsampling.core import resample_as_central_vote
from prefsampling.ordinal import single_crossing, norm_mallows

num_candidates = 10
initial_votes = single_crossing(100, num_candidates)

resample_as_central_vote(
    initial_votes,  # The votes
    norm_mallows,  # The sampler
    {"norm_phi": 0.4, "seed": 855, "num_candidates": num_candidates},  # The arguments for the sampler
)

Constants#

The constants used in the package are defined with respect to their corresponding samplers, see for instance EuclideanSpace or SetDistance. They are also all gathered in the prefsampling.CONSTANTS enumeration.

from prefsampling import CONSTANTS

CONSTANTS.BALL
CONSTANTS.SCHROEDER
CONSTANTS.BUNKE_SHEARER

Not that EuclideanSpace and CONSTANTS are not the same enumeration so direct comparison will fail. Indeed, CONSTANTS.BALL == EuclideanSpace.BALL is evaluated to False. However, the values are the same so CONSTANTS.BALL.value == EuclideanSpace.BALL.value is evaluated to True.

Quick Start

Contents