Skip to content

Python implementations of approval-based committee (multi-winner) voting rules

License

Notifications You must be signed in to change notification settings

martinlackner/abcvoting

Repository files navigation

DOI DOI PyPi Python versions Build badge Unittests badge docs Code style: black codecov

abcvoting

For an overview of other software tools related to Computational Social Choice, see the COMSOC community page.

A Python library of approval-based committee (ABC) rules

Approval-based committee rules (ABC rules) are voting methods for selecting a committee, i.e., a fixed-size subset of candidates. ABC rules are also known as approval-based multi-winner rules. The input of such rules are approval ballots. We recommend the book (Multi-Winner Voting with Approval Preferences) by Lackner and Skowron [2] as a detailed introduction to ABC rules and related research directions. In addition, the survey by Faliszewski et al. [1] is useful as a more general introduction to committee voting (not limited to approval ballots).

The following ABC rules are implemented:

  • Approval Voting (AV)

  • Satisfaction Approval Voting (SAV)

  • Proportional Approval Voting (PAV)

  • Sequential Proportional Approval Voting (seq-PAV)

  • Reverse Sequential Proportional Approval Voting (revseq-PAV)

  • Approval Chamberlin-Courant (CC)

  • Phragmén's sequential rule

  • Monroe's rule

  • Minimax Approval Voting (MAV)

  • Greedy Monroe

  • Method of Equal Shares (Rule X)

  • Phragmén's First Method (Eneström's Method)

  • and many more ...

In addition, one can verify axiomatic properties such as

  • Justified Representation (JR)

  • Propotional Justified Representation (PJR)

  • Extended Justified Representation (EJR)

  • Priceability

  • The core property

Instead of using the abcvoting Python library, you can also use the abcvoting web application by Dominik Peters (which is based on this Python library).

Installation

As simple as:

pip install abcvoting

Further details can be found here.

Development

Install all dependencies including development requirements and the abcvoting package in development mode:

pip install -e ".[dev]"

Basic unit tests can be run by excluding tests which require additional dependencies:

pytest  -m "not mipgurobi and not gmpy2 and not slow" tests/

For development, configure the black formatter and pre-commit hooks - see below. Also installing all optional dependencies is recommended.

A development package is build for every commit on the master branch and uploaded to the test instance of PyPI. It can be installed using the following command:

python3 -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple abcvoting

Black formatting

Code needs to be formatted using the black formatter. This is checked by Github actions. Configure your editor to run the black formatter.

Pre-commit hooks

Pre-commit hooks are not required, but they are recommended for development. Pre-commit is used to manage and maintain pre-commit hooks. Install pre-commit (e.g. via apt, conda or pip) and then run $ pre-commit install to install the hooks.

References

[1] Piotr Faliszewski, Piotr Skowron, Arkadii Slinko, and Nimrod Talmon. Multiwinner voting: A new challenge for social choice theory. In Ulle Endriss, editor, Trends in Computational Social Choice, chapter 2, pages 27–47. AI Access, 2017. http://research.illc.uva.nl/COST-IC1205/BookDocs/Chapters/TrendsCOMSOC-02.pdf

[2] Lackner, Martin, and Piotr Skowron. "Multi-Winner Voting with Approval Preferences". Springer International Publishing, SpringerBriefs in Intelligent Systems , 2023. https://link.springer.com/book/10.1007/978-3-031-09016-5