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. The EBNF file (" abif-v0.02.ebnf") represents a vaguely authoritative source for the syntax of ABIF, and the test suite included may be helpful. The "Lark" parsing library is used to read the EBNF, and but development largely shifted to abiftool (and the included abiflib) in 2023.
  Homepage: electowiki.org/wiki/ABIF
  GitHub Repo: github.com/electorama/abif
• abiftool — "abiftool" is a generic tool to convert between many election-summary formats, and as the primary test harness for "abiflib". abiftool can convert ".abif" files to-and-from "jabmod", and (as of June 2024) is capable of converting some other election summary formats into ABIF. The abiflib library is not only used for abiftool; it is also used for "awt"
  Homepage: this page!
  GitHub Repo: github.com/electorama/abiftool
• awt — a.k.a. the "ABIF web tool". This provides the ability to visualize Condorcet/Copeland elections, RCV/IRV elections, and STAR elections via input of the ABIF format into a web form.
  More information: the "awt" information page on electorama
  Homepage: abif.electorama.com
  GitHub Repo: github.com/electorama/awt

Conversion of ABIF to/from other formats

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

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