HowToGenerateAnAudit.txt

How to use this tool for generating an audit configuration (in JSON format).
----------------------------------------------------------------------------

1. Compile (if using Linux, you can probably use the provided Makefile,
otherwise you will likely need to write a custom Makefile).

2. To generate an audit with a risk limit of 5%, gamma = 1.1, lambda = 0.01, 
run the command: 

./irvaudit -rep_ballots REPORTED_BALLOT_FILE -r 0.05 -gamma 1.1 -lambda 0.01 
    -agap 0.005 -alglog -simlog -json OUTPUT_AUDIT_SPEC.json

The 'lambda' and 'gamma' parameters are associated with the current test
statistic being used to compute risk/estimate audit effort (Kaplan-Markov).
Note that the audit configuration produced can be used in an audit with any
desired risk limit -- the audit will just involve more/less ballot polls than
estimated by the software. The 'alglog' and 'simlog' parameters, if provided,
will simply print the current status of the algorithm as it progresses. They
are not necessary, but useful. 

The 'agap' parameter controls the degree of 'suboptimality' you are willing to
accept in your audit configuration. The software is designed to produce a
series of assertions that, with the given parameters (risk limit, gamma,
lambda), requires the least number of estimated ballot polls to audit.
Depending on the election, the algorithm may take longer than you would like to
find the optimal set of assertions (it also has to prove that these are
optimal). With agap = 0.005, we are saying that the configuration found can be
0.5% away from optimal, or require 0.5% more auditing effort than the 
optimal audit. Increasing it should make audit generation quicker. The 
default is 0.005, so you can leave off this flag if you want to keep it at
this value. 

A concrete example you can run:

./irvaudit -rep_ballots USIRV/Aspen_2009_Mayor.txt -r 0.05 -gamma 1.1 
    -lambda 0.01 -agap 0.005 -alglog -simlog -json Aspen2009Mayor.json

In the folder SampleOutputs, I have run the above on each of the USIRV
'reported' ballot data files in USIRV and placed the resulting JSON output. 
 
Note that:

-- The current format for accepting 'reported ballots' is a simple one.
We can look at accepting a different format that is more convenient in
the context of a pilot. The current format is structured as follows:

List of integer candidate id's (eg. 1, 2, 3, 4)
A line separator (-+-+-+-+)
Ballot ranking : Number of ballots with this ranking (eg. (3, 2, 1) : 50)

-- We may change the test statistic being used, and in this instance 
the gamma/lambda parameters could be replaced with something different.
This is not a significant change to the way the tool works, it will
just change how we estimate auditing effort for each assertion that
needs to be checked.