This function takes a gganim object and renders it into an animation. The
nature of the animation is dependent on the renderer, but defaults to using
gifski to render it to a gif. The length and framerate is decided on render
time and can be any two combination of nframes, fps, and duration.
Rendering is happening in discrete time units. This means that any event in
the animation is rounded of to the nearest frame (e.g. entering will always
take a whole number of frames). This means that rounding artifacts are
possible when only rendering few frames. To avoid this you can increase the
detail argument. detail will get multiplied to nframes and the
resulting number of frames will get calculated, but only nframes evenly
spaced frames are rendered.
animate(plot, ...)
# S3 method for gganim
animate(
plot,
nframes,
fps,
duration,
detail,
renderer,
device,
ref_frame,
start_pause,
end_pause,
rewind,
...
)
# S3 method for gganim
print(x, ...)
knit_print.gganim(x, options, ...)A gganim object
Arguments passed on to the device.
For available device arguments, see grDevices::png() or grDevices::svg()
The number of frames to render (default 100)
The framerate of the animation in frames/sec (default 10)
The length of the animation in seconds (unset by default)
The number of additional frames to calculate, per frame (default 1)
The function used to render the generated frames into an
animation. Gets a vector of paths to images along with the framerate. (by
default it will use gifski_renderer() if gifski is installed. If not it
will use magick_renderer() if magick is installed and then av_renderer()
if av is installed. If all fails it will use the file_renderer())
The device to use for rendering the single frames. Possible
values are 'png', 'ragg_png' (requires the ragg package), 'jpeg',
'tiff', 'bmp', 'svg', and 'svglite' (requires the svglite package).
(default 'png')
The frame to use for fixing dimensions of the plot, e.g. the
space available for axis text. Defaults to the first frame. Negative values
counts backwards (-1 is the last frame) (default 1)
Number of times to repeat the first and last
frame in the animation (default is 0 for both)
Should the animation roll back in the end (default FALSE)
chunk options for the currently executing chunk
The return value of the renderer function
print.gganim() is an alias for animate() in the same way as
print.ggplot() is an alias for plot.ggplot(). This ensures that gganimate
behaves ggplot2-like and produces the animation when the object is printed.
The plot() method is different and produces a single frame for inspection
(by default frame 50 out of 100).
Animations can be saved to disk using anim_save() in much the same way
ggsave() works for static plots.
It is possible to overwrite the defaults used by gganimate for the animation
by setting them with options() (prefixed with gganimate.. As an example,
if you would like to change the default nframes to 50 you would call
options(gganimate.nframes = 50). In order to set default device arguments
(those you would normally pass through with ...) you should use the
gganimate.dev_args options and provide a list of arguments e.g.
options(gganimate.dev_args = list(width = 800, height = 600)) Defaults set
this way can still be overridden by giving arguments directly to animate().
knitr Support:
It is possible to specify the arguments to animate() in the chunk options
when using gganimate with knitr. Arguments specified in this way will
have precedence over defaults, but not over arguments specified directly in
animate(). The arguments should be provided as a list to the gganimate
chunk option, e.g. {r, gganimate = list(nframes = 50, fps = 20)}. A few
build-in knitr options have relevance for animation and will be used unless
given specifically in the gganimate list option. The native knitr options
supported are:
dev: will set device
dev.args: will set additional arguments to the device (...)
fig.width, fig.height, fig.asp, fig.dim: will set width and
height of the device.
All plots have a certain set of variables available for string literal interpolation within plot labels. These are:
frame gives you the frame index for the current frame
nframes gives you the total number of frames in the animation
progress gives you the progress of the animation at the current frame
(equal to frame/nframes)
data gives you the layer data for the current frame (as a list of data frames)
Further, the transition and view in use can also make variables available. Consult the documentation for these for more detail.
anim <- ggplot(mtcars, aes(mpg, disp)) +
geom_point(aes(color = gear)) +
transition_states(gear, transition_length = 2, state_length = 1) +
enter_fade() +
exit_fade()
if (FALSE) {
# Explicitly animate using default (same as just printing the animation)
animate(anim)
# Change duration and framerate
animate(anim, fps = 20, duration = 15)
# Make the animation pause at the end and then rewind
animate(anim, nframes = 100, end_pause = 10, rewind = TRUE)
# Use a different renderer
animate(anim, renderer = file_renderer('~/animation/'))[1:6]
# Specify device dimensions and/or resolution
animate(anim, height = 2, width = 3, units = "in", res = 150)
}