Universal RCV Tabulator
The Universal RCV Tabulator is a free, open-source application designed to quickly and accurately tabulate a wide variety of ranked choice voting (RCV) elections. It allows users to:
- Create contest configuration files using a graphical user interface (GUI)
- Validate contest configuration files to ensure they are well-formed, and all values are within expected ranges
- Tabulate a contest
A contest configuration file specifies:
- Which tabulation rule variations to use
- A list of registered candidates
- Paths to one or more cast vote record (CVR) files
- Output formatting options (contest name, date, jurisdiction, etc.)
The Tabulator produces the following as output:
- A summary .csv file containing round-by-round vote totals for each candidate and the eventual winner(s)
- A summary .json file containing additional information which can be used by external tools for visualizing contest results
- A detailed audit .log file describing how every ballot was counted in each round over the course of the tabulation
Installing and Launching the Tabulator
Method 1 (Easy): Pre-Compiled Version
Download the pre-compiled Tabulator for your OS from the GitHub releases page.
Note: this download should be a "jlink image", which means you don't even need to have Java installed on your machine to run it!
Unzip the file, navigate to the
bindirectory, and launch the RCV Tabulator GUI by running the
rcvscript if using MacOS or Linux, or
rcv.batif using Windows.
Method 2 (Less Easy): Compile and Run Using Gradle
Install JDK 11 or higher, and make sure your Java path is picking it up properly by verifying that the following command returns the expected version:
$ java -version
If the expected version isn't returned, you'll need to follow the instructions here on how to set your Java path.
Download the zip of the source code from GitHub and unzip it, or install git and use the following command at the terminal / command prompt to clone a local copy on your machine:
$ git clone https://github.com/BrightSpots/rcv.git
Use the provided version of Gradle to build and run the code from the terminal / command prompt to start the RCV Tabulator GUI:
$ cd rcv-master(or, if you cloned the repo using git:
$ ./gradlew run(or, if you're on Windows:
If you get a "permission denied" error in Linux or MacOS, you need to mark the script as executable with:
$ chmod 777 gradlew
Encrypting the Tabulator Directory
For security purposes, we strongly recommend applying password encryption (e.g. 256-bit SHA) to the directory containing the Tabulator, config files, CVR files, and any other related files.
Mac OS has built-in encryption capability that allows users to create encrypted disk images from folders using Disk Utility (see "Create a secure disk image").
Configuring a Contest
The GUI can be used to easily create, save, and load contest configuration files (which are in .json format). These files can also be created manually using any basic text editor, but this method isn't recommended.
In either case, please reference the config file documentation when configuring a contest.
Warning: Using shortcuts, aliases, or symbolic links to launch the Tabulator is not supported; doing so may result in unexpected behavior. Also, please avoid clicking in the command prompt / terminal window when starting the Tabulator GUI, as it may halt the startup process.
Loading and Tabulating a Contest
The Tabulator includes several example contest configuration files and associated CVR files.
- Click "File > Load..." in the menu and navigate to the
sample_inputfolder (if you used Method 2 to install the Tabulator, navigate to the
- Open one of the folders listed here and select the config file (it will have the
- Click on the configuration tabs (Output, CVR Files, Candidates, Required Rules, Optional Rules) to see how this contest is configured.
- Click "Tabulation > Validate" in the menu to check if this configuration is valid. You will see the results in the console at the bottom of the main window.
- Click "Tabulation > Tabulate" in the menu to tabulate the election. You will see the results in the console, including the location of the output files.
Alternatively, you can run the Tabulator using the command-line interface by including the flag
-cli and then supplying a path to an existing config file, e.g.:
$ rcv -cli path/to/config
Or, if you're compiling and running using Gradle:
$ gradlew run --args="-cli path/to/config"
You can also activate a special
convert-to-cdf function via the command line to export the CVR as a NIST common data format (CDF) .json instead of tabulating the results, e.g.:
$ rcv -cli path/to/config convert-to-cdf
This option is available in the GUI by selecting the "Conversion > Convert CVRs in Current Config to CDF" menu option.
Or, again, if you're compiling and running using Gradle:
$ gradlew run --args="-cli path/to/config convert-to-cdf"
Finally, there's a
convert-dominion-to-generic-csv option as well for converting Dominion JSON CVRs into a standardized, generic .csv format:
$ rcv -cli path/to/folder/containing/jsons convert-dominion-to-generic-csv
This option is available in the GUI by selecting the "Conversion > Convert Dominion to Generic Format..." menu option.
Viewing Tabulator Output
Tabulator output file names automatically include the current date and time, e.g.
2019-06-25_17-19-28_summary.csv. This keeps them separate if you tabulate the same contest multiple times.
Look in the console window to see where the output spreadsheet was written, e.g.
2019-06-25 17:19:28 PDT INFO: Generating summary spreadsheet: /rcv/test_data/2018_maine_gov_primary_dem/output/2019-06-25_17-19-28_summary.csv...
The summary spreadsheet (in .csv format), summary .json, and audit .log files are all readable using a basic text editor.
Note: If you intend to print any of the output files, we strongly recommend adding headers / footers with page numbers, the file name, the date and time of printing, who is doing the printing, and any other desired information.
Bright Spots Developers
- Jonathan Moldover
- Louis Eisenberg
- Hylton Edingfield