transition_states ¶
transition_states(
states: str,
*,
transition_length: float | Sequence[float] = 1,
state_length: float | Sequence[float] = 1,
wrap: bool = True,
) -> FeatureSpec
Animate by holding each value of states and moving smoothly to the next.
Each state (one value of the states column) is shown for a while, then
its marks move to where they are in the next state (gganimate
transition_states). States come in the column's order: numbers
ascending, categories in their level order (a polars Enum or pandas
categorical keeps its order, plain strings their order of first appearance).
Stats and positions run per state; axes and legends cover every state, so
they stay still. Layers without the states column are drawn in every
frame.
Marks are matched between states by their group (set it with
aes(group=...); discrete mappings such as color also split groups):
the k-th row of a group moves to the k-th row of the same group. Numbers
and sizes move linearly by the plot's ease_aes(), colors through CIE Lab,
categories, shapes and texts switch halfway. Rows without a partner show
only in their own state, unless the plot has enter or exit effects
(enter_fade(), exit_shrink(), ...).
Titles, subtitles and captions can show {closest_state},
{previous_state}, {next_state} and {transitioning} (TRUE
while moving), plus {frame}, {nframes} and {progress}.
Parameters:
-
states(str) –The column whose values are the states.
-
transition_length(float or sequence of float, default:1) –Relative time spent moving from one state to the next; a list gives one length per state (recycled).
-
state_length(float or sequence of float, default:1) –Relative time each state is held still; a list gives one per state.
-
wrap(bool, default:True) –Move from the last state back to the first, so the animation loops smoothly.
Returns:
-
FeatureSpec–The transition (kind
"animation"), added to a plot with+.
Raises:
-
SpecError–If
statesis not a non-empty string, a length is negative or not a number, orwrapis not a bool.
Examples:
>>> from ggrust import *
>>> data = {
... "year": [2021, 2021, 2022, 2022, 2023, 2023],
... "fruit": ["apple", "pear"] * 3,
... "sold": [10, 4, 12, 7, 15, 9],
... }
>>> plot = (
... ggplot(data, aes("fruit", "sold"))
... + geom_col()
... + transition_states("year", transition_length=2, state_length=1)
... + ease_aes("cubic-in-out")
... + ggtitle("Sales in {closest_state}")
... )
>>> animate(plot, nframes=30).nframes
30
A short hold, a long move, and no move from the last state back to the first:
>>> plot = (
... ggplot(data, aes("fruit", "sold"))
... + geom_col()
... + transition_states("year", transition_length=3, state_length=1, wrap=False)
... )
The states around the frame, in the title and subtitle:
>>> plot = (
... ggplot(data, aes("fruit", "sold"))
... + geom_col()
... + transition_states("year")
... + labs(title="{closest_state}", subtitle="from {previous_state} to {next_state}")
... )
A short hold, a long move, and no move from the last state back to the first
The states around the frame, in the title and subtitle