tweenr/ 0000755 0001762 0000144 00000000000 14305577002 011561 5 ustar ligges users tweenr/NAMESPACE 0000644 0001762 0000144 00000004731 14277360441 013012 0 ustar ligges users # Generated by roxygen2: do not edit by hand
S3method(convert_generator,along_generator)
S3method(convert_generator,component_generator)
S3method(convert_generator,default)
S3method(convert_generator,keyframe_generator)
S3method(get_frame,along_generator)
S3method(get_frame,component_generator)
S3method(get_frame,keyframe_generator)
S3method(get_raw_frames,along_generator)
S3method(get_raw_frames,component_generator)
S3method(get_raw_frames,keyframe_generator)
S3method(vec_tween_class,Date)
S3method(vec_tween_class,POSIXt)
S3method(vec_tween_class,character)
S3method(vec_tween_class,default)
S3method(vec_tween_class,factor)
S3method(vec_tween_class,list)
S3method(vec_tween_class,logical)
S3method(vec_tween_class,numeric)
export("%>%")
export("col_types<-")
export("ease_type<-")
export("frame_times<-")
export("gen_data<-")
export("generator_settings<-")
export("keyframes<-")
export(.complete_states)
export(.get_first_frame)
export(.get_last_frame)
export(.has_frames)
export(.max_id)
export(.with_later_frames)
export(.with_prior_frames)
export(PHASE_LEVELS)
export(add_keyframe)
export(add_pause)
export(close_state)
export(col_classes)
export(col_types)
export(data_frame_to_gen)
export(display_ease)
export(ease_type)
export(frame_times)
export(gen_along)
export(gen_at)
export(gen_components)
export(gen_data)
export(gen_events)
export(gen_keyframe)
export(gen_to_data_frame)
export(generator_settings)
export(get_frame)
export(get_raw_frames)
export(interpolate_custom_at)
export(is_generator)
export(keep_state)
export(keyframes)
export(open_state)
export(prepare_keyframes)
export(tween)
export(tween_along)
export(tween_appear)
export(tween_at)
export(tween_color)
export(tween_color_t)
export(tween_colour)
export(tween_colour_t)
export(tween_components)
export(tween_constant)
export(tween_constant_t)
export(tween_date)
export(tween_date_t)
export(tween_datetime)
export(tween_datetime_t)
export(tween_elements)
export(tween_events)
export(tween_fill)
export(tween_numeric)
export(tween_numeric_t)
export(tween_state)
export(tween_states)
export(tween_t)
export(vec_tween_class)
importFrom(farver,decode_colour)
importFrom(farver,encode_colour)
importFrom(graphics,plot)
importFrom(magrittr,"%>%")
importFrom(rlang,"%||%")
importFrom(rlang,as_function)
importFrom(rlang,enquo)
importFrom(rlang,eval_tidy)
importFrom(rlang,is_integerish)
importFrom(rlang,quo_is_missing)
importFrom(rlang,quo_is_null)
importFrom(vctrs,vec_cbind)
importFrom(vctrs,vec_rbind)
useDynLib(tweenr, .registration = TRUE)
tweenr/LICENSE 0000644 0001762 0000144 00000000061 13252477477 012602 0 ustar ligges users YEAR: 2018
COPYRIGHT HOLDER: Thomas Lin Pedersen
tweenr/README.md 0000644 0001762 0000144 00000010333 14276677320 013053 0 ustar ligges users
# tweenr
[](https://github.com/thomasp85/tweenr/actions/workflows/R-CMD-check.yaml)
[](https://CRAN.R-project.org/package=tweenr)
[](https://CRAN.R-project.org/package=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`](https://github.com/thomasp85/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`
``` r
#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:
``` r
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:
``` r
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`](https://github.com/thomasp85/transformr) package should
be used as it expands tweenr into the spatial realm
tweenr/man/ 0000755 0001762 0000144 00000000000 14276701255 012342 5 ustar ligges users tweenr/man/tween.Rd 0000644 0001762 0000144 00000011204 14067576055 013757 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tween.R, R/tween_colour.R, R/tween_constant.R,
% R/tween_date.R, R/tween_datetime.R, R/tween_numeric.R
\name{tween}
\alias{tween}
\alias{tween_t}
\alias{tween_colour}
\alias{tween_color}
\alias{tween_colour_t}
\alias{tween_color_t}
\alias{tween_constant}
\alias{tween_constant_t}
\alias{tween_date}
\alias{tween_date_t}
\alias{tween_datetime}
\alias{tween_datetime_t}
\alias{tween_numeric}
\alias{tween_numeric_t}
\title{Create simple tweens}
\usage{
tween(data, n, ease = "linear")
tween_t(data, n, ease = "linear")
tween_colour(data, n, ease = "linear")
tween_color(data, n, ease = "linear")
tween_colour_t(data, n, ease = "linear")
tween_color_t(data, n, ease = "linear")
tween_constant(data, n, ease = "linear")
tween_constant_t(data, n, ease = "linear")
tween_date(data, n, ease = "linear")
tween_date_t(data, n, ease = "linear")
tween_datetime(data, n, ease = "linear")
tween_datetime_t(data, n, ease = "linear")
tween_numeric(data, n, ease = "linear")
tween_numeric_t(data, n, ease = "linear")
}
\arguments{
\item{data}{A list of vectors or a single vector. In the standard functions
each element in the list must be of equal length; for the *_t functions
lengths can differ. If a single vector is used it will be eqivalent to using
\code{as.list(data)} for the standard functions and \code{list(data)} for the
*_t functions.}
\item{n}{The number of elements per transition or tween. See details}
\item{ease}{The easing function to use for each transition or tween. See
details. Defaults to \code{'linear'}}
}
\value{
A list with an element for each tween. That means that the length of
the return is equal to the length of the elements in \code{data} for the
standard functions and equal to the length of \code{data} for the *_t
functions.
}
\description{
This set of functions can be used to interpolate between single data types,
i.e. data not part of data.frames but stored in vectors. All functions come
in two flavours: the standard and a *_t version. The standard reads the data
as a list of states, each tween matched element-wise from state to state. The
*_t version uses the transposed representation where each element is a vector
of states. The standard approach can be used when each tween has the same
number of states and you want to control the number of point in each state
transition. The latter is useful when each tween consists of different
numbers of states and/or you want to specify the total number of points for
each tween.
}
\details{
\code{tween} and \code{tween_t} are wrappers around the other functions that tries to guess
the type of input data and choose the appropriate tween function. Unless you
have data that could be understood as a colour but is in fact a character
vector it should be safe to use these wrappers. It is probably safer and more
verbose to use the explicit functions within package code as they circumvent
the type inference and checks whether the input data matches the tween
function.
\code{tween_numeric} will provide a linear interpolation between the points based on
the sequence returned by the easing function. \code{tween_date} and \code{tween_datetime}
converts to numeric, produces the tweening, and converts back again.
\code{tween_colour} converts colours into Lab and does the interpolation there,
converting back to sRGB after the tweening is done. \code{tween_constant} is a
catchall that converts the input into character and interpolates by switching
between states halfway through the transition.
The meaning of the \code{n} and \code{ease} arguments differs somewhat
between the standard and *_t versions of the functions. In the standard
function \code{n} and \code{ease} refers to the length and easing function of
each transition, being recycled if necessary to \code{length(data) - 1}. In
the *_t functions \code{n} and \code{ease} refers to the total length of each
tween and the easing function to be applied to all transition for each tween.
The will both be recycled to \code{length(data)}.
}
\section{Difference Between \code{tween_numeric} and \code{approx()}}{
\code{tween_numeric} (and \code{tween_numeric_t}) is superficially equivalent to
\code{\link[stats:approxfun]{stats::approx()}}, but there are differences.
\code{\link[stats:approxfun]{stats::approx()}} will create evenly spaced points, at the expense
of not including the actual points in the input, while the reverse is true
for \code{tween_numeric}. Apart from that \code{tween_numeric} of course supports easing
functions and is vectorized.
}
\examples{
tween_numeric(list(1:3, 10:8, c(20, 60, 30)), 10)
tween_colour_t(list(colours()[1:4], colours()[1:2], colours()[25:100]), 100)
}
tweenr/man/tween_states.Rd 0000644 0001762 0000144 00000003476 14067576055 015356 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tween_states.R
\name{tween_states}
\alias{tween_states}
\title{Tween a list of data.frames representing states}
\usage{
tween_states(data, tweenlength, statelength, ease, nframes)
}
\arguments{
\item{data}{A list of data.frames. Each data.frame must contain the same
number of rows, but only the first data.frame needs to contain all columns.
Subsequent data.frames need only contain the columns that shows change.}
\item{tweenlength}{The lengths of the transitions between each state.}
\item{statelength}{The length of the pause at each state.}
\item{ease}{The easing functions to use for the transitions. See details.}
\item{nframes}{The number of frames to generate. The actual number of frames
might end up being higher depending on the regularity of \code{tweenlength}
and \code{statelength}.}
}
\value{
A data.frame with the same columns as the first data.frame in
\code{data}, but replicated \code{nframes} times. An additional column called
\code{.frame} will be added giving the frame number.
}
\description{
This function is intended to create smooth transitions between states of
data. States are defined as full data.frames or data.frames containing only
the columns with change. Each state can have a defined period of pause, the
transition length between each states can be defined as well as the easing
function.
}
\examples{
data1 <- data.frame(
x = 1:20,
y = 0,
colour = 'forestgreen',
stringsAsFactors = FALSE
)
data2 <- data1
data2$x <- 20:1
data2$y <- 1
data <- tween_states(list(data1, data2), 3, 1, 'cubic-in-out', 100)
}
\seealso{
Other data.frame tween:
\code{\link{tween_along}()},
\code{\link{tween_appear}()},
\code{\link{tween_components}()},
\code{\link{tween_elements}()},
\code{\link{tween_events}()}
}
\concept{data.frame tween}
tweenr/man/dot-max_id.Rd 0000644 0001762 0000144 00000000734 14067576055 014670 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tween_state.R
\name{.max_id}
\alias{.max_id}
\title{Get the highest id occuring in a dataset}
\usage{
.max_id(data)
}
\arguments{
\item{data}{A data.frame as returned by \code{tween_state}}
}
\value{
An integer giving the currently highest id
}
\description{
This is helper for \code{tween_state} related functions to get the currently
highest \code{.id} in a frame collection
}
\keyword{internal}
tweenr/man/tween_appear.Rd 0000644 0001762 0000144 00000003276 14067576055 015321 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tween_appear.R
\name{tween_appear}
\alias{tween_appear}
\title{Tween a data.frame of appearances}
\usage{
tween_appear(data, time, timerange, nframes)
}
\arguments{
\item{data}{A data.frame to tween}
\item{time}{The name of the column that holds the time dimension. This does
not need to hold time data in the strictest sence - any numerical type will
do}
\item{timerange}{The range of time to create the tween for. If missing it
will defaults to the range of the time column}
\item{nframes}{The number of frames to create for the tween. If missing it
will create a frame for each full unit in \code{timerange} (e.g.
\code{timerange = c(1, 10)} will give \code{nframes = 10})}
}
\value{
A data.frame as \code{data} but repeated \code{nframes} times and
with the additional columns \code{.age} and \code{.frame}
}
\description{
This function is intended for use when you have a data.frame of events at
different time points. This could be the appearance of an observation for
example. This function replicates your data \code{nframes} times and
calculates the duration of each frame. At each frame each row is
assigned an age based on the progression of frames and the entry point of in
time for that row. A negative age means that the row has not appeared yet.
}
\examples{
data <- data.frame(
x = rnorm(100),
y = rnorm(100),
time = sample(50, 100, replace = TRUE)
)
data <- tween_appear(data, 'time', nframes = 200)
}
\seealso{
Other data.frame tween:
\code{\link{tween_along}()},
\code{\link{tween_components}()},
\code{\link{tween_elements}()},
\code{\link{tween_events}()},
\code{\link{tween_states}()}
}
\concept{data.frame tween}
tweenr/man/gen_events.Rd 0000644 0001762 0000144 00000005016 14276677372 015004 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gen_events.R
\name{gen_events}
\alias{gen_events}
\title{Generator for tweening the appearance of elements}
\usage{
gen_events(
.data,
ease,
start,
end = NULL,
range = NULL,
enter = NULL,
exit = NULL,
enter_length = 0,
exit_length = 0
)
}
\arguments{
\item{.data}{A data.frame with components at different stages}
\item{ease}{The easing function to use. Either a single string or one for
each column in the data set.}
\item{start, end}{The start (and potential end) of the event encoded in the
row, as unquoted expressions. Will be evaluated in the context of \code{.data} so
can refer to columns in it. If \code{end = NULL} the event will be without extend
and only visible in a single frame, unless \code{enter} and/or \code{exit} is given.}
\item{range}{The range of time points to include in the tween. If \code{NULL} it
will use the range of \code{time}}
\item{enter, exit}{functions that calculate a start state for new observations
that appear in \code{to} or an end state for observations that are not present in
\code{to}. If \code{NULL} the new/old observations will not be part of the tween. The
function gets a data.frame with either the start state of the exiting
observations, or the end state of the entering observations and must return
a modified version of that data.frame. See the \emph{Match, Enter, and Exit}
section for more information.}
\item{enter_length, exit_length}{The lenght of the opening and closing
transitions if \code{enter} and/or \code{exit} is given. Measured in the same units as
\code{time}}
}
\value{
A \code{component_generator} object
}
\description{
This is a generator version of \code{\link[=tween_events]{tween_events()}}. It returns a generator
that can be used with \code{\link[=get_frame]{get_frame()}} and \code{\link[=get_raw_frames]{get_raw_frames()}} to extract frames
for a specific time point scaled between 0 and 1.
}
\examples{
d <- data.frame(
x = runif(20),
y = runif(20),
time = runif(20),
duration = runif(20, max = 0.1)
)
from_left <- function(x) {
x$x <- -0.5
x
}
to_right <- function(x) {
x$x <- 1.5
x
}
gen <- gen_events(d, 'cubic-in-out', start = time, end = time + duration,
enter = from_left, exit = to_right, enter_length = 0.1,
exit_length = 0.05)
get_frame(gen, 0.65)
}
\seealso{
Other Other generators:
\code{\link{gen_along}()},
\code{\link{gen_at}()},
\code{\link{gen_components}()},
\code{\link{gen_keyframe}()}
}
\concept{Other generators}
tweenr/man/tween_components.Rd 0000644 0001762 0000144 00000006016 14276677372 016237 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tween_components.R
\name{tween_components}
\alias{tween_components}
\title{Interpolate individual component}
\usage{
tween_components(
.data,
ease,
nframes,
time,
id = NULL,
range = NULL,
enter = NULL,
exit = NULL,
enter_length = 0,
exit_length = 0
)
}
\arguments{
\item{.data}{A data.frame with components at different stages}
\item{ease}{The easing function to use. Either a single string or one for
each column in the data set.}
\item{nframes}{The number of frames to calculate for the tween}
\item{time}{An unquoted expression giving the timepoint for the different
stages of the components. Will be evaluated in the context of \code{.data} so can
refer to a column from that}
\item{id}{An unquoted expression giving the component id for each row. Will
be evaluated in the context of \code{.data} so can refer to a column from that}
\item{range}{The range of time points to include in the tween. If \code{NULL} it
will use the range of \code{time}}
\item{enter, exit}{functions that calculate a start state for new observations
that appear in \code{to} or an end state for observations that are not present in
\code{to}. If \code{NULL} the new/old observations will not be part of the tween. The
function gets a data.frame with either the start state of the exiting
observations, or the end state of the entering observations and must return
a modified version of that data.frame. See the \emph{Match, Enter, and Exit}
section for more information.}
\item{enter_length, exit_length}{The lenght of the opening and closing
transitions if \code{enter} and/or \code{exit} is given. Measured in the same units as
\code{time}}
}
\value{
A data.frame with the same columns as \code{.data} along with \code{.id} giving
the component id, \code{.phase} giving the state of each component in each frame,
and \code{.frame} giving the frame membership of each row.
}
\description{
This function is much like \code{\link[=tween_elements]{tween_elements()}} but with a slightly different
syntax and support for many of the newer features such as enter/exits and
tween phase identification. Furthermore it uses tidy evaluation for time and
id, making it easier to change these on the fly. The biggest change in terms
of functionality compared to \code{tween_elements()} is that the easing function
is now given per column and not per row. If different easing functions are
needed for each transition then \code{tween_elements()} is needed.
}
\examples{
from_zero <- function(x) {x$x <- 0; x}
data <- data.frame(
x = c(1, 2, 2, 1, 2, 2),
y = c(1, 2, 2, 2, 1, 1),
time = c(1, 4, 10, 4, 8, 10),
id = c(1, 1, 1, 2, 2, 2)
)
data <- tween_components(data, 'cubic-in-out', nframes = 100, time = time,
id = id, enter = from_zero, enter_length = 4)
}
\seealso{
Other data.frame tween:
\code{\link{tween_along}()},
\code{\link{tween_appear}()},
\code{\link{tween_elements}()},
\code{\link{tween_events}()},
\code{\link{tween_states}()}
}
\concept{data.frame tween}
tweenr/man/dot-get_last_frame.Rd 0000644 0001762 0000144 00000001447 14067576055 016405 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tween_state.R
\name{.get_last_frame}
\alias{.get_last_frame}
\alias{.get_first_frame}
\alias{.with_prior_frames}
\alias{.with_later_frames}
\alias{.has_frames}
\title{Helpers for working with tweened data}
\usage{
.get_last_frame(data)
.get_first_frame(data)
.with_prior_frames(prior, new_tween, nframes)
.with_later_frames(later, new_tween, nframes)
.has_frames(data)
}
\arguments{
\item{data, prior, later}{A data.frame. If a \code{.frame} column exists it will be interpreted
as a data.frame containing multiple states}
\item{new_tween}{The result of a tweening}
}
\value{
A data.frame
}
\description{
These are internal helpers for extracting and inserting data into a
data.frame of tweened states.
}
\keyword{internal}
tweenr/man/interpolate_custom_at.Rd 0000644 0001762 0000144 00000000735 14276701255 017242 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gen_keyframe.R
\name{interpolate_custom_at}
\alias{interpolate_custom_at}
\title{Fallback for keyframe vector support}
\usage{
interpolate_custom_at(from, to, at, ease)
}
\arguments{
\item{from, to}{vectors to interpolate between}
\item{at}{value between 0 and 1 defining the point}
\item{ease}{the easing function to use}
}
\description{
Fallback for keyframe vector support
}
\keyword{internal}
tweenr/man/tween_events.Rd 0000644 0001762 0000144 00000005471 14276677372 015362 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tween_events.R
\name{tween_events}
\alias{tween_events}
\title{Transition in and out of events}
\usage{
tween_events(
.data,
ease,
nframes,
start,
end = NULL,
range = NULL,
enter = NULL,
exit = NULL,
enter_length = 0,
exit_length = 0
)
}
\arguments{
\item{.data}{A data.frame with components at different stages}
\item{ease}{The easing function to use. Either a single string or one for
each column in the data set.}
\item{nframes}{The number of frames to calculate for the tween}
\item{start, end}{The start (and potential end) of the event encoded in the
row, as unquoted expressions. Will be evaluated in the context of \code{.data} so
can refer to columns in it. If \code{end = NULL} the event will be without extend
and only visible in a single frame, unless \code{enter} and/or \code{exit} is given.}
\item{range}{The range of time points to include in the tween. If \code{NULL} it
will use the range of \code{time}}
\item{enter, exit}{functions that calculate a start state for new observations
that appear in \code{to} or an end state for observations that are not present in
\code{to}. If \code{NULL} the new/old observations will not be part of the tween. The
function gets a data.frame with either the start state of the exiting
observations, or the end state of the entering observations and must return
a modified version of that data.frame. See the \emph{Match, Enter, and Exit}
section for more information.}
\item{enter_length, exit_length}{The lenght of the opening and closing
transitions if \code{enter} and/or \code{exit} is given. Measured in the same units as
\code{time}}
}
\value{
A data.frame with the same columns as \code{.data} along with \code{.id} giving
the component id, \code{.phase} giving the state of each component in each frame,
and \code{.frame} giving the frame membership of each row.
}
\description{
This tweening function is a more powerful version of \code{\link[=tween_appear]{tween_appear()}}, with
support for newer features such as enter/exits and tween phase
identification. The tweener treats each row in the data as unique events in
time, and creates frames with the correct events present at any given time.
}
\examples{
d <- data.frame(
x = runif(20),
y = runif(20),
time = runif(20),
duration = runif(20, max = 0.1)
)
from_left <- function(x) {
x$x <- -0.5
x
}
to_right <- function(x) {
x$x <- 1.5
x
}
tween_events(d, 'cubic-in-out', 50, start = time, end = time + duration,
enter = from_left, exit = to_right, enter_length = 0.1,
exit_length = 0.05)
}
\seealso{
Other data.frame tween:
\code{\link{tween_along}()},
\code{\link{tween_appear}()},
\code{\link{tween_components}()},
\code{\link{tween_elements}()},
\code{\link{tween_states}()}
}
\concept{data.frame tween}
tweenr/man/tweenr-package.Rd 0000644 0001762 0000144 00000003361 14276677372 015545 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tweenr_package.R
\docType{package}
\name{tweenr-package}
\alias{tweenr}
\alias{tweenr-package}
\title{tweenr: Interpolate Data for Smooth Animations}
\description{
\if{html}{\figure{logo.png}{options: style='float: right' alt='logo' width='120'}}
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.
}
\details{
tweenr is a small collection of functions to help you in creating
intermediary representations of your data, i.e. interpolating states of data.
As such it's a great match for packages such as animate and gganimate, since
it can work directly with data.frames of data, but it also provide fast and
efficient interpolaters for numeric, date, datetime and colour that are
vectorized and thus more efficient to use than the build in interpolation
functions (mainly \code{\link[stats:approxfun]{stats::approx()}} and
\code{\link[grDevices:colorRamp]{grDevices::colorRamp()}}).
The main functions for data.frames are \code{\link[=tween_states]{tween_states()}},
\code{\link[=tween_elements]{tween_elements()}} and \code{\link[=tween_appear]{tween_appear()}}, while the
standard interpolaters can be found at \code{\link[=tween]{tween()}}
}
\seealso{
Useful links:
\itemize{
\item \url{https://github.com/thomasp85/tweenr}
\item Report bugs at \url{https://github.com/thomasp85/tweenr/issues}
}
}
\author{
\strong{Maintainer}: Thomas Lin Pedersen \email{thomasp85@gmail.com} (\href{https://orcid.org/0000-0002-5147-4711}{ORCID})
}
tweenr/man/gen_internal.Rd 0000644 0001762 0000144 00000002117 14106445702 015271 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/aaa.R, R/gen.R, R/gen_keyframe.R
\docType{data}
\name{col_classes}
\alias{col_classes}
\alias{gen_internal}
\alias{PHASE_LEVELS}
\alias{is_generator}
\alias{generator_settings}
\alias{generator_settings<-}
\alias{ease_type}
\alias{ease_type<-}
\alias{col_types}
\alias{col_types<-}
\alias{gen_data}
\alias{gen_data<-}
\alias{gen_to_data_frame}
\alias{data_frame_to_gen}
\alias{keyframes}
\alias{keyframes<-}
\alias{frame_times}
\alias{frame_times<-}
\title{Generator internals}
\format{
An object of class \code{character} of length 5.
}
\usage{
col_classes(data)
PHASE_LEVELS
is_generator(x)
generator_settings(x)
generator_settings(x) <- value
ease_type(x)
ease_type(x) <- value
col_types(x)
col_types(x) <- value
gen_data(x)
gen_data(x) <- value
gen_to_data_frame(...)
data_frame_to_gen(x)
keyframes(x)
keyframes(x) <- value
frame_times(x)
frame_times(x) <- value
}
\arguments{
\item{x}{A generator object}
}
\value{
Various data
}
\description{
Generator internals
}
\keyword{datasets}
\keyword{internal}
tweenr/man/dot-complete_states.Rd 0000644 0001762 0000144 00000001545 14067576055 016623 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tween_state.R
\name{.complete_states}
\alias{.complete_states}
\title{Fill in missing rows using enter and exit functions}
\usage{
.complete_states(from, to, id, enter, exit, max_id)
}
\arguments{
\item{from, to}{Data.frames to tween between}
\item{id}{The name of the column that holds the matching id}
\item{enter, exit}{functions to fill out missing rows in \code{from} and \code{to}
respectively}
}
\value{
A list with the elements \code{from} and \code{to} holding the filled out
versions of \code{from} and \code{to}
}
\description{
This function figures out which rows are missing in either state and applies
the provided \code{enter} and \code{exit} functions to fill in the blanks and provide
a 1-to-1 relation between the rows in \code{from} and \code{to}.
}
\keyword{internal}
tweenr/man/tween_fill.Rd 0000644 0001762 0000144 00000001527 14067576055 014774 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tween_fill.R
\name{tween_fill}
\alias{tween_fill}
\title{Fill out missing values by interpolation}
\usage{
tween_fill(data, ease)
}
\arguments{
\item{data}{A data.frame or vector.}
\item{ease}{A character vector giving valid easing functions. Recycled to
match the ncol of \code{data}}
}
\value{
If \code{data} is a data.frame then a data.frame with the same
columns. If \code{data} is a vector then a vector.
}
\description{
This tween fills out \code{NA} elements (or \code{NULL} elements if \code{data} is a list)
by interpolating between the prior and next non-missing values.
}
\examples{
# Single vector
tween_fill(c(1, NA, NA, NA, NA, NA, 2, 6, NA, NA, NA, -2), 'cubic-in-out')
# Data frame
tween_fill(mtcars[c(1, NA, NA, NA, NA, 4, NA, NA, NA, 10), ], 'cubic-in')
}
tweenr/man/tween_along.Rd 0000644 0001762 0000144 00000003632 14067576055 015145 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tween_along.R
\name{tween_along}
\alias{tween_along}
\title{Interpolate data along a given dimension}
\usage{
tween_along(
.data,
ease,
nframes,
along,
id = NULL,
range = NULL,
history = TRUE,
keep_last = FALSE
)
}
\arguments{
\item{.data}{A data.frame with components at different stages}
\item{ease}{The easing function to use. Either a single string or one for
each column in the data set.}
\item{nframes}{The number of frames to calculate for the tween}
\item{along}{The "time" point for each row}
\item{id}{An unquoted expression giving the component id for each row. Will
be evaluated in the context of \code{.data} so can refer to a column from that}
\item{range}{The range of time points to include in the tween. If \code{NULL} it
will use the range of \code{time}}
\item{history}{Should earlier datapoints be kept in subsequent frames}
\item{keep_last}{Should the last point of each id be kept beyond its time}
}
\value{
A data.frame with the same columns as \code{.data} along with \code{.id} giving
the component id, \code{.phase} giving the state of each component in each frame,
and \code{.frame} giving the frame membership of each row.
}
\description{
This tween takes groups of rows along with the time for each row and
calculates the exact value at each at each frame. Further it allows for
keeping the subsequent raw data from previous frame as well as letting the
final row linger beyond its time. It especially useful for data that should
be visualised as lines that are drawn along the x-axis, but can of course
also be used for other dimensions as well (even dimensions not corresponding
to any axis).
}
\seealso{
Other data.frame tween:
\code{\link{tween_appear}()},
\code{\link{tween_components}()},
\code{\link{tween_elements}()},
\code{\link{tween_events}()},
\code{\link{tween_states}()}
}
\concept{data.frame tween}
tweenr/man/gen_at.Rd 0000644 0001762 0000144 00000003510 14276677372 014101 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gen_at.R
\name{gen_at}
\alias{gen_at}
\title{Generator for interpolating between two data frames}
\usage{
gen_at(from, to, ease, id = NULL, enter = NULL, exit = NULL)
}
\arguments{
\item{from, to}{A data.frame or vector of the same type. If either is of
length/nrow 1 it will get repeated to match the length of the other}
\item{ease}{A character vector giving valid easing functions. Recycled to
match the ncol of \code{from}}
\item{id}{The column to match observations on. If \code{NULL} observations will be
matched by position. See the \emph{Match, Enter, and Exit} section for more
information.}
\item{enter, exit}{functions that calculate a start state for new observations
that appear in \code{to} or an end state for observations that are not present in
\code{to}. If \code{NULL} the new/old observations will not be part of the tween. The
function gets a data.frame with either the start state of the exiting
observations, or the end state of the entering observations and must return
a modified version of that data.frame. See the \emph{Match, Enter, and Exit}
section for more information.}
}
\value{
A \code{keyframe_generator} object
}
\description{
This is a generator version of \code{\link[=tween_at]{tween_at()}} with the additional functionality
of supporting enter and exit functions. It returns a generator that can be
used with \code{\link[=get_frame]{get_frame()}} and \code{\link[=get_raw_frames]{get_raw_frames()}} to extract frames for a
specific time point scaled between 0 and 1.
}
\examples{
gen <- gen_at(mtcars[1:6, ], mtcars[6:1, ], 'cubic-in-out')
get_frame(gen, 0.3)
}
\seealso{
Other Other generators:
\code{\link{gen_along}()},
\code{\link{gen_components}()},
\code{\link{gen_events}()},
\code{\link{gen_keyframe}()}
}
\concept{Other generators}
tweenr/man/gen_keyframe.Rd 0000644 0001762 0000144 00000005260 14276677372 015304 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gen_keyframe.R
\name{gen_keyframe}
\alias{gen_keyframe}
\alias{add_pause}
\alias{add_keyframe}
\title{Generator for keyframe based tweening}
\usage{
gen_keyframe(keyframe = NULL, pause = 0)
add_pause(.data, pause = 0)
add_keyframe(
.data,
keyframe,
ease,
length,
id = NULL,
enter = NULL,
exit = NULL
)
}
\arguments{
\item{keyframe}{A data frame to use as a keyframe state}
\item{pause}{The length of the pause at the current keyframe}
\item{.data}{A data.frame to start from. If \code{.data} is the result of a prior
tween, only the last frame will be used for the tween. The new tween will
then be added to the prior tween}
\item{ease}{The easing function to use. Either a single string or one for
each column in the data set.}
\item{length}{The length of the transition}
\item{id}{The column to match observations on. If \code{NULL} observations will be
matched by position. See the \emph{Match, Enter, and Exit} section for more
information.}
\item{enter, exit}{functions that calculate a start state for new observations
that appear in \code{to} or an end state for observations that are not present in
\code{to}. If \code{NULL} the new/old observations will not be part of the tween. The
function gets a data.frame with either the start state of the exiting
observations, or the end state of the entering observations and must return
a modified version of that data.frame. See the \emph{Match, Enter, and Exit}
section for more information.}
}
\value{
A \code{keyframe_generator} object
}
\description{
This is a generator version of \code{\link[=tween_state]{tween_state()}} and its utility functions. It
returns a generator that can be used with \code{\link[=get_frame]{get_frame()}} and
\code{\link[=get_raw_frames]{get_raw_frames()}} to extract frames for a specific time point scaled between
0 and 1.
}
\examples{
df1 <- data.frame(
country = c('Denmark', 'Sweden', 'Norway'),
population = c(5e6, 10e6, 3.5e6)
)
df2 <- data.frame(
country = c('Denmark', 'Sweden', 'Norway', 'Finland'),
population = c(6e6, 10.5e6, 4e6, 3e6)
)
df3 <- data.frame(
country = c('Denmark', 'Norway'),
population = c(10e6, 6e6)
)
to_zero <- function(x) {
x$population <- 0
x
}
gen <- gen_keyframe(df1, 10) \%>\%
add_keyframe(df2, 'cubic-in-out', 35, id = country, enter = to_zero) \%>\%
add_pause(10) \%>\%
add_keyframe(df3, 'cubic-in-out', 35, id = country, enter = to_zero,
exit = to_zero) \%>\%
add_pause(10)
get_frame(gen, 0.25)
}
\seealso{
Other Other generators:
\code{\link{gen_along}()},
\code{\link{gen_at}()},
\code{\link{gen_components}()},
\code{\link{gen_events}()}
}
\concept{Other generators}
tweenr/man/figures/ 0000755 0001762 0000144 00000000000 14276677320 014013 5 ustar ligges users tweenr/man/figures/logo.png 0000644 0001762 0000144 00000063247 14067576055 015476 0 ustar ligges users PNG
IHDR y X iCCPsRGB IEC61966-2.1 (uKBA?jabP$]@B >jAנ үCu
:AQt\ԥ5O%rwgYJAoAXҢ!\|m EWG#0
^nZTZW"