render.animation: Render animations of `networkDynamic` objects as movies in various formats

Description

Takes a network object which describes a sequence of changes in properties of a network and graphically renders it out as a sequence of plots to create an animation. Normally the coordinates determining the vertex positions at specified time points should have been calculated and stored in the network object, along with the slice.par list of parameters describing when and how the network should be divided up in time. If the coordinate data is not found, compute.animation will be called with default arguments.

Appropriate `static' networks for each time region will be generated by network.collapse. The rendering of each frame is drawn by plot.network and most arguments are supported and are passed through to control the details of rendering. The rendered images are stored using the animation package and can be played in the plot window (ani.replay) or saved to a movie file with saveVideo.

Usage

render.animation(net, render.par = list(tween.frames = 10, show.time = TRUE, 
            show.stats = NULL, extraPlotCmds=NULL, initial.coords=0),
            plot.par = list(bg='white'), ani.options = list(interval=0.1), 
            render.cache = c('plot.list','none'), verbose=TRUE, ...)

Value

A sequence of plots will be generated on the active plot device. If render.cache='plot.list' the recorded plots are stored as a list in .ani.env$.images.

Arguments

net

The networkDynamic object to be rendered, usually containing pre-computed vertex positions as dynamic attributes.

render.par

Named list of parameters to specify the behavior of the animation.

tween.frames the number of interpolated frames to generate between each calculated network layout (default 10).
show.time If TRUE, labels the plot with onset and terminus time for each slice.
show.stats NULL, or a string containing a formula to be passed to summary.stergm to display the network statistics for the current slice on the plot. e.g. "~edges+gwesp(0,fixed=TRUE)"
extraPlotCmds NULL, or additional plot commands to draw on each frame of the animation.
initial.coords default initial coords to be assigned to vertices. Can be a two-column numeric coordinate matrix, or a numeric values to be formed into a matrix.

plot.par

list of `high-level' plotting control arguments to be passed to par. e.g. bg for background color, margins, fonts, etc.

ani.options

list of control arguments for the animation library. For example. interval controls the delay between frames in playback, ani.dev and ani.type can be used to set non-default graphics devices for rendering (i.e 'jpeg' instead of 'png'). See ani.options

render.cache

the default value of 'plot.list' causes each frame of the animation to be cached in an internal list by the ani.record function of the animation library. This is very useful for testing and replaying animations in R's plot window, but can be very slow (or cause out-of-memory errors) for large animations. If the value is set to 'none', the plot will not be recorded (but can be saved to disk via saveVideo, see examples below) and cannot be replayed via the ani.replay() function.

verbose

If TRUE, update text will be printed to the console to report the status of the rendering process.

...

Other parameters to control network rendering. See plot.network.default. Most parameters can be set to TEA attribute names, or specified as a function to be evaluated at each timestep

Author

Skye Bender-deMoll, and the statnet team.

Details

Most of the network plotting arguments are passed directly to plot.network.default. All of the plot.network arguments pased in via ... can be specified as a TEA or special type of function to be evaluated at each time step. For example, if there was a dynamic vertex attribute named 'wealth', it could be mapped to vertex size by providing the TEA name vertex.cex='wealth'. If the wealth value needed transformation to be an appropriate vertex size, it can be specified as a function: vertex.cex=function(slice){slice%v%'wealth'*5-3}

The arguments of plot control functions must draw from a specific set of named arguments which will be substituted in and evaluated at each time point before plotting. The set of valid argument names is:

net is the original (uncollapsed) network
slice is the network collapsed with the appropriate onset and terminus
s is the slice number
onset is the onset (start time) of the slice to be rendered
terminus is the terminus (end time) of the slice to be rendered

A few of the plot parameters have defaults that are different from the ones given by plot.network:

jitter defaults to FALSE to prevent unwanted bouncing
xlim and ylim default to the ranges of the entire set of network coordinates. Although they can be set to function values for interesting effects...
xlab defaults to a function to display the time range: function(onset,terminus){paste("t=",onset,"-",terminus,sep='')}. It also will be overidden if show.stats is set.

If no slice.par network attribute is found to define the time range to render, it will make one up using the smallest and largest non-Inf time values, unit-length non-overlapping time steps and an aggregation rule of 'latest'.

If no dynamic coordinate information has been stored, compute.animation will be called with default values to try to do the layout before giving up.

Additional plot commands passed in via the extraPlotCmds argument will be passed to eval() after each frame is rendered and can be used to add extra annotations to the plot.

One some installations, the default output from saveVideo() (really ffmpeg) produces videos in a slightly non-standard .mp4 format that won't play in Windows Media Player or QuickTime. Users have reported that adding the argument other.opts='-pix_fmt yuv420p" to saveVideo corrects the problem. Recent versions of the animation library will include this argument by default.

To avoid performance issues with the RStudio graphics device, RStudio users will see a message that ndtv is attempting to open another type of plot window. It will try to guess a platform-appropriate device type, but specific device can be pre-specified by the user by setting the R_DEFAULT_DEVICE environment variable

References

Skye Bender-deMoll and McFarland, Daniel A. (2006) The Art and Science of Dynamic Network Visualization. Journal of Social Structure. Volume 7, Number 2 https://www.cmu.edu/joss/content/articles/volume7/deMollMcFarland/

Examples

Run this code


require(ndtv)
# trivial example

triangle <- network.initialize(3) # create a toy network
add.edge(triangle,1,2)
# add an edge between vertices 1 and 2
add.edge(triangle,2,3)
# add a more edges
activate.edges(triangle,at=1) # turn on all edges at time 1 only
activate.edges(triangle,onset=2, terminus=3,
e=get.edgeIDs(triangle,v=1,alter=2))
add.edges.active(triangle,onset=4, length=2,tail=3,head=1)
render.animation(triangle)
ani.replay() 

# an example with changing TEA attributes
wheel <- network.initialize(10)  # create a toy network
add.edges.active(wheel,tail=1:9,head=c(2:9,1),onset=1:9, terminus=11)
add.edges.active(wheel,tail=10,head=c(1:9),onset=10, terminus=12)
# set a dynamic value for edge widths
activate.edge.attribute(wheel,'width',1,onset=0,terminus=3) 
activate.edge.attribute(wheel,'width',5,onset=3,terminus=7)
activate.edge.attribute(wheel,'width',10,onset=3,terminus=Inf)
# set a value for vertex sizes
activate.vertex.attribute(wheel,'mySize',1, onset=-Inf,terminus=Inf)
activate.vertex.attribute(wheel,'mySize',3, onset=5,terminus=10,v=4:8)
# set values for vertex colors
activate.vertex.attribute(wheel,'color','gray',onset=-Inf,terminus=Inf)
activate.vertex.attribute(wheel,'color','red',onset=5,terminus=6,v=4)
activate.vertex.attribute(wheel,'color','green',onset=6,terminus=7,v=5)
activate.vertex.attribute(wheel,'color','blue',onset=7,terminus=8,v=6)
activate.vertex.attribute(wheel,'color','pink',onset=8,terminus=9,v=7)
# render it all
render.animation(wheel,edge.lwd='width',vertex.cex='mySize',vertex.col='color')


# an example with functional attributes
set.network.attribute(wheel,'slice.par',
           list(start=1,end=10,interval=1, aggregate.dur=1,rule='latest'))
# render vertex size as betweeness
render.animation(wheel,vertex.cex=function(slice){(betweenness(slice)+1)/5})


# render it directly to a movie file without caching the plots (faster)
if (FALSE) {
saveVideo( render.animation(wheel,edge.lwd='width',vertex.cex='mySize',vertex.col='color',
           render.cache='none') )
}

# simulation based example
# disabled to save time when testing
if (FALSE) {
require(tergm)
# load in example data, results of a basic stergm sim
data(stergm.sim.1)

# (optional) pre-compute coordinates for set time range
# (optional) limit time range to a few steps to speek example
slice.par=list(start=0,end=10,interval=1, aggregate.dur=1,rule='latest')
compute.animation(stergm.sim.1,slice.par=slice.par)


# define the number of inbetween frames and a formula for stats to display
render.par<-list(tween.frames=5,show.time=TRUE,
                show.stats="~edges+gwesp(0,fixed=TRUE)")
                
# render the movie, with labels, smaller vertices, etc
render.animation(stergm.sim.1,render.par=render.par,
                 edge.col="darkgray",displaylabels=TRUE,
                 label.cex=.6,label.col="blue")
                 
# preview the movie in the plot window
ani.replay()     

# save the movie as mp4 compressed video (if FFMPEG installed)
saveVideo(ani.replay(),video.name="stergm.sim.1.mp4", 
           other.opts="-b 5000k",clean=TRUE)
}

Run the code above in your browser using DataLab