Repository files navigation

gganimate extends the grammar of graphics as implemented byggplot2 to include thedescription of animation. It does this by providing a range of newgrammar classes that can be added to the plot object in order tocustomise how it should change with time.

• transition_*() defines how the data should be spread out and how itrelates to itself across time.
• view_*() defines how the positional scales should change along theanimation.
• shadow_*() defines how data from other points in time should bepresented in the given point in time.
• enter_*()/exit_*() defines how new data should appear and how olddata should disappear during the course of the animation.
• ease_aes() defines how different aesthetics should be eased duringtransitions.

All of the above might seem a bit abstract. Let’s try with a contrivedexample:

library(ggplot2)library(gganimate)ggplot(mtcars, aes(factor(cyl),mpg))+   geom_boxplot()+# Here comes the gganimate code  transition_states(gear,transition_length=2,state_length=1  )+  enter_fade()+   exit_shrink()+  ease_aes('sine-in-out')

Here we take a simple boxplot of fuel consumption as a function ofcylinders and lets it transition between the number of gears availablein the cars. As this is a discrete split (gear being best described asan ordered factor) we usetransition_states and provides a relativelength to use for transition and state view. As not all combinations ofdata is present there are states missing a box. We define that when abox appears it should fade into view, whereas at should shrink away whenit disappear. Lastly we decide to use a sinusoidal easing for all ouraesthetics (here, onlyy is changing)

gganimate is available on CRAN and can be installed withinstall.packages('gganimate'). If you wish to install the developmentversion you can install directly from github using devtools:

# install.packages('pak')pak::pak('thomasp85/gganimate')

It is impossible to cover everything possible withgganimate in aREADME, but animations are fun, so let’s at least have one more:

library(gapminder)ggplot(gapminder, aes(gdpPercap,lifeExp,size=pop,colour=country))+  geom_point(alpha=0.7,show.legend=FALSE)+  scale_colour_manual(values=country_colors)+  scale_size(range= c(2,12))+  scale_x_log10()+  facet_wrap(~continent)+# Here comes the gganimate specific bits  labs(title='Year: {frame_time}',x='GDP per capita',y='life expectancy')+  transition_time(year)+  ease_aes('linear')

In this example we see the use oftransition_time() which can be usedwith continuous variables such asyear. With this transition it is notnecessary to provide transition and state length as the “transitionvariable” provides this directly (e.g. it should take twice as long totransition between 1980 and 1990 compared to 2000 to 2005). We also seethe use of string literal interpolation in titles.gganimate lets youspecify variables to evaluate inside titles and different transitionsprovide different type of information to use.

gganimate mimics the wayggplot2 renders its output, in that therendering is done automatically when thegganim object is printed.Under the hood, theanimate() function is called which renders theframe and passes the frames to a renderer functions which takes care ofcombining them to the final animation. The default renderer isgifski_renderer() which returns agif_image object which is a simplewrapper around a path to a gif file. Ifanimate() has been calledimplicitly as part ofprint thegif_image object is available usingthelast_animation() function (analogous toggplot2::last_plot()).In order to save the animation to a specific location, you can use theanim_save() function which, likeggplot2::ggsave, defaults to takingthe last rendered animation and writes it to a file.

gif is a fantastic format for animations due to its wide support, butsometimes another format is required.gganimate is agnostic to therenderer and while the default is to usegifski to combine the frames into agif, it doesn’t have to be so. By passing an alternate renderer to theanimate() function you can control the animation format, andgganimate comes with a bunch (and you can write your own). To createvideo files you can e.g. use theffmpeg_renderer():

p<- ggplot(airquality, aes(Day,Temp))+   geom_line(size=2,colour='steelblue')+   transition_states(Month,4,1)+   shadow_mark(size=1,colour='grey')animate(p,renderer= ffmpeg_renderer())

Video output are automatically embedded in RMarkdown documents, butGitHub strips video when rendering READMEs so you can’t see it here

Further there’s support for rendering to sprite sheets if that is yourvice.

This is the second iteration of the gganimate package. The first,developed byDavid Robinson had a verydifferent API, and relied on specifying animation frame membershipinsideaes() blocks in thegeom_*() calls. This approach was easy tograsp, but essentially limited in capabilities and has thus beenabandoned for a more thorough grammar.

Code written for the old API will not work with thisgganimate versionand there will not come a future support for it. If you wish to continueusing the old API then avoid upgradinggganimate. If you’ve alreadyupgraded and wish to downgrade, the latest version of the old API isavailable as aGitHubrelease.

If you wish to convert your old animations to the new API, the closestyou get is probably withtransition_manual, even though it is notcompletely substitutable:

# Old codeggplot(mtcars)+   geom_boxplot(aes(factor(cyl),mpg,frame=gear))# New codeggplot(mtcars)+   geom_boxplot(aes(factor(cyl),mpg))+   transition_manual(gear)