Animations for STV Elections #249

prismika · 2025-07-25T16:08:30Z

Pursuant to issue #222. This PR adds support for animating STV elections using Manim. Given a votekit STV election called election, the user can render an animation using, for example,

animation = STVAnimation(election, title=f"Animation of STV Election")
animation.render(preview=True)

Here is an example of a rendered scene.

ElectionScene2.mp4

This PR is a draft. I have yet to write robust testing for the animation pipeline (such as snapshot testing). I also have yet to implement a few requested features:

Letting users specify which candidates are on screen, batching offscreen eliminations into a single animation event.
Letting users specify nicknames for candidates to appear onscreen.
"Light mode"

Before implementing these I wanted some feedback on my code so far.

Thanks!

…with empty STVAnimation class.

…imation branch. Add animations module with empty STVAnimation class.

- Remove double underscores - Remove wildcard imports - Change votekit imports to local imports - Minor changes

…ll functions.

…mutate.

cdonnay

Hi @prismika. Switching computers here so just submitting a partial review for now, will pick it back up in an hour or so.

src/votekit/animations.py

cdonnay · 2025-07-25T17:14:02Z

src/votekit/animations.py

+            dict: A dictionary whose keys are candidate names and whose values are themselves dictionaries with details about each candidate.
+        """
+        candidates = {
+            name: {"support": support}


Do you anticipate having to include other information about the candidates later on? If yes, I can see why the nested dict structure is used. if not, this could just be a dict.

Yes, candidate nicknames will go here as well.

src/votekit/animations.py

cdonnay · 2025-07-25T17:15:37Z

src/votekit/animations.py

+        self.rounds = self._make_event_list(election)
+        self.title = title
+
+    def _make_candidate_dict(self, election: STV) -> dict:


Can you be more specific about type setting here? dict[str, dict[str, float]] for example.

This is now dict[str, dict[str, object]]

cdonnay · 2025-07-25T18:00:29Z

src/votekit/animations.py

+        Returns:
+            List[dict]: A list of dictionaries corresponding to the rounds of the election. Each dictionary records salient attributes of the corresponding round.
+        """
+        events = []


Do you know ahead of time how long this list will be? If so it might be more efficient to pre-populate it with dummy entries.

src/votekit/animations.py

cdonnay

Alright review complete!

This looks great already! I think you should feel confident moving onto your other todos.
I'd encourage a little more modularization. You can see the code for PreferenceProfile as an example of super tiny private methods that build into the bigger methods. Peter is a big fan of keeping functions short.

cdonnay · 2025-07-25T19:51:10Z

src/votekit/animations.py

+            elected_candidates = []
+            for fset in election_round.elected:
+                if len(fset) > 0:
+                    (name,) = fset


Does assume only one candidate is elected at a time? I.e. that the fset has exactly one element?

Ah it assumes the fset has one candidate, but there can be multiple fsets. Can you double check that the STV election class never elects two cands in one fset? Or add a check here for that?

I replaced this code with a list comprehension like the ones that exist throughout the codebase. Of the form:
[c for s in election_round.elected for c in s]

cdonnay · 2025-07-25T19:51:41Z

src/votekit/animations.py

+                event_type = "win"
+                elected_candidates_str = elected_candidates[0]
+                for candidate_name in elected_candidates[1:]:
+                    elected_candidates_str += ", " + candidate_name


What exactly does this do? Formats the name of the elected cand?

Or concatenates all of the names of all of the winners? If it's this one, can you do this with a .join statement on a list?

I did not know you could do this with a join! It's slick. Added.

cdonnay · 2025-07-25T19:54:53Z

src/votekit/animations.py

+                support_transferred : dict[str, dict[str, float]] = {}
+                if round_number == len(election):
+                    # If it's the last round, don't worry about the transferred votes
+                    support_transferred = {cand: {} for cand in elected_candidates}


Can you init support_transferred on line 91 to be what you need in line 94? why start with it empty?

I believe I added this to appease mypy. It liked that the type was clearly declared to make sure the type didn't depend on the control flow.

cdonnay · 2025-07-25T19:55:53Z

src/votekit/animations.py

+                        support_transferred=support_transferred,
+                        quota=election.threshold,
+                        message=message,
+                    )


never seen this way of init-ing a dict, does it make all of the keywords without you having to put it in strings?

Yes, exactly.

cdonnay · 2025-07-25T19:57:00Z

src/votekit/animations.py

+                        message=message,
+                    )
+                )
+            elif len(eliminated_candidates) > 0:


it can only be 1, right?

Yes, that should be true. Just hedging my bets I suppose.

cdonnay · 2025-07-25T19:57:22Z

src/votekit/animations.py

+                event_type = "elimination"
+                eliminated_candidates_str = eliminated_candidates[0]
+                for candidate_name in eliminated_candidates[1:]:
+                    eliminated_candidates_str += ", " + candidate_name


same here, only one can be eliminated, right?

Yes. This code has been tightened up.

cdonnay · 2025-07-25T20:06:10Z

Since I am not a manim guy, I'm going to skip looking at that code for now since the animation clearly works. But the same overall review comments would apply; aim for super tiny private methods that build into bigger ones (up to reason). @peterrrock2 will check out your manim code when he gets a chance.

… 'Rounds 3-7: 5 candidates eliminated.'

…left and right sides.

…ariable names to use consistent terminology, etc.

… transferred.

prismika · 2025-08-05T22:31:41Z

Thanks for the code review! I addressed or responded to all the comments.

Some changes since the last comments:

Created dataclasses for animation events instead of using complicated ad-hoc dictionaries.
Support for off-screen candidates. The user can specify which candidates they want on-screen with an optional "focus" keyword argument. If multiple rounds in a row result in off-screen candidates being eliminated, those rounds are condensed into a single step in the animation. (This helps in elections with lots of candidates.)
Bug fixes

Regarding the long methods: the longest two are _animate_win and _animate_elimination at about 100 lines. I've thought about how to factor these but in the end this is simply the amount of Manim code necessary to animate those steps, and the code animating each individual step coheres tightly. It's not idea, but I've decided to leave those methods long.

Given an STV election object election, this code:

from votekit.animations import STVAnimation

animation = STVAnimation(
	election,
	title = "STV Election for Two Seats",
	focus = ['W2', 'W5'] # Elected candidates are automatically focused, so we don't have to list them
)
animation.render(preview = True)

produces this animation:

ElectionScene.mp4

If we like the look of the animation, I can start making snapshot tests!

Tasks remaining:

Snapshot testing
Let users provide nicknames for display purposes
Light mode

Thanks!

peterrrock2 · 2025-08-27T18:18:33Z

Looking good to @cdonnay and I so far! Let us know if you need more support on this, but so far you are killing it 😁

prismika added 13 commits July 15, 2025 11:21

Initial commit for 3.3.0-stv-animation branch. Add animations module …

1ce3f5d

…with empty STVAnimation class.

index on 3.3.0-stv-animation: 1ce3f5d Initial commit for 3.3.0-stv-an…

5a2c8a7

…imation branch. Add animations module with empty STVAnimation class.

Collect animation code in votekit.animation module.

82a50ee

Add support for multiple winners in one round.

eab7683

Clean up the animation code. Specifically,

927c5b1

- Remove double underscores - Remove wildcard imports - Change votekit imports to local imports - Minor changes

Fix static typechecking errors. Add type hints and documentation to a…

875be7b

…ll functions.

Rearrange classes and functions for readability.

2337e20

Fix bug in which rendering an STVAnimation caused the saved state to …

13785c4

…mutate.

Make event messages pretty.

f2f5247

Formatting animations.py

3f472d3

Add test for animation initialization.

e4f5068

Remove the unused _rescale_bars method.

7b287ee

Update documentation, fix typesetting and typechecking.

8a36597

prismika requested review from cdonnay and peterrrock2 July 25, 2025 16:08

cdonnay requested changes Jul 25, 2025

View reviewed changes

prismika added 12 commits July 31, 2025 15:00

Introduce dataclass for animation events.

bc2c576

Let users specify focused candidates.

a355b01

Automatically condense offscreen events into one event. For instance,…

c4fb8da

… 'Rounds 3-7: 5 candidates eliminated.'

Fix layout bug in which bars would extend off the screen on both the …

661dc79

…left and right sides.

Automatically focus all elected candidates.

1bdfb95

Various cleaning tasks: Update type hints and documentation, change v…

345e47a

…ariable names to use consistent terminology, etc.

Various small fixes.

3543415

Fixes to formatting and testing

9391181

Fix bug in which exhausted votes would not disappear if no votes were…

48ce6b8

… transferred.

Typo

89e5111

Tweak test

0c2e430

Small changes to appease poetry.

362dce7

peterrrock2 added the work-in-progress label Aug 13, 2025

Base automatically changed from 3.3.0 to main October 2, 2025 17:55

prismika added 2 commits December 1, 2025 13:53

Fix exhausted bar color.

bc7974e

Fix formatting

2758139

Animations for STV Elections #249

Are you sure you want to change the base?

Animations for STV Elections #249

Uh oh!

Conversation

prismika commented Jul 25, 2025

Uh oh!

cdonnay left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cdonnay left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cdonnay commented Jul 25, 2025

Uh oh!

prismika commented Aug 5, 2025

Uh oh!

peterrrock2 commented Aug 27, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants