abiftool for ABIF

abiftool is Python-based software for working with ABIF files. "What is ABIF" you may ask? Read on to learn more....

News

abiftool 0.31.0 is out (July 11, 2025) — A release about SF 2024 elections, FPTP support, improved testing, and bug fixes for added fun!

Handling of San Francisco's latest JSON-based CVRs.
Initial implementation of First-Past-The-Post (FPTP) tabulation.
Substantial refactoring of abiflib, including renaming sub-libraries and adding deprecation stubs.
Much more robust pytests and more of them.
Many micro-features hidden in command-line options.
General code cleanup and major improvements throughout.

See the announcement to the ES list to learn more.

`abiftool` in a nutshell

"abiftool" is a command-line tool to convert between many election-summary formats, and its companion tool (fetchmgr) fetches many published election results from the Internet and processes those results. The abiftool bundle includes the powerful "abiflib" Python library which not only handles processing of many different election aggregation formats, but tallies the results using many different election methods (including "first past the post", IRV/RCV, Condorcet/Copeland, and STAR).

Core to abiflib is a JSON-based structure called jabmod, which is a structured representation of an election. The jabmod structure is easy for programmers to understand, and provides a comprehensive view of an election. "jabmod" is short for "JSON ABIF Model". abiftool can convert ".abif" files to-and-from "jabmod", and is capable of converting many election summary formats into ABIF.

For Python developers that have pip installed on their computer, installation of abiftool and abiflib is as simple as typing the following command:

$ pip install abiftool

It's also possible to check out abiftool from git:

https://github.com/electorama/abiftool

ABIF and `abiftool`

The Aggregated Ballot Information Format (or "ABIF") provides a concise, aggregated, plain-text document to describe the ballots cast in score (cardinal) elections or ranked (ordinal) elections, as well as approval-based and choose-one balloting systems.

Forms of the format were used as early as 1996 on the Election-Methods (EM) Mailing List, among other places. Over time, many online, form-based tools were created to parse forms of the format. Formalization of the format the format began in 2021, and an "abif" repo (https://github.com/electorama/abif) was started on GitHub, where discussion occured, and some early code was checked in. The EBNF file (" abif-v0.03.ebnf") represents a vaguely authoritative source for the syntax of ABIF, and the test suite included may be helpful. As of July 2025, the code in the electorama/abif repository has a simple parser that uses the "Lark" parsing library to converts ABIF into jabmod

See the following links about ABIF to learn more:

The ABIF homepage: — https://electorama.com/ABIF
The ABIF GitHub Repo — https://github.com/electorama/abif

`awt` — the ABIF web tool

Folks that aren't familiar with Python programming (or programming in general) may appreciate the "ABIF web tool". This provides the ability to visualize elections expressed in ABIF by entering ABIF into a web form. awt then tallies the given election using the Condorcet/Copeland method, the RCV/IRV method, and the STAR method. into a web form.

Links

Live awt application — https://abif.electorama.com
awt development page — https://electorama.com/awt
awt source code — https://github.com/electorama/awt

Conversion of ABIF to/from other formats with abiftool

abiftool converts between ABIF and other commonly-used electoral expression formats. abiftool.py calls out to "abiflib", which is a Python conversion library between various election summary formats that can be found in the electorama/abiftool source repository (as "electorama/abiftool/abiflib").

Input formats

abiftool/abiflib accepts input in the following formats:

ABIF (or ".abif") — (as described above)
Debian elections format (provided as ".txt") — The Debian project has been performing their elections using the "Schulze" method (a Condorcet method) since 2003, and a Condorcet-inspired method before that. The Schulze method is also known as "Clone Proof SSD". See the 2003 Debian " Constitutional Amendment: Condorcet/Clone Proof SSD Voting Method" for the algorithm and other information, and see " leader2003_tally.txt" for an example of the text format, taken from the 2003 Debian Project Leader Election.
.jabmod — this is a JSON model for ABIF, and mainly used as an internal format for abiftool. This format is not stable (as of January 2024).
PrefLib format (often saved as ".toi" or ".toc") — The website " PrefLib.org" has a fantastic collection of electoral data, converted to their own format. See 00005-00000002.toi for a PrefLib example from the Burlington 2009 Mayoral Race
.widj - An obsolete format, which was the JSON representation used by " Electowidget". This format was developed circa 2005, and still can be found on electowiki.org at the following location: https://electowiki.org/wiki/User:RobLa/Electowidget

Output formats

The 2023 version of abiftool/abiflib converts to the following formats:

ABIF (or ".abif") — (as described above)
.jabmod — (as described above)
Various text and HTML formats — As of January 2024, abiftool.py does rudimentary pairwise voting calculations based on the input, and has a command-line switch for performing these calculations prior to output.

Community

Please join the Electorama community to meet other people interested in ABIF

Contributing bug reports and feature ideas

Please file issues in the abiftool.py issue tracker if you notice problems with the tool that likely need to get fixed sooner rather than later. Please note your issues in one of the GitHub repos to help make this project go faster:

https://github.com/electorama/abif/issues — to suggest changes to the ABIF Format, or to help move the ABIF specification forward.
https://github.com/electorama/abiftool/issues — for Python coding discussions, and to help add more formats to the tool.

Chat/Email/Forum

There are many communication channels used by the Electorama community and folks interested in ABIF.

Chat : electorama.com/discord — the #general channel on the Electorama Discord server is a good place to ask about ABIF.
Email :
- [EM] list — There has been a bit of discussion about ABIF on the election-methods list (also known as the "[EM] list"), and the primary author of abiftool has been hosting this mailing list since 1996.
- [ES] list — This mailing list was started in 2024 for software developers to talk about election software. It's very low traffic right now, but no guarantees it will stay that way.
Forum : github.com/electorama/abif/discussions — Though the "abiftool" repo on GitHub doesn't have a discussion forum, the "abif" repo does. Feel free to use the "abif" forum to ask questions about "abiftool".

Future work

There are many tools and formats out there, and (as of January 2024), much work to be done. Visit electorama/abif#29 to discuss this topic.

License

abiftool is currently licensed under GPLv3. Visit electorama/abiftool#1 to discuss licensing, or email Rob Lanphier (robla@gmail.com).

Back to home page: Home