Skip to content

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 fps so the duration stays, as gganimate does: fps * shown / (nframes - start_pause - end_pause), and the pauses play at that lowered rate. For example transition_manual() over 49 values with fps=8, end_pause=16 plays 65 frames at about 4.7 fps (13.9 s). Pass a smaller nframes (here 65) or duration= to keep it faster.

  • fps (float, default: 10 ) –

    Frames per second asked. A transition with fewer frames than nframes lowers it by gganimate's rule, fps * frames / nframes (see nframes): three states with fps=1 and the default 100 frames play at about 0.03 fps (each state about 33 s). Pass nframes equal to the number of states (nframes=3) to keep the fps asked.

  • 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 ggsize by default.

  • height (float, default: None ) –

    Frame size in pixels (both or neither); the plot's ggsize by 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_save and :func:last_animation.

Raises:

  • SpecError –

    If plot has 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