Skip to content

Animation

Animation(
    plot: PlotSpec,
    options: AnimateOptions,
    size: tuple[float, float] | None,
    dpi: float | None,
)

A planned animation of a plot: frames, speed and size, rendered on demand.

Made by :func:animate. Displays as an HTML player in notebooks, saves as GIF, APNG or HTML, and gives single frames as plots for inspection. Immutable.

Examples:

>>> from ggrust import *
>>> data = {"year": [2021, 2022, 2023], "sold": [10, 12, 15], "fruit": ["apple"] * 3}
>>> plot = ggplot(data, aes("fruit", "sold")) + geom_col() + transition_manual("year")
>>> animation = animate(plot, fps=2)
>>> animation.nframes, animation.fps
(3, 0.06)

fps property

fps

Frames per second the animation plays at.

As gganimate, a transition with fewer frames than nframes lowers the fps asked to fps * frames / nframes so the duration stays: three states with fps=1 and the default 100 frames give about 0.03. Pass nframes equal to the number of states to keep the fps asked.

nframes property

nframes

Number of frames the animation shows, pauses and rewind included.

As gganimate, a transition with fewer frames than nframes asked for (transition_manual(): one per value) shows only those.

options property

options

The animate() options, a copy (None: gganimate's default).

plot property

plot

The animated plot (with its transition).

frame

frame(index: int) -> PlotSpec

Return frame index as a still plot (render it with to_png() etc.).

Parameters:

  • index (int) –

    0-based frame number; negative numbers count from the end.

Returns:

  • PlotSpec –

    The plot drawing only that frame.

Raises:

  • PlotIndexError –

    If index is not an integer within -nframes to nframes - 1.

Examples:

>>> from ggrust import *
>>> data = {"year": [2021, 2022], "sold": [10, 12], "fruit": ["apple"] * 2}
>>> plot = ggplot(data, aes("fruit", "sold")) + geom_col() + transition_manual("year")
>>> svg = animate(plot).frame(-1).to_svg()

save

save(
    filename: str | PathLike[str],
    *,
    path: str | None = None,
) -> str

Write the animation to filename; the extension picks the format.

Parameters:

  • filename (str) –

    .gif, .png / .apng (animated PNG) or .html / .htm (a page with the player).

  • path (str, default: None ) –

    Directory to join in front of filename.

Returns:

  • str –

    Absolute path of the written file.

Raises:

  • ExportError –

    If the extension is missing or not an animation format.

Examples:

>>> import os
>>> import tempfile
>>> from ggrust import *
>>> data = {"year": [2021, 2022, 2023], "sold": [10, 12, 15]}
>>> plot = ggplot(data, aes("year", "sold")) + geom_point() + transition_manual("year")
>>> animation = animate(plot, fps=1)
>>> with tempfile.TemporaryDirectory() as folder:
...     written = animation.save("sales.gif", path=folder)
...     os.path.basename(written), os.path.exists(written)
('sales.gif', True)

to_apng

to_apng(path: Target | None = None) -> bytes | str

Return the animated PNG bytes, or write them to path.

Parameters:

  • path (str or file - like, default: None ) –

    Where to write: a file path or a binary file-like object.

Returns:

  • bytes or str –

    The APNG when path is None, else the written path (empty for a file object).

Examples:

>>> import io
>>> from ggrust import *
>>> data = {"year": [2021, 2022, 2023], "sold": [10, 12, 15]}
>>> plot = ggplot(data, aes("year", "sold")) + geom_point() + transition_manual("year")
>>> buffer = io.BytesIO()
>>> animate(plot, fps=1).to_apng(buffer)
''
>>> buffer.getvalue()[1:4]
b'PNG'

to_gif

to_gif(path: Target | None = None) -> bytes | str

Return the GIF bytes, or write them to path and return its absolute path.

Parameters:

  • path (str or file - like, default: None ) –

    Where to write: a file path or a binary file-like object.

Returns:

  • bytes or str –

    The GIF when path is None, else the written path (empty for a file object).

Examples:

>>> from ggrust import *
>>> data = {"year": [2021, 2022, 2023], "sold": [10, 12, 15]}
>>> plot = ggplot(data, aes("year", "sold")) + geom_point() + transition_manual("year")
>>> animate(plot, fps=1).to_gif()[:6]
b'GIF89a'

to_html

to_html(
    path: Target | None = None,
    iframe: bool | None = None,
    metadata: bool = True,
) -> str | None

Return a standalone HTML page with the player, or write it to path.

Parameters:

  • path (str or file - like, default: None ) –

    Where to write: a file path or a binary file-like object.

  • iframe (bool, default: None ) –

    Return an <iframe srcdoc> sized to the player instead of a page.

  • metadata (bool, default: True ) –

    Record ggrust vX.Y.Z in the page's generator meta tag.

Returns:

  • str or None –

    The page when path is None, else the written path (None for a file object).

Examples:

>>> from ggrust import *
>>> data = {"year": [2021, 2022, 2023], "sold": [10, 12, 15]}
>>> plot = ggplot(data, aes("year", "sold")) + geom_point() + transition_manual("year")
>>> animation = animate(plot, fps=1)
>>> animation.to_html()[:15]
'<!DOCTYPE html>'
>>> animation.to_html(iframe=True)[:7]
'<iframe'