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.

Each section starts with a title line (one of META, PROJECTS, VOTES), followed by a column header line which is a semicolon-separated list of the names of the columns used in the section (for the META section this must be key;value, for the other sections it depends on which information is available), followed by several lines encoding the data. 

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
date_begin; 16.09.2023
date_end; 04.10.2023
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.

All fields are provided as key:value pairs.

        * we use integers instead of booleans for flag values (such as 1 and 0) as this approach provides more flexibility. For example, a project can be either selected (1) or not (0). But there are cases where a project is selected for another reason, such as an error made by the company conducting the voting process. In such cases, we can assign a special value, like 2, and explain it in a comment.