ComChoice (Computational Choice) is a large collection of many well-known voting rules and aggregation methods in Python.
Project description
What it is?
ComChoice is an open-source library to aggregate individual and collective preferences in Python. This library aims to convert the state-of-the-art in Social Choice Theory, Decision-Making Process and Pairwise Comparison Optimization into easy and intuitive functions to be used by programmers and researchers with basic programming knowledge.
ComChoice provides a module to run an API to aggregate preferences. This API can be used for digital democracy platforms.
What we provide?
- Algorithmic implementation in Python and DataFrame objects of most of the state-of-the-art in voting rules studied in Computational Social Choice (e.g., complete preferences, participatory budgeting).
- Methods to test some axiomatic properties in Social Choice Theory.
- A robust framework to run digital democracy platforms' backends, by providing an easy-to-use API developed in FastAPI.
Getting Started
Via pip
pip install comchoice
From source code
To install comchoice
from the source, you need first to clone the project repository as follows:
git clone https://github.com/CenterForCollectiveLearning/comchoice.git
cd comchoice
python setup.py install
Basic Background
The function parameters in this library follow, in most cases, the terminology adopted by the COMSOC community. Nonetheless, some functions includes specific parameters called by their notation in the literature.
Let $A$ a set of $n$ alternatives, such that $A = {a_1, a_2, a_3, ..., a_n}$. A ballot represents an input of preferences of a voter or voters over a set of candidates (either an ordered set of preferences or approved ones)\footnote{In the COMSOC literature, we find references of voters as agents, and candidates as alternatives.}. The preferences are separated by a delimiter, that by default is represented by $>$. In case of approval ballots, the default delimiter is the comma ($,$). For example, a ballot ($B$) for a voter is $B = {a>b>c}$. This ballot means that the voter prefers $a$ over $b$, $b$ over $c$, and $a$ over $c$.
In general, voting methods present two outputs: a winner or a ranking of preferences. We call winner rule those that returns a winner (or group of them) of an election; whereas we refer to voting rule those that returns a score for each alternative. It should be noted that a voting rule can be interpreted as a winner rule, since the top-scored alternative is considered the winner. This option is included in the library by a parameter defined in the functions of voting rules.
Hands on Coding
Hello world: Synthethic data
For starting, let's use the data of an election of 22 voters and 4 alternatives. Then, voters provided their ranking of preferences.
import pandas as pd
from comchoice.aggregate import borda
data = [
{"voters": 7, "ballot": "A>B>C>D"},
{"voters": 5, "ballot": "B>C>D>A"},
{"voters": 6, "ballot": "D>B>C>A"},
{"voters": 4, "ballot": "C>D>A>B"}
]
df = pd.DataFrame(data)
borda(df)
Here, our goal is to calculate a ranking of alternatives by using Borda count.
alternative | value | rank |
---|---|---|
B | 41 | 1 |
C | 35 | 2 |
D | 31 | 3 |
A | 25 | 4 |
As shown in the table above, borda
method includes alternatives' Borda score and their aggregate position.
Next, if you are interested in testing other rules using the same data, you just need to execute another function to the dataframe already defined. For instance, condorcet
method calculates the Condorcet winner of an election.
from comchoice.aggregate import condorcet
condorcet(df, weak=True)
alternative | value |
---|---|
B | 0.833333 |
In this example, B is a weak Condorcet winner because it is ranked above any other alternative in individual matches. Still, it does not beat all the alternatives.
Manage Pairwise Comparison data
Convert Star-rated dataset to Pairwise Comparison
comchoice
allows converting an dataset into pairwise comparison data through to_pairwise()
method defined in the subpackage preprocessing
.
Let's suppose that we have two alternatives and two voters. Voter 1 rates alternative A with 5 stars, and rates alternative B with 3 stars. In this case, we could assume that voter 1 will choose alternative A over alternative B.
Our data:
voter | alternative | rating |
---|---|---|
1 | A | 5 |
1 | B | 3 |
2 | A | 4 |
2 | B | 5 |
Pairwise comparison data:
voter | option_a | option_b | selected |
---|---|---|---|
1 | A | B | A |
2 | A | B | B |
Here an example how would be the code:
df = pd.DataFrame([
(1, A, 5),
(1, B, 3),
(2, A, 4),
(2, B, 5)
], columns=["voter", "alternative", "rating"])
df_pw = to_pairwise(
df,
value="rating"
)
Calculating metrics
Then, let's calculate some metrics using the pairwise comparison data set.
bradley_terry(df_pw)
About
ComChoice
was developed by the research group in Digital Democracy at the Center for Collective Learning, Université de Toulouse.
GPL-3 License
The ComChoice
library is distributed under General Public License (GPL), version 3. More details here.
Do you have any questions?
We invite you to create an issue in the project's GitHub repository (https://github.com/CenterForCollectiveLearning/comchoice/issues).
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file comchoice-0.1.0.tar.gz
.
File metadata
- Download URL: comchoice-0.1.0.tar.gz
- Upload date:
- Size: 42.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.10.8
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 870a83f766e3f6e13dc8a421294a1330791a4b22728c017dc2bf667a3734fec1 |
|
MD5 | 4440021a9b377c3506ad8fa3ae6eeae1 |
|
BLAKE2b-256 | 5772daf0e815bd8a7259cae3b1b5c3d94a6e6977c483168a1c0c5b3dd0f90e7f |
File details
Details for the file comchoice-0.1.0-py3-none-any.whl
.
File metadata
- Download URL: comchoice-0.1.0-py3-none-any.whl
- Upload date:
- Size: 80.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.10.8
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | f721084d20854ede151be18a478400c7a18cd1bac5c50128db8915d9092ffa2a |
|
MD5 | 75811fac7ebadbc39b219dc5e6788519 |
|
BLAKE2b-256 | 37a64f0fa9f22c5e3d49c67cb1072814cca3c59135216c787b59bc1ac2037970 |