abiftool for ABIF

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

ABIF and abiftool

It is important to distinguish between "ABIF" (the format) and "abiftool" (convertion software)

• ABIF — The Aggregated Ballot Information Format provides a concise, aggregated, text-based document to describe the ballots cast in score (cardinal) elections or ranked (ordinal) elections, as well as approval-based and choose-one balloting systems. Discussion of 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 (which was later largely abandoned). The EBNF file (" abif-v0.02.ebnf") is still a useful expression of the format, though.
  Homepage: electowiki.org/wiki/ABIF
  GitHub Repo: github.com/electorama/abif
• abiftool — After the ringleader for ABIF tried (and failed) to understand how to use the "Lark" parsing library for building a Python framework around the .abif format, he started anew in 2023. Thus "abiftool" was born. abiftool hopes to be a generic tool to convert between many election-summary formats once it matures.
  Homepage: this page!
  GitHub Repo: github.com/electorama/abiftool

Conversion of ABIF to/from other formats

This script (abiftool.py) aspires to convert 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

The 2023 version of 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:

• github.com/electorama/abif/issues — to suggest changes to the ABIF Format, or to help move the ABIF specification forward.
• 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.
• 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.

Licensing

The primary author of abiftool.py (Rob Lanphier, a.k.a. "robla") has not yet fully decided on what the long-term license will be (it's currently licensed under GPLv3). As of this writing (in January 2024), the primary author can probably be convinced to switch to an MIT, BSD, or Apache license of some sort, but could decide to go with a more restrictive license (e.g. AGPLv3 or some other strong copyleft). As other contributors contribute under GPLv3, it will become more difficult for the primary author to convince other contributors to change license. Visit electorama/abiftool#1 to discuss this topic.

---

Back to home page: Home