| network.layout.animate {ndtv} | R Documentation |
Sequentially-stable network layout algorithms suitable for generating network animations.
Description
The network.layout.animate.* layouts are often adaptations or wrappers for existing static layout algorithms with some appropriate presets. They all accept the coordinates of the ‘previous’ layout as an argument so that they can try to construct a suitably smooth sequence of node positions. Usually these layouts are not called directly and instead selected by specifying the appropriate animation.mode argument to compute.animation
Usage
network.layout.animate.kamadakawai(net, dist.mat = NULL, default.dist = NULL,
seed.coords = NULL, layout.par = list(),verbose=FALSE)
network.layout.animate.MDSJ(net, dist.mat = NULL, default.dist = NULL,
seed.coords = NULL, layout.par=list(max_iter=50, dimensions =
2),verbose=TRUE)
network.layout.animate.useAttribute(net, dist.mat = NULL, default.dist = NULL,
seed.coords = NULL, layout.par = list(x = "x", y = "y"), verbose = TRUE)
network.layout.animate.Graphviz(net, dist.mat = NULL, default.dist = NULL,
seed.coords = NULL, layout.par = list(), verbose = TRUE)
Arguments
net |
The network (or temporal sub-network) that will be used to determine vertex positions. |
dist.mat |
A (usually optional) matrix of distances between vertices that should be used to define node positions. This is important to provide if network edge weights need special handling - for example to be fliped from similarities to distances, symmetrized, etc. |
default.dist |
A default distance value which a layout may use to fill in for undefined dyads to space out isolates and disconnected components. |
seed.coords |
A two-column by n-vertex matrix of starting coordinates for the layout to use, usually the coordinates of the previous layout. |
layout.par |
A list of named layout parameters specific to the algorithm. |
verbose |
Print more information about the layout process |
Details
These layouts are generally called by compute.animation on a sequence of extracted networks, with each layout fed the output of the previous layout
Usually if the dist.mat is not included, one will be calculated using the layout.distance function which will compute the geodesic path length distance between nodes after symmetrizing the network and replacing Inf values with either sqrt(network.size) or the passed in default.dist
KamadaKawai
The KamadaKawai option provides resonably good dynamically stable layouts. It computes a symmetric geodesic distance matrix from the input network (replacing infinite values with default.dist, and seeds the initial coordinates for each slice with the results of the previous slice in an attempt to find solutions that are as close as possible to the previous positions. However, it performs poorly on large networks and is not as stable as MDSJ.
See network.layout.kamadakawai for more details about the implementation and parameters
MDSJ
The MDSJ layout uses the MDSJ Java library written by Christian Pich, Algorithmics Group, Department of Computer & Information Science, University of Konstanz, Germany http://algo.uni-konstanz.de/software/mdsj/ (original url), 2009. The library does Multidimensional Scaling (MDS) of the distance matrix using SMACOF optimization. Because MDSJ is released under a creative commons by-nc-sa license it is not distributed with the ndtv package, but an installer is included.
When the MDSJ layout is called it checks for working Java installation, and then checks if MDSJ is installed. If not, it prompts the user and (optionally) downloads and installs MDSJ. If MDSJ is not installed, it falls back to calling the KamadaKawai layout instead.
MDSJ is quite fast for larger networks, but relatively less efficient for smaller ones because of the overhead of system calls and Java start up for each layout. The verbose option prints more information on the Java process. The max_iter parameter sets the maximum of minimization steps the algorithm can try. In cases where it seems like the layout has not completely finished, this can be set higher. The dimensions argument sets the number of dimensions the layout should be performed in and indirectly the number of columns expected and produced for coordinate matrices.
useAttribute
The useAttribute layout makes it possible to define vertex positions using a static or dynamic vertex attributes to provide the x and y coordinates for each time step. The names of the attributes to be used are passed in via the layout.par argument. For example layout.par = list(x = "myX", y = "myY") The attribute must have values defined for each time point that the network plotted.
Graphviz
The Graphviz layout is a wrapper for the Graphviz https://www.graphviz.org software library. If the library is installed on your system (see install.graphviz), it provides a number of additional high-quality layouts. When layout is called it checks for a working Graphviz installation (falling back to KamadaKawai if Graphviz cannot be found) and writes the network to a temp file using export.dot. Then the appropriate Graphviz layout engine (default is neato) is executed via a system call, and the coordinates of the vertices are parsed from the output.
Currently, the arguments to layout.par can be used to specify the Graphviz layout engine to use (i.e. gv.engine='neato' for stress-minimized, gv.engine='dot' for hierarchal, gv.engine='fdp' for force-directed, etc) and additional command-line control parameters can be passed in via gv.args. For example, to use the 'dot' layout, but change layout rank direction to Left-Right: layout.par=list(gv.engine='dot',gv.args='-Grankdir=LR'). See https://graphviz.gitlab.io/doc/info/command.html. Note that Graphviz's graphic rendering parameters are not used to control network plot rendering (but they may impact layout positions).
It is also possible to pass edge attributes of the network directly through to the Graphviz .dot file by passing in the names of the attributes using gv.edge.attrs argument to layout.par. For example, layout.par=list(gv.edge.attrs='len') will write the value of the edge attribute 'len' to a gv attribute 'len', which would control the edge lengths when using neato or fdp https://graphviz.gitlab.io/docs/attrs/len/.
The Graphviz layout normally ignores the values in dist.mat, but for compatibility with other layouts, it is possible to use the values in dist.mat to influence Graphviz's edge length by setting layout.par gv.len.mode='ndtv.distance.matrix' instead of its default 'gv.edge.len'. This writes out all of the possible edges to the file and will overide any other edge attributes.
Value
A two-column by n-vertex matrix of coordinates.
Note
The MDSJ algorithm can only be used for non-comercial projects as it is available under the terms and conditions of the Creative Commons License "by-nc-sa" 3.0. https://creativecommons.org/licenses/by-nc-sa/3.0/
Author(s)
Skye Bender-deMoll
References
Algorithmics Group. MDSJ: Java Library for Multidimensional Scaling (Version 0.2). Available at http://algo.uni-konstanz.de/software/mdsj/. University of Konstanz, 2009.
Kamada, T. and Kawai, S. (1989). An Algorithm for Drawing General Undirected Graphs. Information Processing Letters, 31(1):7-15.
John Ellson et.al (2001) "Graphviz – open source graph drawing tools" Lecture Notes in Computer Science. Springer-Verlag. p483-484 https://www.graphviz.org
See Also
See Also network.layout.kamadakawai,layout.distance,compute.animation