preftools

DISCONTINUED as of 2014-08-25

preftools is a bundle of command line utilities for ballot counting, currently containing "schulze", "schulze-simple" and "propor". The command line utils are used to create a ranking based on ballot data, given in a CSV like text file.

The "schulze" tool returns a ranking according to the Schulze Method. It is additionally possible to split the preference list of each ballot into 3 parts: Approvals, neutral part, disapprovals. For each candidate you can select a ratio (quorum) of approvals to disapprovals neccessary for the candidate to be taken into account.

The "schulze-simple" tool is a simplified version of the "schulze" tool, not implementing any tie-breaking and only supporting a quorum of 1/2+ corresponding to >50%. The lack of tie-breaking simplifies a description of the algorithm for electoral regulations. (See sample description in german language.)

The "propor" tool uses random numbers to – statistically seen – create a proportional ranking out of voters preferences. The algorithm works as follows: Select a random ballot out of all ballots which have at least one candidate not crossed out. The first candidate on the chosen ballot, which was not crossed out, is selected as next winner. This winner is crossed out on all ballots. The whole procedure is repeated with all ballots until all candidates on all ballots are crossed out. The more winners you select, the more proportional are the voters represented in the result. The algorithm is NOT suitable for creating candidate lists or electing board members, but it is aimed to be used for selecting the order of processing of motions in a meeting. As the "propor" tool behaves randomly on one side, but its results need to be reproducible on the other side (to be able to avoid fraud), it will request a file containing random numbers in order to work. This numbers need to be publicly drawn.

Dependencies

Download

Data format

For both tools all possible candidates have to be listed in a text file separated by comma or semicolon, or be given in seperate lines. For the "schulze" tool a ratio of approvals to disapprovals needed for this candidate may be placed after each candidate, separated by a colon. A plus sign after the ratio indicates that the ratio must be strictly greater than the given value. Consider the following example:

Candidate A : 1/2+
Candidate B : 1/2+
Candidate C : 2/3

As opposed to the "schulze" tool the "schulze-simple" and the "propor" tool will not accept any ratio specifications using colons.

The ballots have to be listed in another text file, each line corresponding to one ballot. For the "schulze" or "schulze-simple" tool it is possible to split each line into 3 parts by using a slash as delimiter. The first section will be approvals, the second section will be neutral, the third section will be disapprovals. A comma is used to separate candidates having the same ranking and a semicolon is used to separate candidates having a different ranking, while the first candidates have the highest preference. Different preferences are only possible in the approval and the disapproval part, hence using a semicolon in the neutral part is illegal. If you do not use slashes to separate a ballot into 3 parts, then all entries will be counted as approvals. Consider the following example:

Candidate A; Candidate B / Candidate C /
Candidate A, Candidate C / / Candidate B
Candidate A / Candidate B / Candidate C
Candidate C; Candidate A, Candidate B / /

For the "schulze" tool it is neccessary to either name ALL existing candidates in each ballot or to provide a default position for missing candidates, which can be "neutral", "first" or "last". Specifying "neutral" as default, causes missing candidates to have the same rank as other candidates ranked as neutral. Specifying "first" means that missing candidates are disapproved and ranked just behind the candidates ranked as neutral, but before the other candidates in the disapproval part. Specifying "last" means that missing candidates are disapproved and ranked after all other candidates.

The "propor" tool behaves differently: It does not expect all candidates to be listed in each ballot and it does not support different sections in a ballot (slashes will be treated like semicolons). For the "propor" tool it is recommended to enforce a strict ranking, hence only using semicolons as delimiter:

Candidate A; Candidate B
Candidate A; Candidate C; Candidate B

Using commas to equally rank candidates within a ballot will cause a random candidate to be chosen, if the ballot is drawn.

The "propor" tool also needs random numbers as input, which are used to randomly select ballots in a reproducible way. The random file first needs a specified range, e.g. "1-6", written in an own line. The following lines each contain a number within the specified range. Within the file a new range may be specified at any time. See example:

1-6
4
2
6
1
1-2
1
2
2
1
1
1
2
1-49
13
22

All files may contain empty lines and extra whitespace before and after each entry. A hash (#) indicates a comment until the end of the line.

Changes

  • 2011-01-09: Version 0.9
    • Removed unused function approval_ratio in schulze-simple program
  • 2011-01-09: Version 0.8
    • Fixed definition in german description text of schulze-simple algorithm
  • 2010-12-28: Version 0.7
    • Fixed error in german description text of schulze-simple algorithm
  • 2010-12-27: Version 0.6
    • Added german example ballots
  • 2010-12-23: Version 0.5
    • Added missing LICENSE file
  • 2010-12-23: Version 0.4
    • Added german description of a voting process utilizing schulze-simple
    • Beautified output of schulze and schulze-simple
      • Ranking is displayed only when there is at least one approved candidate
      • Renamed “Comparison” to “Direct comparison” for clarification
  • 2010-12-17: Version 0.3
    • schulze-simple tool added, which is a simplified version of the schulze tool. A quota of 1/2+ is hard-coded and tie-breaking is not performed in the simplified version.
    • Minor code style change in schulze
  • 2010-12-10: Version 0.2
    • schulze
      • Show battle results between approved candidates ordered by ranking
    • propor
      • Do not consume random data, when all ballots are equal
      • Output of random number transformation more verbose
    • Added example data files
    • Code cleanup and minor bugfixes related to padding in output
  • 2010-12-05: Initial release (v0.1)