Animation¶
A plot becomes an animation when a transition_* is added to it: the transition
splits the data into frames, and everything else (layers, scales, theme) stays an
ordinary plot. The functions and their parameters follow
gganimate by Thomas Lin Pedersen and
David Robinson; lets-plot has no animation.
Provisional
Animation is complete and tested, but new: names and parameters of animate,
Animation, anim_save, last_animation, transition_*, enter_*, exit_*,
shadow_* and ease_aes may still change in a minor release, with a note in the
changelog. See Stability.
A first animation¶
p + transition_manual("year") draws one frame per value of year. Scales are
trained once over all the data, so the axes stay fixed; stats and positions run per
frame. In a notebook the plot plays in a small player (play, pause and a slider), as
the ones on this page.
from ggrust import *
from ggrust.data import penguins
plot = (
ggplot(penguins, aes("flipper_length_mm", "body_mass_g", color="species"))
+ geom_point(size=3, alpha=0.8, na_rm=True)
+ labs(
title="Palmer penguins, {current_frame}",
x="flipper length (mm)",
y="body mass (g)",
)
+ transition_manual("year")
+ theme_light()
+ ggsize(700, 450)
)
animation = animate(plot, nframes=3, fps=1)
animation
animate(plot, ...) plans the frames and returns an
Animation. Without it, a plot with a transition
is animated with the defaults (100 frames at 10 frames per second).
animate option |
Meaning |
|---|---|
nframes, fps, duration |
Number of frames, frames per second, length in seconds. Give any two. |
start_pause, end_pause |
Repeat the first or last frame this many times. |
rewind |
Play backwards to the start after the last frame. |
detail |
Frames computed per shown frame (default 1). |
width, height, dpi |
Size in pixels (default: the plot's ggsize) and resolution of the saved file. |
Transitions¶
| Transition | Frames | Use it for |
|---|---|---|
transition_manual(frames, cumulative=False) |
One per value, no movement between them. | Flip-book steps; cumulative=True keeps earlier values. |
transition_states(states, transition_length=1, state_length=1, wrap=True) |
Holds each state, then moves into the next. | Categories or a few time points. |
transition_time(time, range=None) |
Evenly spaced over a number, date or date-time column. | Data observed over time. |
transition_reveal(along, range=None, keep_last=True) |
Reveals the data along a column. | Lines and areas that grow. |
States¶
transition_states holds each state for state_length and moves the marks into the
next one over transition_length (relative lengths), and with wrap=True from the
last state back to the first. Rows are matched by group: set it with
aes(group=...); discrete mappings such as fill split groups too. Numbers and
sizes are eased, colors move through CIE Lab, and categories switch halfway.
from ggrust import *
from ggrust.data import penguins
plot = (
ggplot(penguins, aes("species", fill="species"))
+ geom_bar(width=0.7)
+ labs(title="Penguins counted in {closest_state}", x="", y="penguins")
+ transition_states("year", transition_length=2, state_length=1)
+ ease_aes("cubic-in-out")
+ theme_light()
+ ggsize(600, 420)
)
animation = animate(plot, nframes=60, fps=20)
animation
Time¶
transition_time spaces the frames evenly over the range of a time column and moves
the marks from each observed time to the next, matched by group as above. Each time
is drawn at its nearest frame; when two times fall on the same frame only the
earlier one is drawn and a warning says so (raise nframes).
import polars as pl
from ggrust import *
from ggrust.data import penguins
means = (
penguins.drop_nulls(["bill_length_mm", "bill_depth_mm"])
.group_by("species", "year")
.agg(pl.col("bill_length_mm", "bill_depth_mm").mean(), pl.len().alias("penguins"))
)
plot = (
ggplot(means, aes("bill_length_mm", "bill_depth_mm", color="species", size="penguins"))
+ geom_point(alpha=0.8)
+ labs(title="Penguin bills in {frame_time}", x="bill length (mm)", y="bill depth (mm)")
+ transition_time("year")
+ ease_aes("cubic-in-out")
+ theme_light()
+ ggsize(600, 420)
)
animation = animate(plot, nframes=40, fps=10)
animation
Reveal¶
transition_reveal keeps the rows reached so far: lines, areas and polygons end at
a point interpolated at the frame, while other geoms (points, texts) show only that
moving point, kept at the end of its group with keep_last=True.
from ggrust import *
from ggrust.data import economics
plot = (
ggplot(economics, aes("date", "unemploy"))
+ geom_line(color="#1f77b4", size=1)
+ geom_point(color="#d62728", size=4)
+ labs(title="US unemployment, {frame_along}", x="", y="unemployed (thousands)")
+ transition_reveal("date")
+ theme_light()
+ ggsize(640, 400)
)
animation = animate(plot, nframes=100, fps=20, end_pause=20)
animation
Easing¶
ease_aes(default, **aesthetics) sets how values move during a transition:
"linear" moves evenly, "cubic-in-out" starts and ends slowly, "bounce-out"
bounces at the end. The names are tweenr's: linear, or one of quadratic, cubic,
quartic, quintic, sine, circular, exponential, elastic, back and
bounce, followed by -in, -out or -in-out. Aesthetics can differ:
plot + ease_aes("cubic-in-out", y="bounce-out")
Enter and exit¶
Marks without a partner in the next state show only in their own state. Enter and
exit effects let them move in and out instead of popping:
enter_fade(alpha=0) / exit_fade(alpha=0) fade them, enter_grow(size=0) /
exit_shrink(size=0) grow points and texts from nothing, bars from the axis, lines
and polygons from their centre. Effects added with + apply one after the other, and
they work with transition_states and transition_time.
from ggrust import *
sales = {
"year": [2021] * 3 + [2022] * 3 + [2023] * 3,
"fruit": ["apple", "pear", "plum", "apple", "pear", "kiwi", "apple", "kiwi", "fig"],
"sold": [10, 6, 4, 12, 8, 5, 15, 9, 7],
}
plot = (
ggplot(sales, aes("fruit", "sold", fill="fruit"))
+ geom_col(width=0.7)
+ labs(title="Fruit sold in {closest_state}", x="", y="crates")
+ transition_states("year", transition_length=2, state_length=1)
+ enter_fade()
+ enter_grow()
+ exit_fade()
+ exit_shrink()
+ ease_aes("cubic-in-out")
+ theme_light()
+ ggsize(600, 420)
)
animation = animate(plot, nframes=60, fps=20)
animation
Shadows¶
A shadow keeps earlier frames in view. shadow_wake(wake_length) trails moving marks
with their last frames (wake_length is a share of the animation; size and alpha
shrink and fade the trail, falloff is the ease of that change):
import polars as pl
from ggrust import *
from ggrust.data import economics
yearly = (
economics.with_columns(
year=pl.col("date").dt.year(),
unemployed=pl.col("unemploy") / pl.col("pop") * 100,
)
.group_by("year")
.agg(pl.col("unemployed").mean(), pl.col("psavert").mean())
.sort("year")
)
plot = (
ggplot(yearly, aes("unemployed", "psavert"))
+ geom_point(size=6, color="#b7410e")
+ labs(
title="United States, {frame_time}",
x="unemployed (% of population)",
y="personal savings rate (%)",
)
+ transition_time("year")
+ shadow_wake(0.15)
+ theme_light()
+ ggsize(650, 450)
)
animation = animate(plot, nframes=100, fps=14)
animation
shadow_mark(past=True, future=False, **styles) keeps the marks of the states
already shown (or still to come) in the background instead, restyled by the constants
given: plot + shadow_mark(alpha=0.3, size=1). Both take exclude_layer (layer
numbers counted from 1) and work with transition_states and transition_time. A
plot has one shadow: a later one replaces an earlier one.
Labels¶
Text in braces in the title, subtitle or caption is filled in per frame:
labs(title="Year: {frame_time}").
| Variable | Available with | Value |
|---|---|---|
{frame}, {nframes}, {progress} |
every transition | Frame number, frame count, share of the animation done (0 to 1). |
{current_frame} |
transition_manual |
The value drawn. |
{closest_state}, {previous_state}, {next_state} |
transition_states |
The nearest, last and coming state. |
{transitioning} |
transition_states |
True while moving between two states. |
{frame_time} |
transition_time |
The time of the frame. |
{frame_along} |
transition_reveal |
The position reached along the column. |
Dates and date-times are written as dates, in one format for the whole animation.
Saving¶
The file extension picks the format: .gif, .png (an animated PNG) or .html (a
page with the player).
from ggrust import *
from ggrust.data import penguins
plot = (
ggplot(penguins, aes("flipper_length_mm", "body_mass_g", color="species"))
+ geom_point(na_rm=True)
+ labs(title="{current_frame}")
+ transition_manual("year")
)
ggsave(plot, "penguins.gif") # animated with the defaults
animation = animate(plot, nframes=3, fps=1, width=500, height=350)
animation.save("penguins.html") # or anim_save("penguins.html", animation)
anim_save("penguins.png") # the last animation made, as gganimate
animation.frame(0).to_png("first_frame.png") # one frame is an ordinary plot
animation.to_gif(), to_apng() and to_html() return the bytes or text when no
path is given. GIF frames that come out identical are merged and later frames hold
only the rectangle that changed, so files stay small.