Learn R Programming

tweenr

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

#install.packages('devtools')
devtools::install_github('thomasp85/tweenr')

An example

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

library(tweenr)
library(ggplot2)

# 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) %>% 
  keep_state(10)

# 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
  plot(p)
}

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

Easing

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:

tweenr::display_ease('cubic-in-out')

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

Copy Link

Version

Install

install.packages('tweenr')

Monthly Downloads

106,247

Version

2.0.3

License

MIT + file LICENSE

Issues

Pull Requests

Stars

Forks

Maintainer

Thomas Pedersen

Last Published

February 26th, 2024

Functions in tweenr (2.0.3)

tween_appear

Tween a data.frame of appearances
.max_id

Get the highest id occuring in a dataset
tween_at

Get a specific position between two states
gen_along

Generator for tweening along a variable
tween_at_t

Get several specific position between two states
gen_at

Generator for interpolating between two data frames
tween_components

Interpolate individual component
get_frame

Extract a frame from a generator
prepare_keyframes

Prepare keyframes for generator
vec_tween_class

Get the nominal class of a vector
interpolate_custom_at

Fallback for keyframe vector support
gen_events

Generator for tweening the appearance of elements
tween_state

Compose tweening between states
reexports

Objects exported from other packages
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
tween_along

Interpolate data along a given dimension
tween

Create simple tweens
tween_states

Tween a list of data.frames representing states
tweenr-package

tweenr: Interpolate Data for Smooth Animations
gen_components

Generator for tweening components separately from each other
display_ease

Display an easing function
.get_last_frame

Helpers for working with tweened data
.complete_states

Fill in missing rows using enter and exit functions
gen_keyframe

Generator for keyframe based tweening
col_classes

Generator internals