tweenr v1.0.1


Monthly downloads



Interpolate Data for Smooth Animations

In order to create smooth animation between states of data, tweening is necessary. This package provides a range of functions for creating tweened data that can be used as basis for animation. Furthermore it adds a number of vectorized interpolaters for common R data types such as numeric, date and colour.



Travis-CI Build Status AppVeyor Build Status CRAN\_Release\_Badge CRAN\_Download\_Badge Coverage Status

What is this?

tweenr is a package for interpolating data, mainly for animations. It provides a range of functions that take data of different forms and calculate intermediary values. It supports all atomic vector types along with factor, Date, POSIXct, characters representing colours, and list. tweenr is used extensibly by gganimate to create smooth animations, but can also be used by itself to prepare data for animation in another framework.

How do I get it?

tweenr is available on CRAN and can be installed with install.packages('tweenr'). In order to get the development version you can install it from github with devtools


An example

Following is an example of using the pipeable tween_state() function with our belowed iris data:


# Prepare the data with some extra columns
iris$col <- c('firebrick', 'forestgreen', 'steelblue')[as.integer(iris$Species)]
iris$size <- 4
iris$alpha <- 1
iris <- split(iris, iris$Species)

# Here comes tweenr
iris_tween <- iris$setosa %>% 
  tween_state(iris$versicolor, ease = 'cubic-in-out', nframes = 30) %>% 
  keep_state(10) %>% 
  tween_state(iris$virginica, ease = 'elastic-out', nframes = 30) %>% 
  keep_state(10) %>% 
  tween_state(iris$setosa, ease = 'quadratic-in', nframes = 30) %>% 

# Animate it to show the effect
p_base <- ggplot() + 
  geom_point(aes(x = Petal.Length, y = Petal.Width, alpha = alpha, colour = col, 
                 size = size)) + 
  scale_colour_identity() +
  scale_alpha_identity() + 
  scale_size_identity() + 
  coord_cartesian(xlim = range(iris_tween$Petal.Length), 
                  ylim = range(iris_tween$Petal.Width))
iris_tween <- split(iris_tween, iris_tween$.frame)
for (d in iris_tween) {
  p <- p_base %+% d

Other functions

Besides the tween_state()/keep_state() combo showcased above, there are a slew of other functions meant for data in different formats

tween_components takes a single data.frame, a vector of ids identifying recurrent elements, and a vector of timepoints for each row and interpolate each element between its specified time points.

tween_events takes a single data.frame where each row encodes a single unique event, along with a start, and end time and expands the data across a given number of frames.

tween_along takes a single data.frame along with an id and timepoint vector and calculate evenly spaced intermediary values with the possibility of keeping old values at each frame.

tween_at takes two data.frames or vectors along with a numeric vector giving the interpolation point between the two data.frames to calculate.

tween_fill fills missing values in a vector or data.frame by interpolating between previous and next non-missing elements


In order to get smooth transitions you'd often want a non-linear interpolation. This can be achieved by using an easing function to translate the equidistant interpolation points into new ones. tweenr has support for a wide range of different easing functions, all of which can be previewed using display_ease() as here where the popular cubic-in-out is shown:


Spatial interpolations

The purpose of tweenr is to interpolate values independently. If paths and polygons needs to be transitioned the transformr package should be used as it expands tweenr into the spatial realm

Functions in tweenr

Name Description
tween_states Tween a list of data.frames representing states
tweenr-package tweenr: Interpolate Data for Smooth Animations
tween_state Compose tweening between states
.complete_states Fill in missing rows using enter and exit functions
tween_fill Fill out missing values by interpolation
tween_elements Create frames based on individual element states
tween_events Transition in and out of events
.get_last_frame Helpers for working with tweened data
.max_id Get the highest id occuring in a dataset
tween_at Get a specific position between two states
display_ease Display an easing function
tween_components Interpolate individual component
tween_along Interpolate data along a given dimension
tween_appear Tween a data.frame of appearances
reexports Objects exported from other packages
tween Create simple tweens
No Results!

Last month downloads


Type Package
Date 2018-12-14
License MIT + file LICENSE
Encoding UTF-8
LazyData TRUE
LinkingTo Rcpp
RoxygenNote 6.1.1
NeedsCompilation yes
Packaged 2018-12-14 13:16:06 UTC; thomas
Repository CRAN
Date/Publication 2018-12-14 13:40:03 UTC

Include our badge in your README