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.
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
indexis not an integer within-nframestonframes - 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
pathis 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
pathis 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.Zin the page'sgeneratormeta tag.
Returns:
-
str or None–The page when
pathis 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'