Skip to content

transition_manual

transition_manual(
    frames: str, *, cumulative: bool = False
) -> FeatureSpec

Animate by showing the rows of one value of frames per frame.

Each frame draws the rows whose frames column has one value, 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 (counts, stacks, smooths) run per value. Axes and legends cover every frame, so they stay still. Layers whose data has no frames column are drawn in every frame. As gganimate, the animation has one frame per value when nframes is larger, and fps shrinks to keep the requested duration; with more values than nframes, evenly spaced values are shown.

Titles, subtitles and captions can show the frame with {current_frame} (also {previous_frame}, {next_frame}, {frame}, {nframes} and {progress}).

Parameters:

  • frames (str) –

    The column whose values are the frames.

  • cumulative (bool, default: False ) –

    Keep the rows of earlier frames: frame k draws the values up to k.

Returns:

  • FeatureSpec –

    The transition (kind "animation"), added to a plot with +.

Raises:

  • SpecError –

    If frames is not a non-empty string or cumulative 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_manual("year")
...     + ggtitle("Sales in {current_frame}")
... )
>>> animate(plot).nframes
3

Each frame keeps the years before it:

>>> plot = (
...     ggplot(data, aes("fruit", "sold", color=as_discrete("year")))
...     + geom_point(size=6)
...     + transition_manual("year", cumulative=True)
... )

Each frame keeps the years before it