Merge pull request #151 from mggg/3.0.0

3.0.0 Full Release

.github/workflows/test.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       max-parallel: 4
       matrix:
-        python-version: ["3.9", "3.11"]
+        python-version: ["3.9", "3.12"]
 
     steps:
     # Python & dependency installation

.gitignore

@@ -10,4 +10,5 @@ extra_data/
 .venv
 .docs_venv
 docs/_build
-.dev
+.dev
+vote2

CHANGELOG.md

@@ -6,6 +6,77 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+
+
+## [3.0.0] - 2024-08-15
+
+## 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. 
+
+
+## Fixed
+
+
+
+## [2.0.1] - 2024-06-11
 ## Added
 - Created a read the docs page.
 - Add `scale` parameter to `ballot_graph.draw()` to allow for easier reading of text labels.
@@ -33,7 +104,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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.
+- 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.

README.md

@@ -23,14 +23,14 @@ A simple example of how to use VoteKit to load, clean, and run an election using
 
 ```python
 from votekit import load_csv, remove_noncands
-from votekit.elections import STV, fractional_transfer
+from votekit.elections import STV
 
 minneapolis_profile = load_csv("mn_2013_cast_vote_record.csv")
 
 # clean downloaded file to remove edited aspects of the cast vote record
 minneapolis_profile = remove_noncands(minneapolis_profile, ["undervote", "overvote", "UWI"])
 
-minn_election = STV(profile = minneapolis_profile, transfer = fractional_transfer, seats = 1)
+minn_election = STV(profile = minneapolis_profile, m = 1)
 minn_election.run_election()
 ```
 

TODO.md

@@ -0,0 +1,3 @@
+- add some more tests to the dictator, boosted dictator, and plurality veto tests
+- maybe more tests for spatial BGs, but we plan to edit that whole module anyway
+- PV is not passing its test due to an issue with empty ballots being removed, thus messing up the random order

docs/api.rst

@@ -36,26 +36,82 @@ Ballot Generators
 Elections
 ---------
 
-.. automodule:: votekit.elections.election_types   
+.. autoclass:: votekit.elections.election_state.ElectionState
+    :members:
+
+.. autoclass:: votekit.models.Election
+    :members:
+
+
+
+Approval-based
+~~~~~~~~~~~~~~~
+.. automodule:: votekit.elections.election_types.approval.approval
+    :members:
+    :show-inheritance:
+
+
+Ranking-based
+~~~~~~~~~~~~~~
+
+.. automodule:: votekit.elections.election_types.ranking.abstract_ranking
     :members:
     :show-inheritance:
 
-Election State
---------------
+.. automodule:: votekit.elections.election_types.ranking.alaska
+    :members:
+    :show-inheritance:
+
+.. automodule:: votekit.elections.election_types.ranking.borda
+    :members:
+    :show-inheritance:
+
+.. automodule:: votekit.elections.election_types.ranking.boosted_random_dictator
+    :members:
+    :show-inheritance:
+
+.. automodule:: votekit.elections.election_types.ranking.condo_borda
+    :members:
+    :show-inheritance:
 
-.. autoclass:: votekit.election_state.ElectionState
+.. automodule:: votekit.elections.election_types.ranking.dominating_sets
+    :members:
+    :show-inheritance:
+
+.. automodule:: votekit.elections.election_types.ranking.plurality_veto
+    :members:
+    :show-inheritance:
+
+.. automodule:: votekit.elections.election_types.ranking.plurality
+    :members:
+    :show-inheritance:
+
+.. automodule:: votekit.elections.election_types.ranking.random_dictator
+    :members:
+    :show-inheritance:
+
+.. automodule:: votekit.elections.election_types.ranking.stv
+    :members:
+    :show-inheritance:
+
+.. automodule:: votekit.elections.election_types.ranking.top_two
+    :members:
+    :show-inheritance:
+
+Score-based
+~~~~~~~~~~~~
+
+.. automodule:: votekit.elections.election_types.scores.rating
     :members:
     :show-inheritance:
 
 Graphs and Viz.
 ---------------
 .. autoclass:: votekit.graphs.ballot_graph.BallotGraph
     :members:
-    :show-inheritance:
 
 .. autoclass:: votekit.graphs.pairwise_comparison_graph.PairwiseComparisonGraph
     :members:
-    :show-inheritance:
 
 .. automodule:: votekit.plots.mds   
     :members:

docs/index.rst

@@ -41,6 +41,7 @@ repository, where `bug reports and feature requests`_, as well as
    user/tutorial/2_real_and_simulated_profiles
    user/tutorial/3_viz
    user/tutorial/4_election_systems
+   user/tutorial/5_score_based
 
 .. toctree::
     :caption: Social Choice Reference

docs/requirements.txt

@@ -49,7 +49,7 @@ prompt_toolkit==3.0.45
 psutil==5.9.8
 ptyprocess==0.7.0
 pure-eval==0.2.2
-pydantic==1.10.15
+pydantic==2.8.2
 Pygments==2.18.0
 pyparsing==3.1.2
 python-dateutil==2.9.0.post0