pSTV Help

I. Overview

This Help assumes that you already understand the basics of an STV election and guides the process of using pSTV. There are three basic steps to running an election:

1. Ballots Menu: Either load ballots from a file or enter them through the program.
2. Method Menu: Choose the election method and set options (if any).
3. Election Menu: Choose the number of people to elect and count the votes.

These three steps are described in more detail below.

II. File Menu

The file menu contains some of your standard items. The printing is fairly rudimentary, but you can copy the text from the main window and paste it into another program to obtain more control over the printing. For loading and saving ballots, see the Ballots menu.

For an ERS97 election, you can save the results in the format of an ERS style result sheet. This is a CSV (comma separated value) file that can be loaded into a spreadsheet.

III. Edit Menu

IV. Ballots Menu

Ballots may be loaded from a file or entered through the program. Two ballot file formats are supported: raw format and BLT format. The BLT format is preferred. The program will ask you to save modified ballots before exiting or loading a new set of ballots, but you can save the ballots at any time.

The first ballot file format supported is the "raw" format. Here is an example:

    Amy Bob Chuck
    Bob Amy
    Chuck
    Chuck Bob

    10: Amy Bob Chuck
    5: Bob Amy
    Chuck
    2: Chuck Bob

The second format is the BLT format used by the Electoral Reform Society. Here is an example:

    4 2          # four candidates are competing for two seats
    -2           # Bob has withdrawn (optional)
    1 4 1 3 2 0  # first ballot
    1 2 4 1 3 0
    1 1 4 2 3 0  # The first number is the ballot weight (>= 1).
    1 1 2 4 3 0  # The last 0 is an end of ballot marker.
    1 1 4 3 0    # Numbers inbetween correspond to the candidates
    1 3 2 4 1 0  # on the ballot.
    1 3 4 1 2 0
    1 3 4 1 2 0  # Chuck, Diane, Amy, Bob
    1 4 3 2 0
    1 2 3 4 1 0  # last ballot
    0            # end of ballots marker
    "Amy"        # candidate 1
    "Bob"        # candidate 2
    "Chuck"      # candidate 3
    "Diane"      # candidate 4
    "Gardening Club Election"  # title

There is also a menu item that allows BLT files to be appended. First load one BLT file and then append the others. All the BLT files must have the same number of candidates, the same number of seats, and identical candidate names.

Ballots may also be entered through the program. If no ballot file has been loaded, then a new ballot file is created. If a ballot file has been loaded, then entered ballots will be appended to the end. You can mix appending and entering of ballots.

The program accepts only valid ballots. You don't need to rank all of the candidates on each ballot, but you cannot skip rankings. You also cannot give two or more candidates the same ranking.

V. Method Menu

A variety of election methods are available and are listed roughly in order of increasing complexity. See Method Details in the help menu for more information on each method. If Method->Options is gray, then there are no options. By default, only STV methods are shown. Choose "Show All Methods" to see the others.

• Single Non-Transferable Vote
• Borda Count
• Instant Runoff Voting
• Bucklin System
• Coombs Method
• Condorcet
• British Columbia STV (formerly Simple STV) -- STV rules proposed for use in British Columbia. The rules are a slight simplification of the rules presented in Behind the Ballot Box by Douglas Amy. See the Help menu for the definition of these rules.
• Cambridge STV -- STV rules used to elect the city council and school committee in Cambridge, MA. The implementation replicates the 1999, 2001, and 2003 city council and school committee elections.
• ERS97 STV -- STV rules created by the Electoral Reform Society. Brian Wichmann of the Electoral Reform Society has verified the implementation.
• Customizable Random Transfer STV -- Allows the user to customize a generic random transfer STV algorithm. For advanced use only.
• Customizable Fractional Transfer STV -- Allows the user to customize a generic fractional transfer STV algorithm (which is British Columbia STV). For advanced use only.
• Meek and Warren STV -- These two implementations have been verified against the example in Tideman and Richardson, "Better voting methods through technology: The refinement-manageability trade-off in the single transferable vote," Public Choice 103: 13-34, 2000.

VI. Election Menu

Set the number of candidates to elect and count the votes.

VII. Display Menu

Two display parameters may be set here. First, the screen font size. This can help get all the information the screen for a larger number of candidates. Second, the displayed precision can be adjusted (all calculations are done to machine precision).

VIII. Help Menu

From the Help Menu you can also find more details on the election methods available and the rules for British Columbia STV.

IX. Advanced Use

You can also write your own Python scripts to run elections. To do this, you would use the Python modules STV.py and ballots.py. (pSTV.py and wxPython are not needed). Here is an example:

    from ballots import *
    from STV import *

    b = Ballots()
    b.loadBLT("ballots.dat")
    e = Election(b)
    e.CambridgeSTV()

IX. Contributions

I would greatly appreciate help in improving pSTV. Please contact me if you know Python or are willing to learn. Testing, suggestions, and bug reports are also greatly appreciated.

I would like to thank the people from Sourceforge, Python, wxPython/wxWidgets, py2exe, and Inno Setup for making the software that pSTV depends on. I would also like to thank David Gamble and Brian Wichmann for their testing and feedback and Nicolaus Tideman for his excellent publications and contributions to the field.

Jeff O'Neill
jco8 at cornell.edu