Skip to main content

Implementation of PB voting rules and tools for reading Pabulib datasets

Project description

pabutools---tools for participatory budgeting

Pabutools provides two submodules: model and rules.


Provides the classes representing voters, candidates and election instances.

  • Voter(id, sex=None, age=None, subunits=set()) with the following attributes:

    • id: unique ID of the voter,
    • sex: 'M' (male), 'F' (female) or None (no information),
    • age: a natural number or None (no information),
    • subunits: a set of strings (subunits which the voter belongs to).
  • Candidate(id, cost, name=None, subunit=None) with the following attributes:

    • id: unique ID of the candidate,
    • cost: a natural number,
    • name: string or None (no information),
    • subunit: string or None (no information or a citywide project).
  • Election(name=None, voters=None, profile=None, budget=0, subunits = None) with the following attributes:

    • voters: a set of Voter instances,
    • profile: a dict where keys are Candidate instances and values are dicts in which keys are Voter instances and values are natural numbers (voters' utilities over candidates; if a voter has utility 0, she can be skipped),
    • budget: a natural number,
    • subunits: a set of strings (subunits within the instance).

    and the following methods:

    • read_from_file(pattern): takes as an input the pattern of the filepaths of Pabulib files and fills the data of the newly created Election instance with them (e.g. calling Election().read_from_files('pabulib/poland_warszawa_2021*') will create a PB election out of all Pabulib files under the provided path starting with 'poland_warszawa_2021'). If the pattern fits more than one file, they should all be from the same country, unit and year. By default, approval utilities are considered to be binary.
    • cost_to_binary_utilities(): if the utilities are cost utilities, they are converted to binary
    • binary_to_cost_utilities(): if the utilities are binary, they are converted to cost utilities


Provides the implementation of a number of voting rules for PB. All the methods take as an argument an election instance and return a set of elected candidates.

  • utilitarian_greedy(e : Election): the simple greedy algorithm,
  • phragmen(e : Election): the Phragmen's Sequential Method,
  • equal_shares(e : Election, completion=None): the method of equal shares. The 'completion' parameter can take the following values:
    • None: no completion (default option).
    • 'binsearch': initial endowments of the voters are set to maximize the exhaustiveness of the elected committee with the use of binary search.
    • 'add1': initial endowments of the voters are increased similarly as above so that the committee is as exhaustive as possible; instead of using binary search, we keep increasing voters' endowments by 1 unit until the outcome is exhaustive or we exceed the original budget. - 'add1_utilitarian': similarly as in add1 completion, but if the outcome is still not exhaustive, it is completed by utilitarian greedy.
    • 'utilitarian_greedy': the completion with utilitarian_greedy.
    • 'phragmen': the completion with the Phragmen's Sequential Method.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pabutools-0.8.tar.gz (5.7 kB view hashes)

Uploaded source

Built Distribution

pabutools-0.8-py3-none-any.whl (6.3 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page