animate: General function for creating animated graphics from a...

In joey711/animate.phyloseq: Animation tools to complement the phyloseq package

Description

Proper function depends entirely on the animation-package, and details regarding customization options can be found in its documentation. In particular, the ani.options function can be called beforehand to make animnation-related adjustments, analogous to the way par can be called for base graphics. Similarly, most arguments to ani.options can be provided as additional named arguments and will be passed on to ani.options via ....

Usage

  animate(df, t=colnames(df)[1], x=colnames(df)[2],
    y=colnames(df)[3], color=NULL, shape=NULL,
    ggplot2_expr=NULL, movie.name="animation.gif", ...)

Arguments

df	(Required). A data.frame that contains covariates that can be mapped to time, as well as two additional axes.
t	(Recommended). A character-class. The name of the time variable in df. Default is the name of the first column, colnames(df)[1].
x	(Recommended). A character-class. The name of the variable in df that will be mapped to the horizontal axis. Default is the name of the second column, colnames(df)[2].
y	(Recommended). A character-class. The name of the variable in df that will be mapped to the vertical axis. Default is the name of the third column, colnames(df)[3].
color	(Optional). A character-class. The name of the variable in df that will be mapped to color. Default is NULL (no color mapping).
shape	(Optional). A character-class. The name of the variable in df that will be mapped to shape. Default is NULL (no shape mapping).
ggplot2_expr	(Optional). A character-class. A single (potentially long) character string that is a ggplot2 expression for additional graphical layers/options. For example, the following ggplot2 expression, if provided, would cause each frame to be faceted in a wrap by the Subject factor with 3 rows, and also use the black and white theme: "facet_wrap(~Subject, nrow=3) + theme_bw()"
movie.name	(Optional). A character string of the desired name for the output movie file. Default is "animation.gif"
...	(Optional). Additional arguments passed to ani.options.

Details

Since this is an animation, one of the most important arguments is t, which specifies the variable within the data.frame (df) that represents time. This will be coerced to a numeric, and each unique value will be treated as a separate time-step within the resulting animation. Note that in most cases it should not be necessary to translate your time measurement into time step integers, so long as the values of t are coerceable to a numeric that represents the correct order. If your time variable is a date represented by the Date class, it will probably work fine. If in doubt, however, check that the following code provides the correct order of values.

as(df[, t], "numeric")

Similarly, the number of frames in the animation will be equal to

length(unique(as(df[, t], "numeric")))

so check that this value is what you need/expect.

Value

A .gif animation file. Support is planned for other output file types supported by animation.

References

http://cran.r-project.org/web/packages/animation/animation.pdf

See Also

animation

Examples

##### Define arbitrary, simple "data"
# x=1:10; y=x; t=x; sdf <- data.frame(x, y, t)
##### Make animation using animate() function:
# animate(sdf, "t", "x", "y")
##### Try an alternative "by hand" using base graphics:
# saveMovie(	for(i in t){
#	plot(subset(sdf, t<=i)[, c("x", "y")],
#			 xlim=c(min(sdf$x), max(sdf$x)),
#			 ylim=c(min(sdf$y), max(sdf$y))
#			 )
# })
#########

joey711/animate.phyloseq documentation built on May 19, 2019, 3:01 p.m.