render.d3movie: Render out a web-based animation of a networkDynamic object...

View source: R/render.d3_animation.R

render.d3movieR Documentation

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,...)

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

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

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

Note

This is a very preliminary draft implementation. The animations preform poorly in the Linux Firefox browser, but are ok in Firefox on other platforms and excellent in the Chrome web browser.

Author(s)

skyebend@uw.edu

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/)

See Also

See also the ndtv-d3 vignette https://cran.r-project.org/package=ndtv/vignettes/ndtv.pdf, ndtv workshop https://statnet.org/workshop-ndtv/ndtv_workshop.html, render.animation, compute.animation.

Examples

# render an interactive SVG animation of short.stergm.sim and open it in a browser
data(short.stergm.sim)
render.d3movie(short.stergm.sim)

# render interactive widget in rmarkdown or RStudio plot window
render.d3movie(short.stergm.sim,output.mode='htmlWidget')

# render a static network as interactive SVG with lots of html tooltip info
data(emon)
render.d3movie(emon[[5]],
    vertex.tooltip=paste(emon[[5]]%v%'vertex.names',
      emon[[5]]%v%'Command.Rank.Score',
      emon[[5]]%v%'Sponsorship',
      sep="<br>"),
    edge.tooltip=paste('Frequency:',emon[[5]]%e%'Frequency'),
    edge.lwd='Frequency')

## Not run: 


# alternate code for embeding in rmarkdown
```{r,results='asis'}
render.d3movie(short.stergm.sim,output.mode='inline')
```



## End(Not run)


ndtv documentation built on July 4, 2024, 5:08 p.m.