launchSonia {rSoNIA}R Documentation

function for exporting networks to SoNIA java package

Description

rSoNIA is used to communicate time-based network data with the external SoNIA java package for creating animations of dynamic networks.

Usage

launchSonia(network,
  interactive = TRUE,
  printLaunch = FALSE,
  time.bounds = get.time.bounds(network),
  max.iter=500, 
  movie.file = NULL, 
  movie.type = "mov", 
  usearrows = TRUE, 
  displaylabels = TRUE, 
  vertex.lab = "vertex.names", 
  vertex.col = "red", 
  vertex.x = "0.0", 
  vertex.y = "0.0" ,
  vertex.cex = 10, 
  vertex.shape = "circle",
  arc.col  = "gray",
  layout.type = "MultiComp KK Layout", 
  soniaPath = paste(rSoniaLoc(),"sonia_1_1_5.jar",sep=""),
  verbose=FALSE)

Arguments

network network of class dynamicnetwork containing data to be exported
interactive toggles interactive application or direct export
printLaunch if true, the command string passed to the system() call will also be printed to the terminal for debugging
time.bounds the start and end time for the movie (default calcs from data)
max.iter the maximum number of iterations the layout algorithm will be allowed
movie.file file name (including path, but without extension) for exported movie file for direct export
movie.type file type, determines export format used. 'mov' = QuickTime movie, 'swf' = Flash animation
usearrows boolean indicating if arrows should be shown, overides option in soniaGraphicsSettings
displaylabels boolean indicating if labels should be shown, overrides option in soniaGraphicsSettings
vertex.lab name of a vertex attribute containing labels
vertex.col an R color name, or name of vertex attribute containing colors
vertex.x name of an attribute containing x coords to use as starting positions
vertex.y names of an attribute containing y coords to use as starting positions
vertex.cex size of vertices or name of vertex attribute containing sizes
vertex.shape a shape name (currently only "circle" or "square") or the name of a vertex attribute containing shape names
arc.col an R color name, or the name of an edge attribute containing colors
layout.type full name of the layout algorithm to use (see below)
soniaPath full path (including file name)to SoNIA java executable to be used, default is to search library trees
verbose boolean indicating of SoNIA should be set to verbose mode so that all status and log messages will be printed to the R terminal

Details

Launches a java program using the {external} command. Requires that Java 1.5+ and the SoNIA libraries are installed (including QuickTime) Most arguments behave somewhat differently than the R standard in that they usually give the name of the variable to be used rather than accepting a vector of values. This is to allow the use of dynamic attributes. However, if the value of a size or color attribute does not match with a variable name, SoNIA will try to parse the value. (which is why the defaults are "circle", "red" ,etc)

Currently can use launch with the following SoNIA layout algorithms (in interactive mode, the algorithm can be changed):

Almost all the parameters in SoNIA (except, for the moment, some crucial ones like the max iterations of the algorithms, and the cooling params) can be set from R by modifying directly the values of the key values pairs sorted in the various sonia...Settings objects. For example:

soniaLayoutSettings$slice.duration[2] <- "0.5". good luck !

Due to somewhat strange fileformat problems, the flash (swf) export will only output movies of a limited size (total number of 65535 arcs, including interpolations, drawn to screen) after which it will begin to recycle drawing elements, making the remaining movie useless.

Value

Writes an animation as QuickTime movie (.mov) for Flash Animation (.swf) to the file system. Does not return an object, but prints text to the console reporting the export process and giving error messages. Uses an intermediate cache file to pass network data.

Warning

This is pre-alpha code and is very unstable

Note

The connection to SoNIA is fairly crude. The dynamic.network object is deparsed and passed in a temp file, along with the control values as arguments, in a commandline call using the system function.

Author(s)

Skye Bender-deMoll skyebend@skyeome.net, CSDE statnet team

References

SoNIA website http://sonia.stanford.edu (add paper cites)

See Also

http://www.stanford.edu/group/sonia/documentation/r documentation for the dynamicnetwork package soniaGraphicsSettings soniaBrowseSettings soniaApplySettings soniaMovieSettings soniaParseSettings soniaLayoutSettings

Examples

             ## Not run: 
#BASIC EXAMPLE
#this example will only work after updateSonia() has been run
# to install the java components of the package.
data(fauxSim); # load simulation from fauxHigh ergm
fauxDyn <- as.dynamic(fauxSim); #convert to dynamic.network object
launchSonia(fauxDyn) # launch sonia in interactive mode

#MORE COMPLEX EXAMPLE
#load statnet to do simulation
library(statnet);
data(fauxhigh);
#define a basic model as in statnet example
#this is very slow!
fauxModel <- ergm(fauxhigh ~ edges + nodefactor("Grade") + nodefactor("Race") +nodefactor("Sex") + nodematch("Grade",diff=T) +nodematch("Race",diff=T) + nodematch("Sex",diff=F) + gwdegree(1.0,fixed=T) + gwesp(1.0,fixed=T) + gwdsp(1.0,fixed=T) );
#simulate 20 networks in sequence, seperated by 1000 toggle tries
fauxSim2 <- simulate(fauxModel,nsim=20,interval=1000);
#convert list of networks from ergm into dynamic network object
fauxDyn1000<- as.dynamic(fauxSim2,check.renewal=FALSE);

#convert sex into a vertex attribute of shape names
shapes <- get.vertex.attribute(fauxDyn1000,"Sex");
shapes <- replace(shapes,shapes==1,"square");
shapes <- replace(shapes,shapes==2,"circle");
fauxDyn1000 <- set.vertex.attribute(fauxDyn1000,"shapes",shapes);

#convert race into a vertex attribute of aribrary colors
set.vertex.attribute(fauxDyn1000,"color",colorize(get.vertex.attribute(fauxDyn1000,"Race")));

#modify some of the settings to be used by sonia for the movie
soniaApplySettings$kk.opt.dist[2]<-25;     #specify node spacing
soniaApplySettings$kk.comp.connect[2] <- 10;     #specify distance betweeen components
soniaGraphicsSettings$layout.height[2]<-500; #increase height of movie

#launch sonia and save out quicktime movie to user specified dir and file name
#quicktime movie only works on macs or windows machines
#movie file will be ~18 Mb! (very high quality, can be compressed later)
launchSonia(fauxDyn1000,
max.iter=5000,
interactive=FALSE,
vertex.col="color",
usearrows=FALSE,
displaylabels=FALSE,
vertex.shape="shape",
vertex.cex="Grade",
movie.file=file.choose(),
movie.type="mov");  
  
#decrease the number of 'tweening  frames
soniaBrowseSettings$num.frames[2]<-10;
#export .swf (flash) version of movie, ~700 Kb
#this should work on all platforms, but only for short movies
launchSonia(fauxDyn1000,
max.iter=5000,
interactive=FALSE,
vertex.col="color",
usearrows=FALSE, 
displaylabels=FALSE,
vertex.shape="shape",
vertex.cex="Grade",
movie.file=file.choose(),
movie.type="swf");

      ## End(Not run)  

[Package rSoNIA version 0.0-4 Index]