Repository files navigation

See theCOMSOC community page for an overview of other software tools related to Computational Social Choice.

The package can be installed using thepip3 package manager:

pip3 install pref_voting

Notes:

• The package requires Python 3.9 or higher and has been tested on Python 3.12.

• Since the package uses Numba, refer to theNumba documentation for the latest supported Python version.

• If you have both Python 2 and Python 3 installed on your system, make sure to usepip3 instead of pip to install packages for Python 3. Alternatively, you can usepython3 -m pip to ensure you're using the correct version of pip. If you have modified your system's defaults or soft links, adjust accordingly.

See theinstallation guide for more detailed instructions.

A profile (of linear orders over the candidates) is created by initializing aProfile class object. Simply provide a list of rankings (each ranking is a tuple of numbers) and a list giving the number of voters with each ranking:

frompref_voting.profilesimportProfilerankings= [    (0,1,2,3),# candidate 0 is ranked first, candidate 1 is ranked second, candidate 2 is ranked 3rd, and candidate 3 is ranked last.    (2,3,1,0),     (3,1,2,0),     (1,2,0,3),     (1,3,2,0)]rcounts= [5,3,2,4,3]# 5 voters submitted the first ranking (0, 1, 2, 3), 3 voters submitted the second ranking, and so on.prof=Profile(rankings,rcounts=rcounts)prof.display()# display the profile

The functiongenerate_profile is used to generate a profile for a given number of candidates and voters:

frompref_voting.generate_profilesimportgenerate_profile# generate a profile using the Impartial Culture probability modelprof=generate_profile(3,4)# prof is a Profile object with 3 candidates and 4 voters# generate a profile using the Impartial Anonymous Culture probability modelprof=generate_profile(3,4,probmod="IAC")# prof is a Profile object with 3 candidates and 4 voters

TheProfile class has a number of methods that can be used to analyze the profile. For example, to determine the margin of victory between two candidates, the plurality scores, the Copeland scores, the Borda scores, the Condorcet winner, the weak Condorcet winner, and the Condorcet loser, and whether the profile is uniquely weighted, use the following code:

prof=Profile([    [2,1,0,3],     [3,2,0,1],     [3,1,0,2]],rcounts=[2,2,3])prof.display()print(f"The margin of 1 over 3 is{prof.margin(1,3)}")print(f"The Plurality scores are{prof.plurality_scores()}")print(f"The Copeland scores are{prof.copeland_scores()}")print(f"The Borda scores are{prof.borda_scores()}")print(f"The Condorcet winner is{prof.condorcet_winner()}")print(f"The weak Condorcet winner is{prof.weak_condorcet_winner()}")print(f"The Condorcet loser is{prof.condorcet_loser()}")print(f"The profile is uniquely weighted:{prof.is_uniquely_weighted()}")

To use one of the many voting methods, import the function frompref_voting.voting_methods and apply it to the profile:

frompref_voting.generate_profilesimportgenerate_profilefrompref_voting.voting_methodsimport*prof=generate_profile(3,4)# create a profile with 3 candidates and 4 voterssplit_cycle(prof)# returns the sorted list of winning candidatessplit_cycle.display(prof)# displays the winning candidates

Additional notebooks that demonstrate how to use the package can be found in theexamples directory

Some interesting political elections are analyzed using pref_voting in theelection-analysis repository.

Consult the documentationhttps://pref-voting.readthedocs.io for a complete overview of the package.

To ensure that the package is working correctly, you can run the test suite usingpytest. The test files are located in thetests directory. Follow the instructions below based on your setup.

• Python 3.9 or higher: Ensure you have a compatible version of Python installed.
• pytest: Installpytest if it's not already installed.

If you are usingPoetry to manage your dependencies, run the tests with:

poetry run pytest

From the command line, run:

pytest

For more detailed output, add the -v or --verbose flag:

pytest -v

If you would like to acknowledge our work in a scientific paper,please use the following citation:

Wesley H. Holliday and Eric Pacuit (2025). pref_voting: The Preferential Voting Tools package for Python. Journal of Open Source Software, 10(105), 7020.https://doi.org/10.21105/joss.07020

@article{HollidayPacuit2025,author ={Wesley H. Holliday and Eric Pacuit},title ={pref_voting: The Preferential Voting Tools package for Python},journal ={Journal of Open Source Software},year ={2025},publisher ={The Open Journal},volume ={10},number ={105},pages ={7020},doi ={10.21105/joss.07020}}

Alternatively, you can cite the archived code repositoryatzenodo.

If you would like to contribute to the project, please see thecontributing guidelines.

Feel free tosend an email if you have questions about the project.

MIT