R/transmute-.R, R/transmute-enter.R, R/transmute-exit.R
enter_exit.RdThe purpose of enter_*() and exit_*() is to control what happens with
data that does not persist during a tween. In general the non-persistent data
is transformed to an invisible version that can be tweened to, e.g. by
setting the opacity to 0 or be moving the element off-screen. It is possible
to define your own transformations, or rely on some of the build in
effects.
enter_manual(default = NULL, ..., name = "manual")
enter_appear(early = FALSE, ...)
enter_fade(..., alpha = 0)
enter_grow(..., size = 0)
enter_recolour(..., colour = "white", fill = colour)
enter_recolor(..., color = "white", fill = color)
enter_fly(..., x_loc = NA, y_loc = NA)
enter_drift(..., x_mod = 0, y_mod = 0)
enter_reset()
exit_manual(default = NULL, ..., name = "manual")
exit_disappear(early = FALSE, ...)
exit_fade(..., alpha = 0)
exit_shrink(..., size = 0)
exit_recolour(..., colour = "white", fill = colour)
exit_recolor(..., color = "white", fill = color)
exit_fly(..., x_loc = NA, y_loc = NA)
exit_drift(..., x_mod = 0, y_mod = 0)
exit_reset()A default transformation to use
Additional specific transformations either named by the geom
(e.g. bar, or by its position in the layer stack, e.g. "2")
A name for the manual modification (only used when printing the object)
Should the data appear in the beginning of the transition or in the end
The start/end transparency.
The proportional start/end size. 0 means complete shrinking
while 1 means no shrinking
The start/end colour and fill the elements should (dis)appear into
Start and end positions of the graphic elements
Modification to add to the entering or exiting data
All enter/exit functions allows the user to add additional transformation functions targeting specific layers. If the functions are named, then the name is understood to reference the class of geoms it applies to. If the functions are unnamed or numbered they will apply to the layer with a matching index in the stack. Named and indexed transformations cannot be mixed.
All modifications except enter_manual()/exit_manual() sets a range of
modifications already, but further can be added with the .... For the
manual versions a default transformation can be set which will apply to all
layers that does not match any of the other given transformations. Often a
single default transformation is enough and no specific transformations are
needed.
Transformation can be given as any expression that can be converted with
rlang::as_function(). This means that purrr style lambda functions are
allowed in addition to anonymous functions etc. Transformation functions must
accept a data.frame and return a data.frame of the same dimensions. The
function will be called with the entering/exiting layer data, except for the
case of polygon- and path-like layers in which case the function recieves the
entering/exiting polygon/path data one by one. A special option is to set a
transformation as NULL instead of a function. In that case the entering and
exiting data will simply appear/disappear when it is no longer part of a
frame.
Enter and exit modifications are composable so that multiple different ones
can be added to an animation and will be applied in turn. You can also
combine multiples and save them as a new enter or exit modification using
c().
Due to the composable nature of enter and exit modifications it is not
possible to overwrite a prior modification by adding a new. If it is needed
to start from scratch then the sentinels enter_reset() and exit_reset()
are provided which clears all prior modifications.
A range of modification types are provided by gganimate and using
enter_manual()/exit_manual() or modification composition it is possible
to create your own.
appear/disappear will simply make elements appear/disappear at either the start or end of the transition. The default if nothing else is added.
fade will simply set the alpha value to zero making the elements fade in/out during the transition.
grow/shrink will set the elements to zero size making them gradually grow into / shrink out of existence. Zero size depends on the type of layer, e.g. polygons/paths will have all their points set to the mean, while points will have size/stroke set to zero.
recolour/recolor will change the colour and/or fill of the elements making them gradually change from the defined colour and into their try colour. Be aware that unless the colour and fill are set to the same as the background colour of the plot this modification needs to be combined with others to ensure that elements does not abruptly appear.
fly will set a specific x and y position where all elements will enter from/ exit to, irrespectible of their real position.
drift will modify the real position of the entering and exiting elements
by a specified amount, e.g. setting x_mod = -5 will let all elements enter
from/exit to the left with a terminal position 5 points to the left of the
real position.
# Default is appear/disappear
anim <- ggplot(mtcars, aes(factor(gear), mpg)) +
geom_boxplot() +
transition_states(gear, 2, 1)
# Fade-in, fly-out
anim1 <- anim +
enter_fade() +
exit_fly(x_loc = 7, y_loc = 40)
# Enter and exit accumulates
anim2 <- anim +
enter_fade() + enter_grow() +
exit_fly(x_loc = 7, y_loc = 40) + exit_recolour(fill = 'forestgreen')