STV File Format

This description of the input file format for STV.pm is current as of version 2.15.

title=

title=Centerville City Council Election 2008-11-04

The title line describes the election being counted. No particular format is required, but the title should include the name and date of the election. The title will appear as part of the program output.

comments

# comments

Any text on a line following '#' will be ignored.

method=

method=GPCA2000
The required method= line specifies the STV counting method to be used. Supported methods:
method=BC
British Columbia STV, but with fractional quota and random tiebreaking.
method=GPCA2000
Green Party of California rules adopted in 2000. GPCA2000 implies BC rules with a mandatory Droop quota.
method=Meek
Meek's method (Algorithm 123).
method=Warren
Similar to Meek's method, but with Warren's method of allocating surplus votes.
method=blt
When method=blt is specified, no count is performed. Instead, the election data is output in .blt format, for use by counting software such as OpenSTV.

seats=

seats=3

quota=

quota=droop

quota=droop is the default, and specifies a Droop quota of (ballots / (seats+1)).

quota=hare specifies a Hare quota of (ballots / seats).

For the Meek and Warren methods only, a quota of droop2 or hare2 can be specified, which implies a mandatory minimum quota of Droop/2 or Hare/2 respectively. This option is experimental.

quota=103 (or another number) specifies an exact numeric quota, and can be used, for example, to specify a rounded-up Droop quota, if necessary.

quota=mandatory

If quota=mandatory is specified in addition to another quota, then a candidate must reach the specifed quota quota in order to be elected, and that seats may be left empty. If quota=mandatory is not specified, all seats are filled (if possible) from the remaining active candidates, even if they have not reached the quota.

method=GPCA2000 implies quota=mandatory.

random=

random=1234

random= seeds the random-number generator used to break ties. One way of picking a seed is to have a representative of each candidate choose a secret number, and to use the sum of those numbers as the seed. Reveal the secret numbers so that they can be verified.

random=non

Specify random=non to break ties non-randomly, in the order of candidate entry. This is useful for testing, or when the random order is determined externally.

candidate=

Each candidate= line has a candidate nickname (typically initials; no spaces) followed by the candidate's full name. Nicknames (initials or first names or any unique designation) are used to make unordered ballots easier to enter, and are also used for the order= option.

candidate=gb George Brown
candidate=mg Mary Green
candidate=ht Hermione Tan
candidate=hb Harvey Black
candidate=vs Violet Smith

withdrawn

withdrawn=jw Janet Weiss

The withdrawn= line follows the format of the candidate= line, with the difference being that votes for candidates so designated are not counted.

order=

Two ballot formats are supported. In the first, the ballot a series of blank lines, labeled 1, 2, 3, etc. The voter fills in the name of candidates in preference order. The ballots are very general, and no candidate benefits from being first on the list. It allows write-ins, if desired.

The second ballot format lists the candidate names, one per line. The voter writes a rank number 1, 2, 3, etc next to candidate names. Write-ins can be accommodated with additional blank lines.

The second ballot format requires the "order=" line, specifying the actual order of candidate names on the ballot. Data entry proceeds by writing down the rank numbers specified by the voter, using a hyphen ('-') for unranked candidates.

order=gb ht mg hb vs

ballots=

ballots=34

The ballots= line must appear after all other options and immediately before the ballot data. The ballot count must match the actual number of ballots or the program will not proceed. This is intended as a data-entry cross-check.

ballot data (unordered format)

If there is no order= line, ballots consist of an optional multiplier (1X is assumed if no mulitplier is present) followed by one or more candidate nicknames, in the order specified by the voter.

gb ht hb
vs mg

The optional multipler indicates that the line should be treated as multiple identical ballots. (This feature is not generally useful in real-world elections.)

10X ht vs mg

The multiplier can be fractional.

1/2X ht vs mg
0.25X ht vs mg

The software will object if a ballot has an unknown nickname, or the same nickname appears twice

ballot data (order= format)

When order= is used, the identity of the candidates is implied by the order= line, and each ballot data line shows the rankings specified by the voter. Unranked candidates are shown with '-'.

1 2 - 3 - -
- - 2 1 - -

As with the unordered format, multipliers are allowed.

8X 3 - 1 2 - 4

The software will object if the same rank number appears twice, or if numbers are skipped.

end

The end line terminates the list of ballots. It is not used with the ballots=blt option (below).

end

ballots=blt

STV.pm will also accept .blt-format ballot files, a format used by other STV counting software, incuding OpenSTV. In this format, only the method= and quota= lines are used; the other information is included in the .blt format. Indicate this format with "ballots=blt".

Following ballots=blt, the remainder of the file is in .blt format. The first line contains the number of candidates and the number of seats. Additional lines of the form -2 indicate withdrawn candidates (-2 means that the second candidate in the candidate list should be treated as withdrawn). Ballot lines start with a multiplier, nicknames implicitly 1..n, and end with 0. Following the ballots is a list of candidate names, in order and in quotes. Last is the election title.

Examples

An unordered-ballot example:

title=STV Voting Example 2007-05-01
seats=3
quota=droop
quota=mandatory
random=37863
candidate=gb George Brown
candidate=mg Mary Green
candidate=ht Hermione Tan
candidate=hb Harvey Black
candidate=vs Violet Smith
candidate=ab Able Body
ballots=21
gb
gb ht hb
ab ht
ht
ht
ab
gb ht hb
hb ht
gb ht hb
vs gb ht hb
vs
vs gb ht hb
vs mg
mg vs
mg
mg vs gb
ab
mg
ht vs
ab
ht ab gb hb
end

An ordered-ballot example:

title=Test of Choice Voting
seats=3
quota=droop
random=37863
candidate=gb George Brown
candidate=mg Mary Green
candidate=ht Hermione Tan
candidate=hb Harvey Black
candidate=vs Violet Smith
candidate=ab Able Body
order=gb mg ht hb vs ab
ballots=3
1 - 2 3 - -
1 - 2 3 - -
- - 1 2 - -
end