v3.0.0

This is a major update to VoteKit that includes some breaking changes for the API and a major refactoring of the code base to make it more organized, maintainable, and (hopefully) easier to contribute to in the future.

Added

• The election methods thanks to @kevin-q2. The newest election methods are PluralityVeto,
  RandomDictator, and BoostedRandomDictator.
• More comprehensive tests for the Ballot class.
• More comprehensive tests for all of the election types.
• More comprehensive tests for the PreferenceProfile class.
• Tests for potential errors in the BallotGenerator classes.

Changed

• Moved the following election methods to sorted folders in src/votekit/elections/election_types:

  • approval
    • Approval
    • BlockPlurality
  • ranking
    • RankingElection
    • Alaska
    • BoostedRandomDictator
    • Borda
    • CondoBorda
    • DominatingSets
    • PluralityVeto
    • Plurality
    • SNTV
    • RandomDictator
  • scores
    • GeneralRating
    • Limited
    • Rating
    • Cumulative

• Updated / added the following methods to src/votekit/utils.py:

  • ballots_by_first_cand
  • remove_cand
  • add_missing_cands
  • validate_score_vector
  • score_profile
  • first_place_votes
  • mentions
  • borda_scores
  • tie_broken_ranking
  • score_dict_to_ranking
  • elect_cands_from_set_ranking
  • expand_tied_ballot
  • resolve_profile_ties

• Changed the way that the ElectionState class operates. It now operates as a dataclass
  storing the following data:

  • round_number: The round number of the election.
  • remaining: The remaining candidates in the election that have not been elected.
  • elected: The set of candidates that have been elected.
  • eliminated: The set of candidates that have been eliminated.
  • tiebreak_winners: The set of candidates that were elected due to a tiebreak within a round.
  • scores: The scores for each candidate in the election.

• The PreferenceProfile class is now a frozen dataclass with the idea being that, once the
  ballots and candidates for an election have been set, they should not be changed.

  • Several validators have also been added to the PreferenceProfile class to ensure that
    the ballots and candidates are valid.

• Updated all documentation to reflect major changes in the API of the package.

New Contributors

• @kevin-q2 made their first contribution in #130
• @peterrrock2 made their first contribution in #151

Full Changelog: v2.0.1...v3.0.0

v2.0.1

This is a minor patch of votekit. It fixes minor bugs in the slate methods, adapts to the new csv format in the scot-elex repo, and updates some plotting functions.

Added

• Created a read the docs page.
• Add scale parameter to ballot_graph.draw() to allow for easier reading of text labels.
• Allow users to choose which bloc is W/C in historical Cambridge data for CambridgeSampler.

Changed

• Updated tutorial notebooks; larger focus on slate models, updated notebooks to match current codebase.
• Removed the seq-RCV transfer rule since it is a dummy function, replaced with lambda function.
• Update plot MDS to have aspect ratio 1, remove axes labels since they are meaningless in MDS.
• Update all BLT files in scot-elex repo to be true CSV files, updated load_scottish accordingly. #123 #129

Fixed

• Fixed bug by which slate-PlackettLuce could not generate ballots when some candidate had 0 support. #131
• Updated various functions in the ballot generator module to only generate ballots for non-zero candidates.
• Fixed one bloc s-BT pdf, which was incorrectly giving 0 weight to all ballot types.

Full Changelog: v2.0.0...v2.0.1

v2.0.0

This update will break some of the backwards compatibility, so we have incremented the major version number.

Added

• A PreferenceInterval class.
• MCMC sampling for both BradleyTerry ballot generators.
• Add print statement to BallotGraph so that when you draw the graph without labels, it prints a dictionary of candidate labels for you.
• Add an IRV election class, which is just a wrapper for STV with 1 seat.
• Add default option to Borda election class, so users do not have to input a score vector if they want to use the traditional Borda vector.
• Add several methods to PairwiseComparisonGraph. Added two boolean methods that return True if there is a condorcet winner or if there is a condorcet cycle. Added two get methods that return the winner or the cycles. Cached the results of dominating_tiers and get_condorcet_cycles.
• Added optional to_float method to first_place_votes if users want to see them as floats instead of Fractions.
  -Added a by_bloc parameter to generate_profile. If True, this returns a tuple, the first entry of which is a dictionary of PreferenceProfiles by bloc. The second entry is the aggregated profile. This is very helpful for analyzing the behavior of a single bloc of voters. Defaults to False for backwards compatibility.
• Created a Cumulative ballot generator class. The Cumulative class works like PL, but samples with replacement instead of without. The ranking order does not matter here, simply that candidates are listed on the ballot with multiplicity.
• Created a HighestScore election class. This takes in a profile and a score vector, and returns the candidates with highest scores. There is a lot of flexibility in the score vector, so this class can run things like Borda, cumulative, etc.
• Created a Cumulative election class which is just a subclass of HighestScore with the score vector set to all 1s. Thus anyone appearing on the ballot gets one point for each time they appear.
• Wrote an __add__ method for PreferenceProfile that combines the ballot lists of two profiles.
• Created utility functions to compute the winners of a profile given a score vector, as well as to validate a score vector (non-negative and non-increasing).
• Created a shortPlackettLuce class which allows you to generate ballots of arbitrary length in the style of PL.
• Added tests for __add__ method of PreferenceProfile.
• Added SlatePreference model and tests.

Changed

• Change the way the condense_ballots() method works in profiles. Rather than altering the original profile, it returns a new profile. This gives users the option to preserve the original profile.

• Alter STV class so that the remaining candidates are always listed in order of current first place votes.

• Made PlackettLuce a subclass of shortPlackettLuce.

• Change PlackettLuce, BradleyTerry, and Cumulative ballot generators to have name_ prefix. This is in contrast to the slate_ models we have introduced.

• Speed improvements for various ballot generators.

• pref_interval_by_bloc is now pref_intervals_by_bloc in all ballot generators. This is now a dictionary of dictionaries, where the both sets of keys are the blocs, and the values of the sub-dictionaries are PreferenceInterval objects. The slate models require that we sample from the uncombined PreferenceInterval objects, while the name models require that we combine the PreferenceInterval objects using cohesion parameters.

• MDS plot functionality, splitting it into compute_MDS which computes the coordinates, and plot_MDS which plots them. Made because the computation is the most time intensive.

Fixed

• Fixed an error in the PreferenceProfile tail method.
• Errors in bloc labeling in CambridgeSampler.

Deprecations

• Deprecated PL and BT to name_PL and name_BT

Full Changelog: v1.1.1...v2.0.0

v1.1.1

VoteKit 1.1.1 is a patch update aimed primarily at extending the functionality of VoteKit. More specifically, this release implements score-based voting systems, and does so without editing the ballot class. To use a score-based system, you have to decide how many points to assign to each position of the ranking. This is flexible enough to handle things like cumulative and approval voting.

This update also includes some additional functionality that was included after creating and running some tutorials on usage of the software. For recordings and copies of some of these notebooks, please see the main website for VoteKit.

Key Changes

• Change the way the condense_ballots() method works in profiles. Rather than altering the original profile, it returns a new profile.
• Altered STV class so that the remaining candidates are always listed in order of current first place votes.
• Added print statement to BallotGraph so that when you draw the graph without labels, it prints a dictionary of candidate labels for you.

Additions

• Added a by_bloc parameter to generate_profile. If True, this returns a dictionary of PreferenceProfile objects by bloc. Defaults to False for backwards compatibility.
• Created a Cumulative ballot generator class. The Cumulative class works like PL, but samples with replacement instead of without. The ranking order does not matter here, simply that candidates are listed on the ballot with multiplicity.
• Created a HighestScore election class. This takes in a profile and a score vector, and returns the $m$ candidates with highest scores.
• Created a Cumulative election class which is just a subclass of HighestScore with the score vector set to all 1s.
• Wrote an __add__ method for PreferenceProfile that combines the ballot lists of two profiles.
• Created utility functions to compute the winners of a profile given a score vector, as well as to validate a score vector (non-negative and non-increasing).
• Add an IRV election class, which is just a wrapper for STV with 1 seat.
• Add default option to Borda election class, so users do not have to input a score vector.
  Add several methods to PairwiseComparisonGraph.
  • Added two boolean methods that return True if there is a condorcet winner or if there is a condorcet cycle.
  • Added two get methods that return the winner or the cycles. Cached the results of dominating_tiers and get_condorcet_cycles.
• Added optional to_float method to first_place_votes if users want to see them as floats instead of Fractions.

Bug Fixes

• Fixed an error in the PreferenceProfile tail method.

Full Changelog: v1.1.0..v1.1.1

v1.1.0

Votekit 1.1.0 features a number of important functional and syntactical changes to the core Ballot, PreferenceProfile, and ElectionState objects. It also includes changes to ballot generation methods to output the correct number of ballots and allow for user-defined block names in the CambridgeSampler class. This release marks an overhaul to the library's documentation, and the addition of section explaining the social choice theory that underpins Votekit's functionality.

Key Changes

• Method names for ElectionState methods
• Caches for the results of run_election()
• Ballot objects made immutable, using Pydantic dataclass
• Parameter names for CambridgeSampler
• BallotGraph now always displays vote totals for a ballot
• ElectionState now prints the current round whenever printing
• load_blt became load_scottish
• plot_summary_stats always displays candidates in order inputted
• PreferenceProfile data frame now has Percent column, removed the Weight Share column
• Ballot object can take floats and integers as weights
• Ballot attribute voter changed to voter_set

Additions

• Added to_dict(), to_json() functions for ElectionState
• Scores attribute to ElectionState
• _rename_blocs method to CambridgeSampler to rename blocs to historical names.
• Added reset and run_to_step methods to Election class
• sort_by_weight parameter to head and tail methods of PreferenceProfile
• received_votes parameter to get_candidates method of PreferenceProfile
• __str__ method for Ballot

Bug Fixes

• Multiple winners correctly ordered based off previous round's vote totals
• CambridgeSampler correctly computes the frequency of opposing bloc ballots
• PreferenceProfile no longer rounds all weights to integer when printing

Special thanks to Chris Donnay (@cdonnay) who made significant contributions to this release and is responsible for the improved tutorials and social choice theory sections of the documentation!

v1.0.2

• bug fixes to election types
• lowered pandas version requirements for wider compatibility

v1.0.1

• added elections submodule (e.g from votekit.elections import STV, fractional_transfer)
• renamed CVR loaders to load_csv and load_blt
• better documentation

v1.0.0

Version 1.0

• User determined options for breaking ties
• Ballot Simplex object, refactored construction for ballot generator classes
• IC/IAC with generalized arguments
• Fixed package imports
• Improved handling of tied rankings within ballots
• Optimization for election helper functions

v0.2.0

Update pyproject.toml

v0.1.1

• Added MDS plotting
• Updated metrics to include: earth mover and Lp distances
• Bug fixes to PreferenceProfile and ballot generators
• More docstrings