pref_voting
See the COMSOC community page for an overview of other software tools related to Computational Social Choice.
Installation
The package can be installed using the pip3 package manager:
pip3 install pref_voting
Notes:
-
The package requires Python 3.10 or higher and has been tested on Python 3.12.
-
Since the package uses Numba, refer to the Numba documentation for the latest supported Python version.
-
If you have both Python 2 and Python 3 installed on your system, make sure to use
pip3instead of pip to install packages for Python 3. Alternatively, you can usepython3 -m pipto ensure you're using the correct version of pip. If you have modified your system's defaults or soft links, adjust accordingly. -
Optional extras install the interfaces to VoteKit and abcvoting, which convert between the election objects of pref_voting and those packages (see the demo notebook):
pip3 install "pref_voting[votekit]"(requires Python >= 3.11),pip3 install "pref_voting[abcvoting]", orpip3 install "pref_voting[interfaces]"for both.
See the installation guide for more detailed instructions.
Example Usage
A profile (of linear orders over the candidates) is created by initializing a Profile 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:
from pref_voting.profiles import Profile
rankings = [
(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 function generate_profile is used to generate a profile for a given number of candidates and voters:
from pref_voting.generate_profiles import generate_profile
# generate a profile using the Impartial Culture probability model
prof = generate_profile(3, 4) # prof is a Profile object with 3 candidates and 4 voters
# generate a profile using the Impartial Anonymous Culture probability model
prof = generate_profile(3, 4, probmod = "IAC") # prof is a Profile object with 3 candidates and 4 voters
The Profile 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 from pref_voting.voting_methods and apply it to the profile:
from pref_voting.generate_profiles import generate_profile
from pref_voting.voting_methods import *
prof = generate_profile(3, 4) # create a profile with 3 candidates and 4 voters
split_cycle(prof) # returns the sorted list of winning candidates
split_cycle.display(prof) # displays the winning candidates
Additional notebooks that demonstrate how to use the package can be found in the examples directory
Some interesting political elections are analyzed using pref_voting in the election-analysis repository.
Consult the documentation https://pref-voting.readthedocs.io for a complete overview of the package.
Testing
To ensure that the package is working correctly, you can run the test suite using pytest. The test files are located in the tests directory. Follow the instructions below based on your setup.
Prerequisites
- Python 3.10 or higher: Ensure you have a compatible version of Python installed.
pytest: Installpytestif it's not already installed.
Running the tests
If you are using uv to manage your dependencies, run the tests with:
uv run pytest
From the command line, run:
pytest
For more detailed output, add the -v or --verbose flag:
pytest -v
How to cite
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
BibTeX:
@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 repository at zenodo.
Contributing
If you would like to contribute to the project, please see the contributing guidelines.
Questions?
Feel free to send an email if you have questions about the project.
License
1 maintainer
Metadata
1 maintainer
Release files for pref_voting 1.18.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pref_voting-1.18.2.tar.gz | 270.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pref_voting-1.18.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 585.8 kB
Release files / pref_voting-1.18.2.tar.gz
| Download URL | pref_voting-1.18.2.tar.gz |
|---|---|
| Size | 270.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b7f1aa45716cfafbfd70168f87e4332750e503517335535c9bebb2211b66ce5f
|
|
BLAKE2b-256 checksum How to use checksums |
6919923c4a10b39e6f2d13534fc9a276f0e9a535cd884e2eec5386110eebd659
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.8 {"installer":{"name":"uv","version":"0.11.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / pref_voting-1.18.2-py3-none-any.whl
| Download URL | pref_voting-1.18.2-py3-none-any.whl |
|---|---|
| Size | 315.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a3d5f4375937de6585f0730b9dfab74edb34f84e1fa8b317d87b507a4d3ecdb9
|
|
BLAKE2b-256 checksum How to use checksums |
79c243fe0b1d958f372a72b63bb2144a221591c0e26225d2270d70c7e0b6e314
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.8 {"installer":{"name":"uv","version":"0.11.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
