I. Overview
This Help assumes that you already understand the basics of an STV election and guides the process of using OpenSTV. There are three basic steps to running an election:
- Ballots Menu: Either load ballots from a file or enter them through the program.
- Method Menu: Choose the election method and set options (if any).
- 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 only two items. The Reset option puts OpenSTV mostly back into its initial state. The Exit option exits.
III. Edit Menu
You can copy selected text from the current tab and paste it into another program. You can also select all of the text in the current tab.
IV. Ballots Menu
Ballots may be loaded from a file or entered through the program. Two ballot file formats are supported: text 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 text format. Here is an example:
Amy Bob Chuck
Bob Amy
Chuck
Chuck Bob
The first ballot lists Amy first, Bob second, and Chuck third. Note that candidate names must be alphanumeric. You can also add a weight to a ballot by prefixing it with a number and a colon:
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
Unlike the above example, comments are not allowed in a BLT file.
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 ballots can be edited, added, and deleted. You can mix appending and editing 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.
Finally, you can shuffle the order of the ballots. This could be interesting for Cambridge STV and Random Transfer STV because the outcome can depend on the order of the ballots.
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 the more common methods are shown. Choose "Show All Methods" to see the others.
VI. Election Menu
Set the number of candidates to elect, a title for the election, and for some methods, the precision to be displayed on the screen. The election results will be displayed in a new tab.
You can also select candidates to eliminate from the election. The eliminated candidates are removed from the ballots before counting the votes.
VII. Results Menu
Unwanted tabs can be deleted, but you can't delete the console tab. The font size in any tab can be changed to the desired size. If the election results are wider than the window size, then choosing a smaller font size may allow for easier viewing of election results.
The results can be saved into a file and two formats are supported. The text format is exactly what you see on the screen. The CSV (comma separated value) output is used by the Electoral Reform Society and can be loaded into any spreadsheet program. The CSV format is not available for all methods.
VIII. Help Menu
From the Help Menu you can also find more details on the election methods available and the GNU General Public License.
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. (OpenSTV.py and wxPython are not needed). Here is an example:
from ballots import *
from STV import *
b = Ballots()
b.loadBLT("ballots.blt")
e = CambridgeSTV(b)
e.runElection()
