R: Compose tweening between states

tween_state {tweenr} | R Documentation

## Compose tweening between states

### Description

The `tween_state()` is a counterpart to `tween_states()` that is aimed at letting you gradually build up a scene by composing state changes one by one. This setup lets you take more control over each state change and allows you to work with datasets with uneven number of rows, flexibly specifying what should happen with entering and exiting data. `keep_state()` is a simpel helper for letting you pause at a state. `open_state()` is a shortcut from tweening from an empty dataset with a given `enter()` function while `close_state()` is the same but will instead tween into an empty dataset with a given `exit()` function.

### Usage

    tween_state(.data, to, ease, nframes, id = NULL, enter = NULL, exit = NULL)

    keep_state(.data, nframes)

    open_state(.data, ease, nframes, enter)

    close_state(.data, ease, nframes, exit)

### Arguments

`.data` | A data.frame to start from. If `.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
`to` | A data.frame to end at. It must contain the same columns as .data (exluding `.frame`)
`ease` | The easing function to use. Either a single string or one for each column in the data set.
`nframes` | The number of frames to calculate for the tween
`id` | The column to match observations on. If `NULL` observations will be matched by position. See the Match, Enter, and Exit section for more information.
`enter, exit` | functions that calculate a start state for new observations that appear in `to` or an end state for observations that are not present in `to`. If `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 Match, Enter, and Exit section for more information.

### Value

A data.frame containing all the intermediary states in the tween, each state will be enumerated by the `.frame` column

### Match, Enter, and Exit

When there are discrepancies between the two states to tweeen between you need a way to resolve the discrepancy before calculating the intermediary states. With discrepancies we mean that some data points are present in the start state and not in the end state, and/or some are present in the end state but not in the start state. A simple example is that the start state contains 100 rows and the end state contains 70. There are 30 missing rows that we need to do something about before we can calculate the tween.

Making pairs The first question to answer is "How do we know which observations are disappearing (exiting) and/or appearing (entering)?". This is done with the `id` argument which should give a column name to match rows between the two states on. If `id = NULL` the rows will be matched by position (in the above example the last 30 rows in the start state will be entering). The `id` column must only contain unique values in order to work.

Making up states Once the rows in each state has been paired you'll end up with three sets of data. One containing rows that is present in both the start and end state, one containing rows only present in the start state, and one only containing rows present in the end state. The first group is easy - here you just tween between each rows - but for the other two we'll need some state to start or end the tween with. This is really the purpose of the `enter` and `exit` functions. They take a data frame containing the subset of data that has not been matched and must return a new data frame giving the state that these rows must be tweened from/into. A simple example could be an `enter` function that sets the variable giving the opacity in the plot to 0 - this will make the new points fade into view during the transition.

Ignoring discrepancies The default values for `enter` and `exit` is `NULL`. This value indicate that non-matching rows should simply be ignored for the transition and simply appear in the last frame of the tween. This is the default.

### Examples

    data1 <- data.frame(
      x = 1:20,
      y = 0,
      colour = 'forestgreen',
      stringsAsFactors = FALSE
    )
    data2 <- data1
    data2$x <- 20:1
    data2$y <- 1

    data <- data1 %>%
      tween_state(data2, 'linear', 50) %>%
      keep_state(20) %>%
      tween_state(data1, 'bounce-out', 50)

    # Using enter and exit (made up numbers)
    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
    }
    pop_devel <- df1 %>%
      tween_state(df2, 'cubic-in-out', 50, id = country, enter = to_zero) %>%
      tween_state(df3, 'cubic-in-out', 50, id = country, enter = to_zero,
                  exit = to_zero)

[Package tweenr version 1.0.2 Index]