Skip to content

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 states is not a non-empty string, a length is negative or not a number, or wrap is 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