README

Google Spreadsheet Voting

Author: Jett Jones

Last docs update: 2021-01-02

Previously Instant Runoff Voting by Chris Cartland and Google Spreadsheet Voting by Darell Ross

What is this Voting Script?

This script allows running a ranked choice vote from a Google Docs Form via a Google Docs Spreadsheet. All configuration is done within the Spreadsheet with little to no programming experience necessary to configure and administrate your vote.

Ranked Choice Voting

• Wikipedia describes RCV well enough: http://en.wikipedia.org/wiki/Ranked-choice_voting

• CGPGrey's five minute video, "The Alternative Vote", also does a great job on YouTube: https://www.youtube.com/watch?v=3Y3jE3B8HsE

In this project, RCV is a method of tallying ranked votes to candidates. Voters rank candidates in a Google Form and the administrator runs a script with Google Apps Script to produce a set of a given size, or a final winner.

Ranked choice from a voter's perspective

1. You get one vote that counts. It comes from your top choice that is still eligible.
2. If a candidate gets a majority of votes, then that candidate wins.
3. If no candidate has majority of all votes, then the candidate with the least votes is removed.
4. If your top choice is removed, the next eligible candidate on your list gets a vote. The process repeats until there is a winner.

Notes about algorithm

• Top N - The count can be configured to stop when a set of candidates of a given size remains.
• No Action - When used for endorsements, an option for 'none of the above' is given special treatment. No Action cannot be eliminated, and becomed the vote for otherwise exhausted ballots.
• Ties - If multiple candidates tie for least votes, there will be a tiebreaker. The Lots tab contains the result of that process. The Lots tab can be written to, if the election uses a physical device like a coin flip.
• Majority - Majority means 50% plus one vote. So in an example where A has 3 votes, and B, C, and D have 1 - A has 50% of the vote, but not 50%+1, so counting would continue to another round.
• It is possible that multiple candidates tie for first place, in which case the result would use a tiebreaker.

Setup a ballot

To create a ballot using this script:

• setup a google form for the ballot
• connect it to a spreadsheet
• attach this script to the spreadsheet

Setting Up the Ballot Form

This script assumes the structure of votes coming out of the google form. This section covers how to setup a form to match.

1. Create a new, blank form on forms.google.com
2. Add an entry for the Secret key, use the type: Short answer.
3. Add a new question for each vote, they'll use the type: Multiple choice grid
   • Add each candidate as a Row.
   • For the columns use 1st 2nd 3rd ... etc, up to the number of candidates.
   • In the bottom right of the question there's a ... menu with two important options to enable:
     • Limit to one response per column
     • Shuffle row order
   • Leave 'Require a response in each row` toggled off.
   • Finally, remember the name you give this question - you'll use it in spreadsheet configuration next.

Connect to a spreadsheet

1. In the Responses tab of the form, in the (...) menu, Select response destination
2. Create a new spreadsheet.

Attach this script

1. Open the newly created spreadsheet.
2. From the Tools menu, select "Script Editor..."
3. In the window that appears, select "Blank Script"
4. Paste the contents of instant-runoff.gs into the script.
5. Save your project with a name of your choice.
6. Return to your Google Sheet and refresh the page.

After a moment, a new "VOTING" menu should appear and the script should create several tabs ( Configure, Credentials, Results, FilteredVotes, and Lots ). The menu option in the VOTING menu titled "Initialize Spreadsheet" can re-run this setup at any time.

The remaining steps will happen in that Configure tab - the other two are used while tallying.

Configure the spreadsheet

The Configure sheet has one column of setting names, and a second column of values. This section describes the settings.

• Use Keys - keys are optional, but prevent double voting or allowing more folks than you intend to use your form. When active, the 'Credentials' tab should contain a list of credentials to accept.
• Vote - the name, in the original google form, of the question that represents a vote.
• Top N - If the value is greater than 1, the tally will stop when that number of candidates remain.
• Use No Action - for votes where 'no winner' is an option, that choice cannot be eliminated between rounds.
• Sheet Per Round - The count runs quickly, so this can be enabled to capture the state of votes before each elimination.
• Key Column - When using keys, this column in the responses will be matched against credentials.
• Other Columns - If set, ignores the rightmost N columns in the responses sheet. This supports a special case of adding tracking columns to the responses page. Two common cases - marking which voters with invalid credentials were contacted, or marking ballots with missing middles (eg. voting only for 1st, 4th, 5th).

Running an Election

Setting Secret Voting Keys

Giving each vote a short key ahead of time ensures:

• each voter has only one vote entry
• they can return and change their vote if they like.

1. Open the Elections Spreadsheet.
2. Select the "Credentials" sheet.
3. On the third column under the heading of "Credential", enter one secret key per line.
   • These keys should be distributed, one per person, to the voters. Voters later enter these keys into the form.
   • Secret keys can be any non-blank value
4. Set the B1 cell of the Configuration sheet to yes.
   • this tells the tally step to only count votes with the given keys.

Running the Vote

After all voters have their individual secret keys, distribute a link to the live form and wait for them to fill in the form.

Tallying the Vote

From the menu "VOTING", select the "Tally Votes" option. For less than 1000 votes, this should take a few seconds. When it is complete, the Results sheet will contain the results for each vote, with details for of the rounds of counting and elimination.

Links

• The google form is inspired by xFanatical
• Wikipedia Ranked Choice Voting
• CGPGrey "The Alternative Vote"