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 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 is a theoretical election tha that used the "quantity:candtoken>candtoken" format:

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

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

• github.com/electorama/abif — An early (2021) implementation in Python started by User:RobLa, using the Lark library and licensed under the Apache 2.0 License. This version was intended as a reference implementation, but at this point, it's mainly useful for the EBNF files describing the syntax of ABIF.
• github.com/electorama/abiftool — A later (2023) 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.
• 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."