Package: prefsampling
PrefSamplingOverviewPrefSampling 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:Ordinal: preferences are expressed as rankings of the candidates;Approval: preferences are expressed by indicating a set of approved candidates.InstallationThe package can be installedfrom PyPIusing:pip3installprefsamplingDocumentationThe complete documentation is availablehere.DevelopmentSetting up the development modeWe 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:pipinstall-e".[dev]"ConventionsWe try to enforce uniformity within the package. Here are some general guidelines.All samplers havenum_votersandnum_candidatesas their two first positional argumentsAll samplers accept aseedparameter to set the seed of the random number generatorWithin the package, the samplers are organised in modules based on the ballot format they
generate. Theprefsampling.coremodule 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__.pyfile of the corresponding module (defined byt the ballot
format).TestsThe tests are run with unittest. Simply run the following command to launch the tests:python-munittestSeveral tests are automatised. When a new sampler is added to the package, it needs
to be added in several places for the tests. The following list provides the details:Add the sampler to the listALL_SAMPLERSintest_all_samplers.py. Follow the convention for the import statements (that you can guess from the ones already there) to avoid duplicated names. The basic requirements (parameters, validation, etc.) that any sampler need to satisfy will then be checked.Add the sampler to corresponding test file for its ballot format:test_all_ballotformat_samplers.py.If needed, add a filetest_ballotformat_samplername.pyfor tests that are specific to the sampler.ValidationWe aim at statistically validating the samplers we provide. All the code necessary to
run the validation is gathered in thevalidationfolder of the repository.When a new sampler is added to the package, proceed as follows:Create the corresponding file in thevalidation/ballotformat/folder.In this file, define a class that inherit from thevalidation.validator.Validator. This requires you to define a set of methods used to compute the theoretical probabilities of the outcomes of the samplers.Add the validator in therun.pyfile.Run therun.pyfile (you may want to comment out some parts).Copy the generated graphs in the correct place of thedoc-source/source/validation_plotsfolder.Update thedoc-source/source/validation.rstfile accordingly.DocumentationThe doc is generated using sphinx. We use thenumpy style guide.
Thenapoleonextension for Sphinx is used
and the HTML style is defined by theBook Sphinx Theme.To generate the doc, first move inside thedocs-sourcefolder and run the following:makecleanmakehtmlThis will generate the documentation locally (in the folderdocs-source/build). If you want the documentation
to also be updated when pushing, run:makegithubAfter having pushed, the documentation will automatically be updated. Note that thegithubdirective may not work on Windows.Publishing on PyPIThe pipeline between GitHub and PyPI is automatised. To push a new version do the following:Update thepyproject.tomlwith the new version number.On GitHub, create a new release tagged with the bew version number.You're done, the new version of the package is automatically pushed to PyPI after the creation of a GitHub release.