animate ¶
animate(
plot: PlotSpec,
*,
nframes: int | None = None,
fps: float | None = None,
duration: float | None = None,
detail: int | None = None,
start_pause: int = 0,
end_pause: int = 0,
rewind: bool = False,
width: float | None = None,
height: float | None = None,
dpi: float | None = None,
) -> Animation
Plan the frames of a plot with a transition (gganimate animate()).
Nothing is drawn yet: the returned :class:Animation renders when displayed,
saved or asked for a frame. Two of nframes, fps and duration set
the third, as gganimate: with duration, a given fps sets the frame
count, otherwise the frame count sets fps.
Parameters:
-
plot(PlotSpec) –A plot with a transition, e.g.
+ transition_manual("year"). -
nframes(int, default:100) –Frames to show, pauses and rewind included. A transition with fewer frames shows those and lowers
fpsso the duration stays, as gganimate does:fps * shown / (nframes - start_pause - end_pause), and the pauses play at that lowered rate. For exampletransition_manual()over 49 values withfps=8, end_pause=16plays 65 frames at about 4.7 fps (13.9 s). Pass a smallernframes(here 65) orduration=to keep it faster. -
fps(float, default:10) –Frames per second asked. A transition with fewer frames than
nframeslowers it by gganimate's rule,fps * frames / nframes(seenframes): three states withfps=1and the default 100 frames play at about 0.03 fps (each state about 33 s). Passnframesequal to the number of states (nframes=3) to keep thefpsasked. -
duration(float, default:None) –Length in seconds.
-
detail(int, default:1) –Frames computed per shown frame (for smoother tweening in later transitions).
-
start_pause(int, default:0) –Frames the first frame is held at the start.
-
end_pause(int, default:0) –Frames the last frame is held at the end.
-
rewind(bool, default:False) –Play the frames backwards after playing them forwards.
-
width(float, default:None) –Frame size in pixels (both or neither); the plot's
ggsizeby default. -
height(float, default:None) –Frame size in pixels (both or neither); the plot's
ggsizeby default. -
dpi(float, default:None) –Resolution of GIF and APNG frames: the pixel size is multiplied by
dpi / 96(96 by default, one pixel per layout pixel).
Returns:
-
Animation–The planned animation; also kept for :func:
anim_saveand :func:last_animation.
Raises:
-
SpecError–If
plothas no transition, or an option is out of range.
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")
>>> animation = animate(plot, fps=1, end_pause=2)
>>> animation.nframes
5
Pauses on the first and last frame, then a rewind back to the start:
>>> animation = animate(plot, nframes=10, fps=2, start_pause=2, end_pause=3, rewind=True)
>>> animation.nframes, animation.fps
(10, 2)
A size in pixels and a resolution for the saved file:
>>> animation = animate(plot, width=400, height=300, dpi=144)
>>> animation.to_gif()[:6]
b'GIF89a'
Three frames computed for each one shown, for a smoother move between states:
>>> plot = ggplot(data, aes("fruit", "sold")) + geom_col() + transition_states("year")
>>> animate(plot, nframes=20, detail=3).nframes
20
Three frames computed for each one shown, for a smoother move between states