Generate Profiles ======================================= ## Sampling Profiles We use the [prefsampling](https://comsoc-community.github.io/prefsampling/index.html) package to sample profiles from standard probability functions. There is a single function, ``generate_profile``, to interface with the prefsampling functions. The following are the available probability models for generating profiles: 1. Impartial Culture Model: generate a profile by sampling from a uniform distribution over profiles with $n$ candidates and $m$ voters, where each voter is equally likely to have any of the $n!$ linear orders on the candidates. ```{eval-rst} .. exec_code:: from pref_voting.generate_profiles import generate_profile # the following all generate a profile with 3 candidates and 5 voters # using the Impartial Culture model: prof = generate_profile(3, 5) # the default is the IC model prof = generate_profile(3, 5, probmodel="IC") prof = generate_profile(3, 5, probmodel="impartial") ``` 2. Impartial Anonymous Culture: generate a profile by sampling from a uniform distribution over anonymous profiles. ```{eval-rst} .. exec_code:: from pref_voting.generate_profiles import generate_profile # the following all generate a profile with 3 candidates and 5 voters # using the Impartial Anonymous Culture model: prof = generate_profile(3, 5, probmodel="IAC") prof = generate_profile(3, 5, probmodel="impartial_anonymous") ``` 3. The Urn model: In the Polya-Eggenberger urn model, to generate a profile given a parameter $\alpha\in [0,\infty)$, each voter in turn randomly draws a linear order from an urn. Initially the urn is the set of all linear orders on the $n$ candidates. If a voter randomly chooses $L$ from the urn, we return $L$ to the urn plus $\alpha n!$ copies of $L$. IC is the special case where $\alpha=0$. The Impartial Anonymous Culture (IAC) is the special case where $\alpha=1/n!$. ```{eval-rst} .. exec_code:: from pref_voting.generate_profiles import generate_profile # the following all generate a profile with 3 candidates and 5 voters # using the Urn model: # default is URN with alpha=0.0, which is equivalent to the IC model. prof = generate_profile(3, 5, probmodel="urn") prof = generate_profile(3, 5, probmodel="URN", alpha=5) prof = generate_profile(3, 5, probmodel="urn", alpha=5) # in addition, there is a pre-defined urn models prof = generate_profile(3, 5, probmodel="URN-10") # URN with alpha=10 ``` 4. Urn models where the $\alpha$ parameter depends on the number of candidates: "URN-0.3" is the urn model with $\alpha=n!*0.3$ where $n$ is the number of candidates; and "URN-R" is the random URN model, where, following Boehmer et al. ("Putting a compass on the map of elections," IJCAI-21), for each generated profile, we chose $\alpha$ according to a Gamma distribution with shape parameter $k=0.8$ and scale parameter $\theta=1$. ```{eval-rst} .. exec_code:: from pref_voting.generate_profiles import generate_profile # the following all generate a profile with 3 candidates and 5 voters # using the Urn model: prof = generate_profile(3, 5, probmodel="URN-0.3") prof = generate_profile(3, 5, probmodel="URN-R") ``` 5. The Mallow's model: generate a profile by fixing a reference linear ordering of the candidates (called the **central_vote**) and assign to each voter a ranking that is "close" to this reference ranking. Closeness to the reference ranking is defined using the Kendall-tau distance between rankings, depending on a *dispersion* parameter $\phi$. Setting $\phi= 0$ means that every voter is assigned the reference ranking, and setting $\phi=1$ is equivalent to the IC model. Formally, to generate a profile given a reference ranking $L_0\in\mathcal{L}(X)$ and $\phi\in (0,1]$, the probability that a voter's ballot is $L\in\mathcal{L}(X)$ is $Pr_{L_0,\phi}(L)=\phi^{\tau(L,L_0)}/C$ where $\tau(L,L_0)= {{|X|}\choose{2}} - |L\cap L_0|$, the Kendell-tau distance of $L$ to $L_0$, and $C$ is a normalization constant. ```{eval-rst} .. exec_code:: from pref_voting.generate_profiles import generate_profile # the following all generate a profile with 3 candidates and 5 voters # using the Mallow's model: # default is phi = 1.0, which is equivalent to the IC model. prof = generate_profile(3, 5, probmodel="MALLOWS") prof = generate_profile(3, 5, probmodel="mallows") prof = generate_profile(3, 5, probmodel="mallows", phi=0.5) # in addition, you can fix the central ranking prof = generate_profile(3, 5, probmodel="mallows", central_vote=[2, 1, 0], phi=0.5) ``` 7. The Mallow's model with a parameter that [Boehmer et al. (2021)](https://arxiv.org/abs/2105.07815) call rel-$\phi$, which together with the number of candidates determines the $\phi$ value. ```{eval-rst} .. exec_code:: from pref_voting.generate_profiles import generate_profile # the following all generate a profile with 3 candidates and 5 voters # using the Mallow's model: # default is relphi is generated randomly from the interval (0,1). prof = generate_profile(3, 5, probmodel="MALLOWS-RELPHI") prof = generate_profile(3, 5, probmodel="MALLOWS-RELPHI", relphi=0.5) # the following are pre-defined Mallow's models with relphi=0.375 prof = generate_profile(3, 5, probmodel="MALLOWS-RELPHI-0.375") # the relphi parameter is chosen uniformly from the interval (0,1) prof = generate_profile(3, 5, probmodel="MALLOWS-RELPHI-R") ``` 8. The Mallow's model with the phi parameter normalized as discussed in [Boehmer, Faliszewski and Kraiczy (2023)](https://proceedings.mlr.press/v202/boehmer23b.html). ```{eval-rst} .. exec_code:: from pref_voting.generate_profiles import generate_profile # the following all generate a profile with 3 candidates and 5 voters # using the Mallow's model: prof = generate_profile(3, 5, probmodel="mallows", phi=0.5, normalise_phi=True) ``` 9. SinglePeaked - a profile $\mathbf{P}$ is *single peaked* if there exists a strict linear order $<$ of $X(\mathbf{P})$ such that for every $i\in V(\mathbf{P})$ and $x,y\in X(\mathbf{P})$, $x