PrefSampling is a lightweight Python library that provides preference samplers. These are algorithms that generate random preferences based on precisely defined statistical cultures. We consider different type of preferences:
This package is part of the Guide to Numerical Experiments on Elections in Computational Social Choice.
The package can be installed from PyPI using:
pip3 install prefsampling
The complete documentation is available here.
If you are using this package we kindly ask you to cite the following reference to credit our work link.
Boehmer N., Faliszewski P., Janeczko Ł., Kaczmarczyk A., Lisowski G., Pierczyński G., Rey S., Stolicki D., Szufa S., Wąs T. (2024).
Guide to Numerical Experiments on Elections in Computational Social Choice.
arXiv preprint arXiv:2402.11765.
We are more than happy to receive help with the development of the package. If you want to contribute, here are some elements to take into account.
First, install the development dependencies by running the following command:
pip install -e ".[dev]"
We try to enforce uniformity within the package. Here are some general guidelines.
num_voters
and num_candidates
as their two first positional argumentsseed
parameter to set the seed of the random number generatorWithin the package, the samplers are organised in modules based on the ballot format they
generate. The prefsampling.core
module is used for features used across samplers.
Within the submodule corresponding to the ballot format, there is a Python file
for each family of samplers. All the samplers are imported and appear in the __all__
variable of the __init__.py
file of the corresponding module (defined by the ballot
format).
The tests are run with unittest. Simply run the following command to launch the tests:
python -m unittest
The structure of the test module follows that of the package. There is one submodule per ballot format we sample. Within the submodule, there is one file per statistical culture.
At the submodule level, there is a file test_all_ballotformat_samplers.py
that gathers the
test that are common to all samplers of the given ballot format.
In the file corresponding the statistical culture, there is a function that returns all the samplers (with their arguments set) that are used as test cases, together with the tests that are specific to the sampler.
When a new sampler is added to the package, it needs to be added in several places within the test module:
test/ballotformat/test_ballotformat_culturename.py
defining the tests specific to the sampler and the functions to use for the tests (called random_ballotformat_culturename_samplers
).test_all_ballotformat_samplers.py
, add the functions for the sampler to the random_ballotformat_samplers()
function.random_samplers()
in the file test/test_all_samplers.py
.We aim at statistically validating the samplers we provide. All the code necessary to
run the validation is gathered in the validation
folder of the repository.
When a new sampler is added to the package, proceed as follows:
validation/ballotformat/
folder.validation.validator.Validator
. This requires you to define a set of methods used to compute the theoretical probabilities of the outcomes of the samplers.run.py
file.run.py
file (you may want to comment out some parts).doc-source/source/validation_plots
folder.doc-source/source/validation.rst
file accordingly.The doc is generated using sphinx. We use the numpy style guide. The napoleon extension for Sphinx is used and the HTML style is defined by the Book Sphinx Theme.
To generate the doc, first move inside the docs-source
folder and run the following:
make clean
make html
This will generate the documentation locally (in the folder docs-source/build
). If you want the documentation
to also be updated when pushing, run:
make githubclean
make github
After having pushed, the documentation will automatically be updated. Note that the
github
directive may not work on Windows.
The pipeline between GitHub and PyPI is automatised. To push a new version do the following:
pyproject.toml
with the new version number.prefsampling/__init__.py
with the new version number.