This section describes how to get the vote data into the program.
There are may ways to collect votes, so there are two different ways to specify the input (more details below):
For the current version, it is assumed that the information has been entered in a spreadsheet such as Excel that can save 'comma seperated value' files, although the information can be entered directly.
For example, a voter ranks their most to least favorite colours from the following colours:
| Blue | Green | Orange | Red | Violet | Yellow |
Say a voter prefers Green, second choice is Red, third choice is Blue, and doesn't really care about the rest.
In rank ordering, the vote is expressed in the order of the choices:
| Green | Red | Blue |
This gets a little cumbersome to enter, so every name can be replaced by a label (these can be more than one character):
| Blue | Green | Orange | Red | Violet | Yellow |
| b | g | o | r | v | y |
Thus the vote can be expressed as:
| g | r | b |
In most elections, the voter will have filled out some sort of form:
| Blue | Green | Orange | Red | Violet | Yellow |
| 3 | 1 | 2 |
where a 1 means first preference, 2 means second preference, etc., so the vote can be expressed:
| 3 | 1 | 2 |
This is specified in terms of a spreadsheet - see next subsection for doing it as a file.
The first row is one of:
rank ordering candidate ordering
to specify which ordering is used (the word ordering can be left off, as everything after the first word is ignored). It is most important to get this right, as otherwise the votes will be scrambled.
The second row is the word:
NAME
in one cell followed by the list of names, one per cell.
If rank ordering is used, the next line is the word
LABEL
in one cell followed by the list of labels, one per cell. Do not use the string "0" consisting of the single digit zero as a label. If candidate ordering is used, omit this line.
Then each row represents one voter, with the some sort of voter identifier in the first cell, the only restriction being that it be unique per voter, followed by the vote in either rank ordering or candidate ordering, as specified on the first line.
Say that we have the voter above, called Voter_A, and another voter (Voter_B) who has the preference:
Red, Orange, Violet, Yellow
Putting it all together, these votes can be represented as (using the two ordering methods):
| rank | ||||||
| NAME | Blue | Green | Orange | Red | Violet | Yellow |
| LABEL | b | g | o | r | v | y |
| Voter_A | g | r | b | |||
| Voter_B | r | o | v | y |
or
| candidate | ||||||
| NAME | Blue | Green | Orange | Red | Violet | Yellow |
| Voter_A | 3 | 1 | 2 | |||
| Voter_B | 2 | 1 | 3 | 4 |
Now simply save this as a ".csv" (comma separated value) file, and run the voting software on it.
This is simply like the spreadsheet, with the cells replaced by commas, so the above two examples would be as follows (filenames are in Italics):
test1a.csv rank order NAME,Blue,Green,Orange,Red,Violet,Yellow LABEL,b,g,o,r,v,y Voter_A,g,r,b Voter_B,r,o,v,y
or
test1b.csv candidate order NAME,Blue,Green,Orange,Red,Violet,Yellow Voter_A,3,1,,2 Voter_B,,,2,1,3,4
NOTE: this form was broken in version 0.3 (although the version with 0's to fill the gaps did work). It is fixed in 0.4 onwards.
The software can handle trailing commas, and also zero to fill the gaps, so either of the following would also work:
test1c.csv rank order NAME,Blue,Green,Orange,Red,Violet,Yellow LABEL,1,2,3,4,5,6 Voter_A,2,4,1,0,0,0 Voter_B,4,3,5,6,0,0
or
test1d.csv candidate order NAME,Blue,Green,Orange,Red,Violet,Yellow Voter_A,3,1,0,2,0,0 Voter_B,0,0,2,1,3,4
Now go to the section on running the program to process this data.