Package: comchoice
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 StartedVia pippip install comchoiceFrom source codeTo installcomchoicefrom 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 installBasic BackgroundThe 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}$. Aballotrepresents an input of preferences of avoterorvotersover a set ofcandidates(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 adelimiter, 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 callwinner rulethose that returns a winner (or group of them) of an election; whereas we refer tovoting rulethose that returns a score for each alternative. It should be noted that avoting rulecan be interpreted as awinner rule, since the top-scored alternative is considered the winner. This option is included in the library by a parameter defined in the functions ofvoting rules.Hands on CodingHello world: Synthethic dataFor 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.alternativevaluerankB411C352D313A254As shown in the table above,bordamethod 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,condorcetmethod calculates the Condorcet winner of an election.from comchoice.aggregate import condorcet

condorcet(df, weak=True)alternativevalueB0.833333In 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 dataConvert Star-rated dataset to Pairwise Comparisoncomchoiceallows converting an dataset into pairwise comparison data throughto_pairwise()method defined in the subpackagepreprocessing.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:voteralternativerating1A51B32A42B5Pairwise comparison data:voteroption_aoption_bselected1ABA2ABBHere 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 metricsThen, let's calculate some metrics using the pairwise comparison data set.bradley_terry(df_pw)AboutComChoicewas developed by the research group in Digital Democracy at theCenter for Collective Learning, UniversitÃ© de Toulouse.GPL-3 LicenseTheComChoicelibrary is distributed under General Public License (GPL), version 3. More detailshere.Do you have any questions?We invite you to create an issue in the project's GitHub repository (https://github.com/CenterForCollectiveLearning/comchoice/issues).