render.d3movie: Render out a web-based animation of a networkDynamic object using ndtv-d3 player app

Description

Exports a self-contained HTML file including an SVG animation of the networkDynamic object and displays it in a web browser. See render.animation for details of animation construction.

Usage

render.d3movie(net, filename=tempfile(fileext = '.html'), 
                           render.par=list(tween.frames=10,
                                           show.time=TRUE,
                                           show.stats=NULL,
                                           extraPlotCmds=NULL,
                                           initial.coords=0),
                           plot.par=list(bg='white'),
                           d3.options, 
                           output.mode=c('HTML','JSON','inline','htmlWidget'),
                           script.type=c('embedded','remoteSrc'),
                           launchBrowser=TRUE,
                           verbose=TRUE,...)

Value

If output.mode='HTML', a file will be generated including the necessary javascript and JSON data structures If output.mode='JSON', a JSON file will be generated including a section describing all of the rendered slices, and a seperate section including the entire networkDynamic object. If output.mode='inline', HTML code for an iframe elment suitible for embedding in markdown documents will be printed, all other output supressed. If output.mode='htmlWidget', a htmlwidgets object will be returned which, will produce appropriate html when 'printed' or emedded in a Shiny app

Arguments

net

The network (usally networkDynamic) object to be rendered, usually containing pre-computed vertex positions as dynamic attributes cached by compute.animation

filename

The file name of the HTML or JSON file to be generated. Must end the proper file extension ('.json' for JSON '.html' for HTML) for correct browser display.

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 main for background color, margins, fonts, etc. MANY OF THESE ARE NOT YET SUPPORTED BY THE NDTV-D3 PLAYER. See list in Details below.

d3.options

list of options to configure ndtv-d3 player app. list( animationDuration=800, scrubDuration=0, enterExitAnimationFactor=0, nodeSizeFactor=0.01, playControls=TRUE, animateOnLoad=FALSE, slider=TRUE, debugFrameInfo=FALSE, debugDurationControl=FALSE, ) See Details below for explanations

output.mode

character string, one of 'HTML','JSON' or 'inline'. The first exports an HTML file with embedded javascript player app including the JSON data structure describing the animation. The second just exports the JSON data structure (for loading into an existing page). The 3rd renders the HTML inside an iframe tag and supresses all other output in an attempt to make it embedable in rmarkdown documents. The 4th generates a htmlWidget suitable for displaying in an RStudio plot window or Shiny app.

script.type

if script.type='embedded', the scripts will be embedded directly in the output html page. This option is the most portable, but will require large file sizes. If script.type='remoteSrc', only the links to the scripts will be included, so the page will require an active internet connection to play the animation.

launchBrowser

if TRUE, after exporting the file R will attempt to open it in a browser

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. NOT ALL PLOT PARAMS ARE IMPLEMENTED YET

Author

skyebend@uw.edu

Details

Animations are generated using a process nearly identical to render.animation. However, instead of using R's plotting functions and the animation library, the relevant information is cached and written into a JSON-formatted file, embedded into a web page along with ndtv-d3 player, and displayed in a web browser as an interactive HTML5 SVG animation.

The ndtv-d3 player app is not a fully-featured R plot device. It only attempts to emulate the elements of plot normally used by plot.network and it understands the graphic elements and a somewhat higher level so that it will be able to handle interaction with edge and vertex objects.

However, ndtv-d3 includes several nice features to support exploring the network:

controller buttons for playing, pausing and stepping through the animation
time slider for jumping and 'scrubing' to parts of the movie
pan and zoom into the network using the mouse-wheel
click on vertices and edges to reveal their ids or abitrary text attached using the vertex.tooltip and edge.tooltip properties
double-click on a vertex to highlight all of the connected edges and vertices

If passed a static network, by default only a single slice will be rendered and the time slider and controllers will be disabled. For consistency with plot.network the static mode also supports passing in a matrix of coordinates via coord argument which will prevent the default call to compute.animation.

Another advantage of ndtv-d3 is that it does not require installing system libraries such as ffmpeg to render out the movie.

The coordinates for vertex postitions are read from the animation.x and animation.y TEA attributes, normally created using compute.animation

The list of currently supported plot,plot.network and par elements is

xlab: : label caption below the render, on the xaxis
main: : main headline above the render
displaylabels: : should vertex labels be displayed?
usearrows: : should arrows be drawn on edges?
bg: : background color (must be html compatible? need to check this)
vertex.cex: : vertex expansion scale factor
label: : labels for vertices (defaults to vertex.names)
label.col: : color of vertex labels
label.cex: : vertex label expansion scale factor
vertex.col: : vertex fill colors
vertex.sides: : number of sides for vertex polygon (shape)
vertex.rot: : rotation for vertex polygon
vertex.border: : color of vertex border stroke
vertex.lwd: : width of vertex border stroke
edge.lwd: : width of edge stroke
edge.col: : edge stroke color

All of the above properties can be defined as dynamic (TEA) attributes. Noteably, curved edges, edge labels, and label positioning are not yet implemented and will be ignored. The main and xlab params will not be positioned exactly as they are in plot

There are a few special plot parameters that are only supported by render.d3move:

vertex.tooltip: arbitrary text or html to be displayed when a vertex is clicked (default is the vertex id)
edge.tooltip: arbitrary text or html to be displayed when an edge is clicked (default is the edge id)
vertex.css.class: properties for adding arbitrary class attributes for use in CSS styling of vertices
edge.css.class: properties for adding arbitrary class attributes for use in CSS styling of edges
vertex.label.css.class: properties for adding arbitrary class attributes for use in CSS styling of vertex labels

ndtv-d3 has its own configuration properties passed in via the d3.options argument list, shown below with their default properties. Values which are set to NULL or omitted will be set to the ndtv-d3 player defaults.

animationDuration=800: Duration (milliseconds) of each animation step during play or step actions
enterExitAnimationFactor=0: Fraction (0-1) of total step animation time that edge enter/exit animations should take
nodeSizeFactor=0.01: Sets default node (vertex) size, as a fraction of viewport size.
playControls=TRUE: Show the player controls (play, pause, step, etc)
animateOnLoad=FALSE: If true, animation will start playing as soon as page loads.
slider=TRUE: Show the time slider control
margin=list(x=20,y=10): SVG margins - may be overridden when setting fixed aspect ratio
debugFrameInfo=FALSE: Show the slice timing info in corner
durationControl=TRUE: Show a control to change speed of animation under the menu in the upper right corner

References

The github repository for the ndtv-d3 javascript library is at https://github.com/statnet/ndtv-d3/ (which is the statnet release fork of https://github.com/michalgm/ndtv-d3/)