animate: Render a gganim object

In dgrtwo/gganimate: A Grammar of Animated Graphics

Render a gganim object

Description

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.

Usage

animate(plot, ...)

## S3 method for class 'gganim'
animate(
  plot,
  nframes,
  fps,
  duration,
  detail,
  renderer,
  device,
  ref_frame,
  start_pause,
  end_pause,
  rewind,
  ...
)

## S3 method for class 'gganim'
print(x, ...)

knit_print.gganim(x, options, ...)

Arguments

plot, x	A gganim object
...	Arguments passed on to the device. For available device arguments, see grDevices::png() or grDevices::svg()
nframes	The number of frames to render (default 100)
fps	The framerate of the animation in frames/sec (default 10)
duration	The length of the animation in seconds (unset by default)
detail	The number of additional frames to calculate, per frame (default 1)
renderer	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())
device	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')
ref_frame	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)
start_pause, end_pause	Number of times to repeat the first and last frame in the animation (default is 0 for both)
rewind	Should the animation roll back in the end (default FALSE)
options	chunk options for the currently executing chunk

Details

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.

Value

The return value of the renderer function

Defaults

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.

Label variables

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.

Examples

anim <- ggplot(mtcars, aes(mpg, disp)) +
  geom_point(aes(color = gear)) +
  transition_states(gear, transition_length = 2, state_length = 1) +
  enter_fade() +
  exit_fade()

## Not run: 
# 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)

## End(Not run)

dgrtwo/gganimate documentation built on March 3, 2024, 8:15 a.m.