centerforcollectivelearning / comchoice Goto Github PK

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.

• 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.

pip install comchoice

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

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.

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.

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)

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.

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:

Pairwise comparison data:

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"
)

Then, let's calculate some metrics using the pairwise comparison data set.

bradley_terry(df_pw)

ComChoice was developed by the research group in Digital Democracy at the Center for Collective Learning, Université de Toulouse.

The ComChoice library is distributed under General Public License (GPL), version 3. More details here.

We invite you to create an issue in the project's GitHub repository (https://github.com/CenterForCollectiveLearning/comchoice/issues).