The .pb File Format

The data concerning one instance of participatory budgeting is to be stored in a single UTF-8 text file with the extension .pb. The content of the file is to be divided into three sections:

  • META section with general metadata like the country, budget, number of votes.
  • PROJECTS section with projects costs and possibly some other metadata regarding projects like category, target etc.
  • VOTES section with votes, that can be in one of the four types: approval, ordinal, cumulative, scoring; and optionally with metadata regarding voters like age, sex etc. 

META
key; value
description; Municipal PB in Wieliczka
country; Poland
unit; Wieliczka
instance; 2020
num_projects; 5
num_votes; 10
budget; 2500
rule; greedy
vote_type; approval
min_length; 1
max_length; 3
PROJECTS
project_id; cost; category
1; 600; culture, education
2; 800; sport
4; 1400; culture
5; 1000; health, sport
7; 1200; education
VOTES
voter_id; age; sex; vote
1; 34; f; 1,2,4
2; 51; m; 1,2
3; 23; m; 2,4,5
4; 19; f; 5,7
5; 62; f; 1,4,7
6; 54; m; 1,7
7; 49; m; 5
8; 27; f; 4
9; 39; f; 2,4,5
10; 44; m; 4,5

Detailed Description

The red part is obligatory.

  • key
    • description
    • country
    • unit – name of the municipality, region, organization, etc., holding the PB process.
    • subunit – name of the sub-jurisdiction or category within which the preferences are aggregated and funds are allocated
      • Example: in Paris, there are 21 PBs – a city-wide budgets and 20 district-wide budgets. For the city-wide budget, unit is Paris, and subunit is undefined, while for the district-wide budgets, unit is also Paris, and subunit is the name of the district (e.g., IIIe arrondissement).
      • Example: before 2019, in Warsaw there have been district-wide and neighborhood-wide PBs. For all of them, unit is Warsaw, while subunit is the name of the district for district-wide budgets, and the name of the neighborhood for neighborhood-wide budgets. To associate neighborhoods with districts (if desired), an additional property district can be used.
      • Example: assume that in a given city, there are distinct PBs for each of $n>1$ categories (environmental projects, transportation projects, etc.). For all of them, unit is the city name, while subunit is the name of the category.
    • instance – a unique identifier of the specific edition of the PB process (year, edition number, etc.) used by the organizers to identify that edition; note that instance will not necessarily correspond to the year in which the vote is actually held, as some organizers identify the edition by the fiscal year in which the PB projects are to be carried out.
    • num_projects
    • num_votes
    • budget – the total amount of funds to be allocated
    • vote_type
      • approval – each vote is a subset of projects,
      • ordinal – each vote is a permutation of a subset of project such that its size is in $[$min_length$,$ max_length$]$, corresponding to a strict preference ordering,
      • cumulative – each vote is a vector $\mathbf{v} \in \mathbb{R}_{+}^{|P|}$ such that ${\lVert\mathbf{v}\rVert}_{1} \le $max_sum_points $ \in \mathbb{R}_{+}$, we usually omit the projects that have zero support,
      • scoring – each vote is a vector $\mathbf{v} \in I^{|P|}$, where $I \subseteq \mathbb{R}$.
    • rule
      • greedy – projects are ordered decreasingly by the value of the aggregation function (i.e., the total score), and are funded until funds are exhausted or there are no more projects,
      • other rules will be defined in future versions.
    • date_begin – the date on which voting starts.
    • date_end – the date on which voting ends.
    • language – language of the description texts (i.e., full project names).
    • edition
    • district
    • comment
    • if vote_type = approval:
      • min_length [default: 1]
      • max_length [default: num_projects]
      • min_sum_cost [default: 0]
      • max_sum_cost [default: $\infty$]
    • if vote_type = ordinal:
      • min_length [default: 1]
      • max_length [default: num_projects]
      • scoring_fn [default: Borda]
    • if vote_type = cumulative:
      • min_length [default: 1]
      • max_length [default: num_projects]
      • min_points [default: 0]
      • max_points [default: max_sum_points]
      • min_sum_points [default: 0]
      • max_sum_points
    • if vote_type = scoring:
      • min_length [default: 1]
      • max_length [default: num_projects]
      • min_points [default: $-\infty$]
      • max_points [default: $\infty$]
      • default_score [default: 0]
    • non-standard fields
  • value

  • project_id
  • cost
  • name – full project name
  • category – for example: education, sport, health, culture, environmental protection, public space, public transit and roads
    • Example: A project might be classified under 'environmental protection' if it aims to improve recycling facilities in a community.
    • Example: A 'public space' project could involve renovating a local park to include more seating areas and playground equipment.
  • target -- for example: adults, seniors, children, youth, people with disabilities, families with children, animals
    • Example: A project targeted at 'youth' might include building a new skateboard park.
    • Example: 'Seniors' might be the target for a project that introduces fitness programs tailored to older adults in community centers.
  • non-standard fields
    • Example: A non-standard field might be 'sustainability', indicating whether a project adheres to environmental sustainability principles.
    • Example: 'Community involvement' could be another non-standard field, detailing the extent of local community participation in the project's planning and execution.

  • voter_id
  • age
  • sex
  • voting_method (e.g., paper, Internet, mail)
  • if vote_type = approval:
    • vote – ids of the approved projects, separated by commas.
  • if vote_type = ordinal:
    • vote – ids of the selected projects, from the most preferred one to the least preferred one, separated by commas.
  • if vote_type = cumulative:
    • vote – project ids, in the decreasing order induced by points, separated by commas; projects not listed are assumed to be awarded $0$ points.
    • points – points assigned to the selected projects, listed in the same order as project ids in vote.
  • if vote_type = scoring:
    • vote – project ids, in the decreasing order induced by points, separated by commas; projects not listed are assumed to be awarded default_score points.
    • points – points assigned to the selected projects, listed in the same order as project ids in vote.
  • non-standard fields