We probably shouldn't reinvent the wheel and write a whole new ballot-scanner; there may be existing open-source projects that can accurately detect the optical-scan marks, and we should use one of those if possible.

Some voters may have filled in bubbles completely, or made a mark in the bubble but not even partially “filled” the bubble in any sense.

We need two things:

• Scanning the voter ID number (ten columns, one per digit)
• Scanning the candidate selections (as many as 60 on a page)

If necessary, the voter ID number can be represented as a series of 10-candidate “races”, and the “winners” converted into the digits of the ballot's voter ID number in a post-processing step.

Brandon Harami (a candidate) tweeted today that the posted results have changed, with a couple of screenshots. I grabbed copies of the pages yesterday and just downloaded a fresh set, so it'd be possible for me to diff them.

#4 may include a tool to convert the HTML files to digestible CSVs; this issue covers a new tool to diff those CSVs and report:

• which candidates' vote totals changed
• the old/delta/new numbers
• which candidates entered or exited the top 7 for their gender category (i.e., became a winner or loser)

Rather than only assuming the HTML pages are in a directory with a constant name, there should be an option to specify a path to that directory.

Using this option should foreclose other analyses like the ballot inventory (though there should probably be similar options for those analyses, and using multiple such options should deliver whatever analyses are requested).

There should also be an option to direct the CSV output to a file at a specified path.

If you have a copy of all the Assembly District pages with the posted results (including vote counts!) on them, it should be possible to compare those vote counts to our own counts of votes found in valid ballots.

This will likely involve using Beautiful Soup to scrape the HTML in each file.

analyze.py generates a CSV file where one column is the voter ID number scanned from each ballot (depending on #1). If the scan yielded a partial number (either because it was incompletely filled in or couldn't be scanned confidently), a human will need to look at that ballot to see whether any missing digits can be filled in.

There should be a tool with usage like:

./update-voter-ID.py path/to/ballot.pdf correct-voter-ID-number

that will update the appropriate row for that ballot in the CSV.

The same tool could have an option --list-needed that lists off ballots with partial or missing voter ID numbers.

There needs to be a tool, analyze.py, that generates a report summarizing the results (as best it can, depending on whether #1 is present) and an index of ballots by Assembly district, voter ID number, etc.