Skip to content

README.md

Latest commit

 

History

History
130 lines (96 loc) · 6.19 KB

README.md

File metadata and controls

130 lines (96 loc) · 6.19 KB

Rank Choice Voting (RCV) Google Apps Script Project

This project provides a complete solution for running Ranked Choice Voting (RCV) and multiple Condorcet voting methods using Google Sheets and Google Forms. It includes scripts to generate a ranked-choice voting form, process the results, and display step-by-step elimination rounds and Condorcet analyses.

Features

  • Google Sheets Add-on Menu:
    Adds a custom "Voting and Ballot Tools" menu to your Google Sheet for creating forms and processing results.

  • Automated Google Form Creation:
    Generates a Google Form for voters to rank candidates. Candidate names and descriptions are automatically pulled from your sheet and displayed in the form to help voters make informed choices.

  • RCV Processing:
    Processes form responses using the Ranked Choice Voting method, including:

    • Multi-round elimination with vote redistribution
    • Automatic tie-breakers (second-choice and last-place votes)
    • Comprehensive candidate status tracking
    • Visual HTML results table with elimination details

  • Condorcet Methods:
    Supports multiple Condorcet voting methods with integrated UI dialogs, including:

    • Basic Condorcet (pairwise comparison) — Identifies a candidate who beats every other candidate in head-to-head matchups. If no such candidate exists due to a cycle (A beats B, B beats C, C beats A), no winner is declared.
    • Schulze Method — Uses the "strongest path" algorithm to resolve cycles by finding the candidate with the strongest chain of victories. Particularly robust for handling complex voting patterns.
    • Ranked Pairs (Tideman) — Locks in pairwise victories in order of strength (largest margin first) while avoiding cycles. Creates a definitive ranking by building an acyclic graph of victories.
    • Minimax (Simpson) — Selects the candidate whose worst pairwise defeat is the smallest. Minimizes maximum opposition, making it resistant to strategic voting.

    Results are displayed in a formatted dialog for easy comparison across methods.

  • Step-by-Step Results:
    Outputs detailed elimination rounds to a dedicated "RCV Processing" sheet for transparency.

  • Dialog Results:
    Shows the winner(s) or tie status in a user-friendly dialog, including:

    • Winner announcement or tie notification
    • HTML-formatted candidate summary table
    • Status, vote counts, and elimination details for all candidates
    • Works for both RCV and Condorcet analyses

Setup

  1. Clone or copy this repository to your local machine.

  2. Prepare your Google Sheet:

    • Create a sheet named Candidates with the following columns:
      • Column 1: Candidate Name
      • Column 2: Candidate Description (including book title, if applicable) - This will be displayed in the form to help voters make informed choices
    • Create a sheet named RCV Processing for detailed elimination round logs
    • Optionally, add more sheets as needed.

  3. Deploy scripts:

    • Use clasp to push the scripts to your Apps Script project, or copy them into the Apps Script editor attached to your Google Sheet.

  4. Open your Google Sheet.

    • You should see a new menu: Voting and Ballot Tools.

Usage

  1. Create the RCV Form:

    • From the Voting and Ballot Tools menu, select Create Ballot Form.
    • A dialog will appear with a link to the generated Google Form.
    • The form will include candidate descriptions to help voters make informed choices.
    • Share this link with your voters.

  2. Collect Votes:

    • Voters fill out the form, ranking all candidates.

  3. Run RCV Analysis:

    • Once voting is complete, select Run RCV Analysis from the menu.
    • A dialog will display:
      • The winner (or tie status if unresolved)
      • A comprehensive candidate summary table showing:
        • Current status (Winner, Active, Eliminated, No Votes)
        • Vote counts
        • Elimination round (if applicable)
        • Reason for elimination
    • For step-by-step ballot redistribution details, view the RCV Processing sheet.

  4. Run Condorcet Analysis:

    • Select Run Condorcet Analysis from the menu to see results for all supported Condorcet methods.
    • Results are displayed in an easy-to-read dialog format showing winners for each method:
      • Basic Condorcet (pairwise comparison)
      • Schulze Method
      • Ranked Pairs (Tideman)
      • Minimax (Simpson)
    • Useful for comparing different voting method outcomes on the same ballot data.

Files

  • onOpen.js — Adds the custom menu and handles UI dialogs for RCV and Condorcet results.
  • createRCVform.js — Builds the Google Form from your candidate list, including helper functions loadCandidates() and loadBallots() for data loading.
  • processRCV.js — Processes the RCV results with comprehensive tie-breakers, elimination logic, and candidate status tracking.
  • processCondorcet.js — Implements and analyzes four Condorcet voting methods.
  • cleanResponses.js — Utility functions for cleaning up old forms and response sheets.
  • testRCV.js — Contains test cases for validating the RCV logic.
  • .claspignore — Specifies files/folders to ignore when pushing with clasp.
  • .gitignore — Specifies files/folders to ignore in Git.
  • README.md — This file.

Customization

  • Candidate Descriptions:
    Edit the Candidates sheet to update candidate names and descriptions. Descriptions are displayed in the voting form to help voters make informed decisions.

  • Tie-breaker Logic:
    The script uses second-choice votes (fewest) and last-place votes (most) as sequential tie-breakers. You can modify the breakTie() function in processRCV.js to adjust this logic.

  • Form Appearance:
    Modify the form title, description, and layout in createRCVform.js to customize the voting experience.

Requirements

  • Google Sheets
  • Google Apps Script (via the Script Editor or clasp)
  • Google Forms (created automatically by the script)

License

MIT License

Questions or issues?
Open an issue or submit a pull request!

Note:
This project was developed with the assistance of GitHub Copilot AI.

© Stuart Donaldson (F3 Little John - Puget Sound region)