Urn Models#
- urn(num_voters: int, num_candidates: int, p: float, alpha: float, seed: int = None) list[set] [source]#
Generates votes following the Pólya-Eggenberger urn culture. The process is as follows. The urn is initially empty and votes are generated one after the other, in turns. When generating a vote, the following happens. With a probability of 1/(urn_size + 1),an approval ballots in which all candidates have the same probability p of being approved is selected at random (following an impartial culture as in the
impartial()
function). With probability 1/urn_size a vote from the urn is selected uniformly at random. In both cases, the vote is put back in the urn together with alpha * (2**m) copies of the vote (where m is the number of candidates).Note that for a given number of voters, votes are not sampled independently.
- Parameters:
num_voters (int) – Number of voters
num_candidates (int) – Number of candidates
p (float) – Proportion of approved candidates in a ballot.
alpha (float) – The dispersion coefficient (alpha * m! copies of a vote are put back in the urn after a draw). Must be non-negative.
seed (int, default:
None
) – The seed for the random number generator.
- Returns:
The votes
- Return type:
list[set]
Examples
from prefsampling.approval import urn # Sample from an urn model with 2 voters and 3 candidates, alpha parameter is 0.5, # parameter p is 0.7 urn(2, 3, 0.7, 0.5) # For reproducibility, you can set the seed. urn(2, 3, 0.7, 0.5, seed=1002) # Passing a negative alpha will fail try: urn(2, 3, 0.7, -0.5) except ValueError: pass # Parameter p needs to be in [0, 1] try: urn(2, 3, 1.7, 0.5) except ValueError: pass try: urn(2, 3, -0.7, 0.5) except ValueError: pass
References
None.
- urn_constant_size(num_voters: int, num_candidates: int, rel_num_approvals: float, alpha: float, seed: int = None) list[set] [source]#
Generates votes following the Pólya-Eggenberger urn culture. The process is as follows. The urn is initially empty and votes are generated one after the other, in turns. When generating a vote, the following happens. With a probability of 1/(urn_size + 1), an approval ballots of size ⌊rel_num_approvals * num_candidates⌋ is selected uniformly at random (following an impartial culture as in the
impartial_constant_size()
function). With probability 1/urn_size a vote from the urn is selected uniformly at random. In both cases, the vote is put back in the urn together with alpha * (m choose ⌊rel_num_approvals * num_candidates⌋) copies of the vote (where m is the number of candidates).Note that for a given number of voters, votes are not sampled independently.
- Parameters:
num_voters (int) – Number of voters
num_candidates (int) – Number of candidates
rel_num_approvals (float) – Proportion of approved candidates in a ballot.
alpha (float) – The dispersion coefficient (alpha * m! copies of a vote are put back in the urn after a draw). Must be non-negative.
seed (int, default:
None
) – The seed for the random number generator.
- Returns:
The votes
- Return type:
list[set]
Examples
from prefsampling.approval import urn_constant_size # Sample from an urn model with 2 voters and 3 candidates, alpha parameter is 0.5, # parameter rel_num_approvals is 0.7 urn_constant_size(2, 3, 0.7, 0.5) # For reproducibility, you can set the seed. urn_constant_size(2, 3, 0.7, 0.5, seed=1002) # Passing a negative alpha will fail try: urn_constant_size(2, 3, 0.7, -0.5) except ValueError: pass # Parameter rel_num_approvals needs to be in [0, 1] try: urn_constant_size(2, 3, 1.7, 0.5) except ValueError: pass try: urn_constant_size(2, 3, -0.7, 0.5) except ValueError: pass
References
None.
- urn_partylist(num_voters: int, num_candidates: int, alpha: float, parties: int | Iterable[float] = None, party_votes: Iterable[set[int]] = None, seed: int = None) list[set[int]] [source]#
Generates approval votes partylist model. In this model, the candidates are partitioned into parties. Voters are assigned a party using an urn model with parameter
alpha
where the balls represent the parties. A voter then approves of all the candidates belonging to their party.If the votes of the parties are not provided (argument
party_votes
), they are determined by the relative size of the parties relative size (argumentparties
). The vote of the first party (of size s1) will always be {0, 1, …, s1 - 1}, the vote of the second party (of size s2) will always be {s1, s1 + 1, …, s2}, etc… In particular, it can be that some candidates are not assigned any party and will thus never be approved (depending on the relative size of the parties). If only the number of parties is given (whenparties
is a integer), then they are assumed to be of equal size.Note that for a given number of voters, votes are not sampled independently.
- Parameters:
num_voters (int) – Number of Voters.
num_candidates (int) – Number of Candidates.
alpha (float) – Parameter for Urn model.
parties (int | Iterable[float], defaults:
None
) – Fractional sizes of the parties. If an integer is given, then it is assumed that it represents the number of parties that have equal size. Needed if the argumentparty_votes
is not provided.party_votes (Iterable[set[int]], defaults:
None
) – The votes of the parties. Needed if the argumentparties
is not provided.seed (int, default:
None
) – Seed for numpy random number generator.
- Returns:
Approval votes.
- Return type:
list[set[int]]
Examples
from prefsampling.approval import urn_partylist # Sample from an urn party-list model with 2 voters and 3 candidates, # alpha parameter is 0.5, and there are 2 equal-sized parties urn_partylist(2, 3, 0.5, parties=2) # For reproducibility, you can set the seed. urn_partylist(2, 3, 0.5, parties=2, seed=1002) # You can use parties of different sizes (sizes are normalised) urn_partylist(2, 5, 0.5, parties=[1, 5, 0.8]) # You can also just provide the votes of the parties urn_partylist(2, 5, 0.5, party_votes=[{0, 2}, {1, 3, 4}]) # The votes of the parties have to be disjoint try: urn_partylist(2, 5, 0.5, party_votes=[{0, 2}, {0, 3, 4}]) except ValueError: pass # You need to pass a value to either 'parties' or 'party_votes' try: urn_partylist(2, 3, 0.5) except ValueError: pass # Passing a negative alpha will fail try: urn_partylist(2, 3, -0.5, parties=2) except ValueError: pass
References
None.