ABIF

ABIF stands for "aggregated ballot information format", a format for expressing aggregated ballot sets resulting from elections (either real elections or theoretical elections).

Description

Memphis, Nashville, Chattanooga, and Knoxville are Tennessee's four largest cities, and are used in the "Tennessee example". The map above shows each city's respective placement within the state.

ABIF is a format designed to be a universal format for expressing aggregated ballot sets from elections, regardless of whether voters are asked to provide rankings (i.e. "ordinal voting") or ratings (i.e. "cardinal voting"). The format is loosely based on a format that has been used on the election-methods mailing list and in other places for many years, in which a quantity (of ballots) is followed by a colon, and then a ranking. Here is how the "Tennessee example" is expressed in this ad hoc format:

42:Memphis>Nashville>Chattanooga>Knoxville
26:Nashville>Chattanooga>Knoxville>Memphis
15:Chattanooga>Knoxville>Nashville>Memphis
17:Knoxville>Chattanooga>Nashville>Memphis

The example above works with some election tabulators that are still online. The example above is also compatible with ABIF. Below is a more complicated example of ABIF, expressing the same "Tennessee example" as above. The ABIF example below includes more information than the ad hoc format above, including longer descriptions of the cities, and a "rating" expressed by voters based on their respective distance from the other cities, and comment lines describing the typical sections of an ABIF file:

# Section 1 - metadata
{"title": "Tennessee capitol example"}
{"description": "Hypothetical example of selecting capitol of Tennessee, frequently used on Wikipedia and electowiki."}
# Section 2 - candidate descriptions
=Memph:[Memphis, TN]
=Nash:[Nashville, TN]
=Chat:[Chattanooga, TN]
=Knox:[Knoxville, TN]
# Section 3 - votelines
# Ratings are 400 miles minus crow-flying mileage to city 
42:Memph/400>Nash/200>Chat/133>Knox/45
26:Nash/400>Chat/290>Knox/240>Memph/200
15:Chat/400>Knox/296>Nash/290>Memph/133
17:Knox/400>Chat/296>Nash/240>Memph/45

The section order (and even line order) is purely convention, and is not mandated by the specification. Comments are any line (or portion of a line) that begins with a hash mark ("#"). Lines that begin with an open curly brace ("{") are metadata lines. Lines that begin with an equal sign ("=") are "candlines" (candidate description lines). Lines that begin with numbers are "votelines", where each voteline has roughly the following format:

quantity ":" candtoken [ "/" rating] [ [ ">" or "=" or "," ] candtoken [ "/" rating] ]*

Each line represents "quantity" number of ballots of voters that expressed the preferences represented in the remainder of the line. Each "candtoken" represents a candidate, and are required to be in order of preference if the delimiter is ">" or "=". If comma (",") is the delimeter, then allcandtokensare required to have a "rating" associated with it.

ABIF uses UTF-8 character encoding, but tries to clearly delineate the portions of the file within which arbitrary UTF-8 characters are allowed.

History

The ABIF format has only been called "ABIF" since 2021. However, as early as 1996, people have used the a simpler format.

EM-list format

On the EM-list started in 1996, participants quickly started using the following format to describe "ordinal voting" elections:

quantity ":" candtoken [ ">" or "=" candtoken]*

In April 1996, Rob Lanphier published a Perl script which tabulated elections using something similar to this format (requiring numbers for the candidates). The script was published in The Perl Journal, later that year. Others wrote similar scripts, allowing letters and names to describe candidates. Many messages to the election-methods mailing list over the years also used the format. Below are theoretical election results used the "quantity:candtoken>candtoken" format:

  46: Dole > Clinton=Nader
  20: Clinton > Dole=Nader
  34: Nader > Clinton > Dole

The author (Stephen Eppley) was describing a situation where Dole and Clinton voters truncate their ballots in a theoretical election using an alternative voting system.

ABIF and cardinal elections

In May 2021, "/u/jman722" posted to the /r/EndFPTP subreddit asking "Have you ever noticed that ordinal ballots have a nice, compact, universally understood notation for ballot sets, but notation for cardinal ballots seems to be aLl OvEr ThE pLaCe?". They suggested a format that is similar to the comma-separated values (CSV) format typically offered as an export format in spreadsheets:

12: Allie/5, Billy/5, Candace/4, Dennis/3, Edith/3, Frank/2, Georgie/1, Harold/0
7: Allie/4, Billy/0, Candace/2, Dennis/3, Edith/1, Frank/0, Georgie/5, Harold/3
5: Allie/0, Billy/3, Candace/2, Dennis/3, Edith/4, Frank/5, Georgie/3, Harold/4

Some discussion ensued on reddit and on the EM-list. As part of these discussions of the name, Lanphier suggested "ABIF", which stood for "aggregated ballot image format". Election auditing expert Neal McBurnett disliked that "I" stood for "Image", and thus the "I" came to stand for "Information". Discussions shifted from reddit to GitHub, and continued through the summer of 2021.

In August 2023, User:RobLa published "abiftool.py" on GitHub, hoping this could become a good interchange tool between election result analysis tools.

Test cases

The normative set of test cases are on GitHub, and we'll be expanding them there:

• https://github.com/electorama/abif/tree/main/testfiles

Note: some test cases were designed to fail, and some examples that are marked as passing tests may be marked as "fail" in the future.

Implementations

There are also a slowly but steadily growing suite of tools that can handle ABIF

Actively-developed

ABIF Web Tool (awt)

The ABIF Web Tool ("awt") is a web front-end which accepts ABIF-formatted text in a form field, and optionally returns the tally results using many different algorithms, including Copeland's method, instant-runoff voting, and STAR voting. awt largely relies on "abiflib", which is included in "abiftool".

• Homepage: abif.electorama.com/awt
• Info page: electorama.com/awt

abiftool

abiftool is an implementation in Python also started by User:RobLa, using regular expressions and licensed under GPL 3.0. As of October 2023, this implementation has support for converting from a few formats (e.g. Debian's format, PrefLib format), and may soon have support for converting into many other formats. The tool also has suppport for basic pairwise comparisons.

• Homepage: electorama.com/abiftool
• GitHub repo: github.com/electorama/abiftool

abif test suite

The "abif" repository in the "electorama" project still contains useful tests and EBNF specifying the ABIF format. An early (2021) implementation of ABIF in Python was started by User:RobLa, using the Lark library and licensed under the Apache 2.0 License. This version was originally intended to grow into a credibly useful reference implementation, but at this point, it's mainly useful for the EBNF files describing the syntax of ABIF and for the test files in the repositoy.

• GitHub repo: github.com/electorama/abif

Preferential Voting Tools (pref_voting)

See also: Stable Voting

• Documentation pref-voting.readthedocs.io/

The pref_voting library is part of the suite of software developed by Eric Pacuit and Wesley Holliday to advocate for Stable Voting. pref_voting is a Python library that can be used to study and run elections with different preferential voting methods. There are a few Jupyter Notebooks demonstrating how to use the library in the pref_voting source code repository on GitHub (e.g. testing.ipynb). Instructions for saving elections in ABIF format can be found here: https://pref-voting.readthedocs.io/en/latest/io.html .

VoteLib

github.com/simberaj/votelib/tree/abif — An branch of VoteLib started by Jan Šimbera. VoteLib is "Votelib is a package to evaluate results of elections under various systems. It aims to provide reliable implementations of many voting systems so that they may be evaluated as they are used in real-world conditions and compared. [...] Votelib does not aim to be an end-to-end tool for managing elections; it does not (and will not) provide user interfaces or concern itself with other parts of the election process than determining the result from the votes cast."