This description of the input file format for STV.pm is current as of version 2.15.
title=Centerville City Council Election 2008-11-04The 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.
# commentsAny text on a line following '#' will be ignored.
method=GPCA2000The 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=3
quota=droopquota=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=mandatoryIf 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=1234random= 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=nonSpecify 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.
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=jw Janet WeissThe withdrawn= line follows the format of the candidate= line, with the difference being that votes for candidates so designated are not counted.
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=34The 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.
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 mgThe 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 mgThe multiplier can be fractional.
1/2X ht vs mg 0.25X ht vs mgThe software will object if a ballot has an unknown nickname, or the same nickname appears twice
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 - 4The software will object if the same rank number appears twice, or if numbers are skipped.
The end line terminates the list of ballots. It is not used with the ballots=blt option (below).
end
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.
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 endAn 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